1 /*
2  * Copyright (c) 2014-2016, NVIDIA CORPORATION.  All rights reserved.
3  *
4  * This program is free software; you can redistribute it and/or modify it
5  * under the terms and conditions of the GNU General Public License,
6  * version 2, as published by the Free Software Foundation.
7  *
8  * This program is distributed in the hope it will be useful, but WITHOUT
9  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
11  * more details.
12  *
13  * You should have received a copy of the GNU General Public License
14  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
15  */
16 
17 #ifndef _ABI_BPMP_ABI_H_
18 #define _ABI_BPMP_ABI_H_
19 
20 #ifdef LK
21 #include <stdint.h>
22 #endif
23 
24 #ifndef __ABI_PACKED
25 #define __ABI_PACKED __attribute__((packed))
26 #endif
27 
28 #ifdef NO_GCC_EXTENSIONS
29 #define EMPTY char empty;
30 #define EMPTY_ARRAY 1
31 #else
32 #define EMPTY
33 #define EMPTY_ARRAY 0
34 #endif
35 
36 #ifndef __UNION_ANON
37 #define __UNION_ANON
38 #endif
39 /**
40  * @file
41  */
42 
43 
44 /**
45  * @defgroup MRQ MRQ Messages
46  * @brief Messages sent to/from BPMP via IPC
47  * @{
48  *   @defgroup MRQ_Format Message Format
49  *   @defgroup MRQ_Codes Message Request (MRQ) Codes
50  *   @defgroup MRQ_Payloads Message Payloads
51  *   @defgroup Error_Codes Error Codes
52  * @}
53  */
54 
55 /**
56  * @addtogroup MRQ_Format Message Format
57  * @{
58  * The CPU requests the BPMP to perform a particular service by
59  * sending it an IVC frame containing a single MRQ message. An MRQ
60  * message consists of a @ref mrq_request followed by a payload whose
61  * format depends on mrq_request::mrq.
62  *
63  * The BPMP processes the data and replies with an IVC frame (on the
64  * same IVC channel) containing and MRQ response. An MRQ response
65  * consists of a @ref mrq_response followed by a payload whose format
66  * depends on the associated mrq_request::mrq.
67  *
68  * A well-defined subset of the MRQ messages that the CPU sends to the
69  * BPMP can lead to BPMP eventually sending an MRQ message to the
70  * CPU. For example, when the CPU uses an #MRQ_THERMAL message to set
71  * a thermal trip point, the BPMP may eventually send a single
72  * #MRQ_THERMAL message of its own to the CPU indicating that the trip
73  * point has been crossed.
74  * @}
75  */
76 
77 /**
78  * @ingroup MRQ_Format
79  * @brief header for an MRQ message
80  *
81  * Provides the MRQ number for the MRQ message: #mrq. The remainder of
82  * the MRQ message is a payload (immediately following the
83  * mrq_request) whose format depends on mrq.
84  */
85 struct mrq_request {
86 	/** @brief MRQ number of the request */
87 	uint32_t mrq;
88 	/**
89 	 * @brief flags providing follow up directions to the receiver
90 	 *
91 	 * | Bit | Description                                |
92 	 * |-----|--------------------------------------------|
93 	 * | 1   | ring the sender's doorbell when responding |
94 	 * | 0   | should be 1                                |
95 	 */
96 	uint32_t flags;
97 } __ABI_PACKED;
98 
99 /**
100  * @ingroup MRQ_Format
101  * @brief header for an MRQ response
102  *
103  *  Provides an error code for the associated MRQ message. The
104  *  remainder of the MRQ response is a payload (immediately following
105  *  the mrq_response) whose format depends on the associated
106  *  mrq_request::mrq
107  */
108 struct mrq_response {
109 	/** @brief error code for the MRQ request itself */
110 	int32_t err;
111 	/** @brief reserved for future use */
112 	uint32_t flags;
113 } __ABI_PACKED;
114 
115 /**
116  * @ingroup MRQ_Format
117  * Minimum needed size for an IPC message buffer
118  */
119 #define MSG_MIN_SZ	128
120 /**
121  * @ingroup MRQ_Format
122  *  Minimum size guaranteed for data in an IPC message buffer
123  */
124 #define MSG_DATA_MIN_SZ	120
125 
126 /**
127  * @ingroup MRQ_Codes
128  * @name Legal MRQ codes
129  * These are the legal values for mrq_request::mrq
130  * @{
131  */
132 
133 #define MRQ_PING		0
134 #define MRQ_QUERY_TAG		1
135 #define MRQ_MODULE_LOAD		4
136 #define MRQ_MODULE_UNLOAD	5
137 #define MRQ_TRACE_MODIFY	7
138 #define MRQ_WRITE_TRACE		8
139 #define MRQ_THREADED_PING	9
140 #define MRQ_MODULE_MAIL		11
141 #define MRQ_DEBUGFS		19
142 #define MRQ_RESET		20
143 #define MRQ_I2C			21
144 #define MRQ_CLK			22
145 #define MRQ_QUERY_ABI		23
146 #define MRQ_PG_READ_STATE	25
147 #define MRQ_PG_UPDATE_STATE	26
148 #define MRQ_THERMAL		27
149 #define MRQ_CPU_VHINT		28
150 #define MRQ_ABI_RATCHET		29
151 #define MRQ_EMC_DVFS_LATENCY	31
152 #define MRQ_TRACE_ITER		64
153 #define MRQ_RINGBUF_CONSOLE	65
154 #define MRQ_PG			66
155 
156 /** @} */
157 
158 /**
159  * @ingroup MRQ_Codes
160  * @brief Maximum MRQ code to be sent by CPU software to
161  * BPMP. Subject to change in future
162  */
163 #define MAX_CPU_MRQ_ID		66
164 
165 /**
166  * @addtogroup MRQ_Payloads Message Payloads
167  * @{
168  *   @defgroup Ping
169  *   @defgroup Query_Tag Query Tag
170  *   @defgroup Module Loadable Modules
171  *   @defgroup Trace
172  *   @defgroup Debugfs
173  *   @defgroup Reset
174  *   @defgroup I2C
175  *   @defgroup Clocks
176  *   @defgroup ABI_info ABI Info
177  *   @defgroup MC_Flush MC Flush
178  *   @defgroup Powergating
179  *   @defgroup Thermal
180  *   @defgroup Vhint CPU Voltage hint
181  *   @defgroup MRQ_Deprecated Deprecated MRQ messages
182  *   @defgroup EMC
183  *   @defgroup RingbufConsole
184  * @}
185  */
186 
187 
188 /**
189  * @ingroup MRQ_Codes
190  * @def MRQ_PING
191  * @brief A simple ping
192  *
193  * * Platforms: All
194  * * Initiators: Any
195  * * Targets: Any
196  * * Request Payload: @ref mrq_ping_request
197  * * Response Payload: @ref mrq_ping_response
198  *
199  * @ingroup MRQ_Codes
200  * @def MRQ_THREADED_PING
201  * @brief A deeper ping
202  *
203  * * Platforms: All
204  * * Initiators: Any
205  * * Targets: BPMP
206  * * Request Payload: @ref mrq_ping_request
207  * * Response Payload: @ref mrq_ping_response
208  *
209  * Behavior is equivalent to a simple #MRQ_PING except that BPMP
210  * responds from a thread context (providing a slightly more robust
211  * sign of life).
212  *
213  */
214 
215 /**
216  * @ingroup Ping
217  * @brief request with #MRQ_PING
218  *
219  * Used by the sender of an #MRQ_PING message to request a pong from
220  * recipient. The response from the recipient is computed based on
221  * #challenge.
222  */
223 struct mrq_ping_request {
224 /** @brief arbitrarily chosen value */
225 	uint32_t challenge;
226 } __ABI_PACKED;
227 
228 /**
229  * @ingroup Ping
230  * @brief response to #MRQ_PING
231  *
232  * Sent in response to an #MRQ_PING message. #reply should be the
233  * mrq_ping_request challenge left shifted by 1 with the carry-bit
234  * dropped.
235  *
236  */
237 struct mrq_ping_response {
238 	/** @brief response to the MRQ_PING challege */
239 	uint32_t reply;
240 } __ABI_PACKED;
241 
242 /**
243  * @ingroup MRQ_Codes
244  * @def MRQ_QUERY_TAG
245  * @brief Query BPMP firmware's tag (i.e. version information)
246  *
247  * * Platforms: All
248  * * Initiators: CCPLEX
249  * * Targets: BPMP
250  * * Request Payload: @ref mrq_query_tag_request
251  * * Response Payload: N/A
252  *
253  */
254 
255 /**
256  * @ingroup Query_Tag
257  * @brief request with #MRQ_QUERY_TAG
258  *
259  * Used by #MRQ_QUERY_TAG call to ask BPMP to fill in the memory
260  * pointed by #addr with BPMP firmware header.
261  *
262  * The sender is reponsible for ensuring that #addr is mapped in to
263  * the recipient's address map.
264  */
265 struct mrq_query_tag_request {
266   /** @brief base address to store the firmware header */
267 	uint32_t addr;
268 } __ABI_PACKED;
269 
270 /**
271  * @ingroup MRQ_Codes
272  * @def MRQ_MODULE_LOAD
273  * @brief dynamically load a BPMP code module
274  *
275  * * Platforms: All
276  * * Initiators: CCPLEX
277  * * Targets: BPMP
278  * * Request Payload: @ref mrq_module_load_request
279  * * Response Payload: @ref mrq_module_load_response
280  *
281  * @note This MRQ is disabled on production systems
282  *
283  */
284 
285 /**
286  * @ingroup Module
287  * @brief request with #MRQ_MODULE_LOAD
288  *
289  * Used by #MRQ_MODULE_LOAD calls to ask the recipient to dynamically
290  * load the code located at #phys_addr and having size #size
291  * bytes. #phys_addr is treated as a void pointer.
292  *
293  * The recipient copies the code from #phys_addr to locally allocated
294  * memory prior to responding to this message.
295  *
296  * @todo document the module header format
297  *
298  * The sender is responsible for ensuring that the code is mapped in
299  * the recipient's address map.
300  *
301  */
302 struct mrq_module_load_request {
303 	/** @brief base address of the code to load. Treated as (void *) */
304 	uint32_t phys_addr; /* (void *) */
305 	/** @brief size in bytes of code to load */
306 	uint32_t size;
307 } __ABI_PACKED;
308 
309 /**
310  * @ingroup Module
311  * @brief response to #MRQ_MODULE_LOAD
312  *
313  * @todo document mrq_response::err
314  */
315 struct mrq_module_load_response {
316 	/** @brief handle to the loaded module */
317 	uint32_t base;
318 } __ABI_PACKED;
319 
320 /**
321  * @ingroup MRQ_Codes
322  * @def MRQ_MODULE_UNLOAD
323  * @brief unload a previously loaded code module
324  *
325  * * Platforms: All
326  * * Initiators: CCPLEX
327  * * Targets: BPMP
328  * * Request Payload: @ref mrq_module_unload_request
329  * * Response Payload: N/A
330  *
331  * @note This MRQ is disabled on production systems
332  */
333 
334 /**
335  * @ingroup Module
336  * @brief request with #MRQ_MODULE_UNLOAD
337  *
338  * Used by #MRQ_MODULE_UNLOAD calls to request that a previously loaded
339  * module be unloaded.
340  */
341 struct mrq_module_unload_request {
342 	/** @brief handle of the module to unload */
343 	uint32_t base;
344 } __ABI_PACKED;
345 
346 /**
347  * @ingroup MRQ_Codes
348  * @def MRQ_TRACE_MODIFY
349  * @brief modify the set of enabled trace events
350  *
351  * * Platforms: All
352  * * Initiators: CCPLEX
353  * * Targets: BPMP
354  * * Request Payload: @ref mrq_trace_modify_request
355  * * Response Payload: @ref mrq_trace_modify_response
356  *
357  * @note This MRQ is disabled on production systems
358  */
359 
360 /**
361  * @ingroup Trace
362  * @brief request with #MRQ_TRACE_MODIFY
363  *
364  * Used by %MRQ_TRACE_MODIFY calls to enable or disable specify trace
365  * events.  #set takes precedence for any bit set in both #set and
366  * #clr.
367  */
368 struct mrq_trace_modify_request {
369 	/** @brief bit mask of trace events to disable */
370 	uint32_t clr;
371 	/** @brief bit mask of trace events to enable */
372 	uint32_t set;
373 } __ABI_PACKED;
374 
375 /**
376  * @ingroup Trace
377  * @brief response to #MRQ_TRACE_MODIFY
378  *
379  * Sent in repsonse to an #MRQ_TRACE_MODIFY message. #mask reflects the
380  * state of which events are enabled after the recipient acted on the
381  * message.
382  *
383  */
384 struct mrq_trace_modify_response {
385 	/** @brief bit mask of trace event enable states */
386 	uint32_t mask;
387 } __ABI_PACKED;
388 
389 /**
390  * @ingroup MRQ_Codes
391  * @def MRQ_WRITE_TRACE
392  * @brief Write trace data to a buffer
393  *
394  * * Platforms: All
395  * * Initiators: CCPLEX
396  * * Targets: BPMP
397  * * Request Payload: @ref mrq_write_trace_request
398  * * Response Payload: @ref mrq_write_trace_response
399  *
400  * mrq_response::err depends on the @ref mrq_write_trace_request field
401  * values. err is -#BPMP_EINVAL if size is zero or area is NULL or
402  * area is in an illegal range. A positive value for err indicates the
403  * number of bytes written to area.
404  *
405  * @note This MRQ is disabled on production systems
406  */
407 
408 /**
409  * @ingroup Trace
410  * @brief request with #MRQ_WRITE_TRACE
411  *
412  * Used by MRQ_WRITE_TRACE calls to ask the recipient to copy trace
413  * data from the recipient's local buffer to the output buffer. #area
414  * is treated as a byte-aligned pointer in the recipient's address
415  * space.
416  *
417  * The sender is responsible for ensuring that the output
418  * buffer is mapped in the recipient's address map. The recipient is
419  * responsible for protecting its own code and data from accidental
420  * overwrites.
421  */
422 struct mrq_write_trace_request {
423 	/** @brief base address of output buffer */
424 	uint32_t area;
425 	/** @brief size in bytes of the output buffer */
426 	uint32_t size;
427 } __ABI_PACKED;
428 
429 /**
430  * @ingroup Trace
431  * @brief response to #MRQ_WRITE_TRACE
432  *
433  * Once this response is sent, the respondent will not access the
434  * output buffer further.
435  */
436 struct mrq_write_trace_response {
437 	/**
438 	 * @brief flag whether more data remains in local buffer
439 	 *
440 	 * Value is 1 if the entire local trace buffer has been
441 	 * drained to the outputbuffer. Value is 0 otherwise.
442 	 */
443 	uint32_t eof;
444 } __ABI_PACKED;
445 
446 /** @private */
447 struct mrq_threaded_ping_request {
448 	uint32_t challenge;
449 } __ABI_PACKED;
450 
451 /** @private */
452 struct mrq_threaded_ping_response {
453 	uint32_t reply;
454 } __ABI_PACKED;
455 
456 /**
457  * @ingroup MRQ_Codes
458  * @def MRQ_MODULE_MAIL
459  * @brief send a message to a loadable module
460  *
461  * * Platforms: All
462  * * Initiators: Any
463  * * Targets: BPMP
464  * * Request Payload: @ref mrq_module_mail_request
465  * * Response Payload: @ref mrq_module_mail_response
466  *
467  * @note This MRQ is disabled on production systems
468  */
469 
470 /**
471  * @ingroup Module
472  * @brief request with #MRQ_MODULE_MAIL
473  */
474 struct mrq_module_mail_request {
475 	/** @brief handle to the previously loaded module */
476 	uint32_t base;
477 	/** @brief module-specific mail payload
478 	 *
479 	 * The length of data[ ] is unknown to the BPMP core firmware
480 	 * but it is limited to the size of an IPC message.
481 	 */
482 	uint8_t data[EMPTY_ARRAY];
483 } __ABI_PACKED;
484 
485 /**
486  * @ingroup Module
487  * @brief response to #MRQ_MODULE_MAIL
488  */
489 struct mrq_module_mail_response {
490 	/** @brief module-specific mail payload
491 	 *
492 	 * The length of data[ ] is unknown to the BPMP core firmware
493 	 * but it is limited to the size of an IPC message.
494 	 */
495 	uint8_t data[EMPTY_ARRAY];
496 } __ABI_PACKED;
497 
498 /**
499  * @ingroup MRQ_Codes
500  * @def MRQ_DEBUGFS
501  * @brief Interact with BPMP's debugfs file nodes
502  *
503  * * Platforms: T186
504  * * Initiators: Any
505  * * Targets: BPMP
506  * * Request Payload: @ref mrq_debugfs_request
507  * * Response Payload: @ref mrq_debugfs_response
508  */
509 
510 /**
511  * @addtogroup Debugfs
512  * @{
513  *
514  * The BPMP firmware implements a pseudo-filesystem called
515  * debugfs. Any driver within the firmware may register with debugfs
516  * to expose an arbitrary set of "files" in the filesystem. When
517  * software on the CPU writes to a debugfs file, debugfs passes the
518  * written data to a callback provided by the driver. When software on
519  * the CPU reads a debugfs file, debugfs queries the driver for the
520  * data to return to the CPU. The intention of the debugfs filesystem
521  * is to provide information useful for debugging the system at
522  * runtime.
523  *
524  * @note The files exposed via debugfs are not part of the
525  * BPMP firmware's ABI. debugfs files may be added or removed in any
526  * given version of the firmware. Typically the semantics of a debugfs
527  * file are consistent from version to version but even that is not
528  * guaranteed.
529  *
530  * @}
531  */
532 /** @ingroup Debugfs */
533 enum mrq_debugfs_commands {
534 	CMD_DEBUGFS_READ = 1,
535 	CMD_DEBUGFS_WRITE = 2,
536 	CMD_DEBUGFS_DUMPDIR = 3,
537 	CMD_DEBUGFS_MAX
538 };
539 
540 /**
541  * @ingroup Debugfs
542  * @brief parameters for CMD_DEBUGFS_READ/WRITE command
543  */
544 struct cmd_debugfs_fileop_request {
545 	/** @brief physical address pointing at filename */
546 	uint32_t fnameaddr;
547 	/** @brief length in bytes of filename buffer */
548 	uint32_t fnamelen;
549 	/** @brief physical address pointing to data buffer */
550 	uint32_t dataaddr;
551 	/** @brief length in bytes of data buffer */
552 	uint32_t datalen;
553 } __ABI_PACKED;
554 
555 /**
556  * @ingroup Debugfs
557  * @brief parameters for CMD_DEBUGFS_READ/WRITE command
558  */
559 struct cmd_debugfs_dumpdir_request {
560 	/** @brief physical address pointing to data buffer */
561 	uint32_t dataaddr;
562 	/** @brief length in bytes of data buffer */
563 	uint32_t datalen;
564 } __ABI_PACKED;
565 
566 /**
567  * @ingroup Debugfs
568  * @brief response data for CMD_DEBUGFS_READ/WRITE command
569  */
570 struct cmd_debugfs_fileop_response {
571 	/** @brief always 0 */
572 	uint32_t reserved;
573 	/** @brief number of bytes read from or written to data buffer */
574 	uint32_t nbytes;
575 } __ABI_PACKED;
576 
577 /**
578  * @ingroup Debugfs
579  * @brief response data for CMD_DEBUGFS_DUMPDIR command
580  */
581 struct cmd_debugfs_dumpdir_response {
582 	/** @brief always 0 */
583 	uint32_t reserved;
584 	/** @brief number of bytes read from or written to data buffer */
585 	uint32_t nbytes;
586 } __ABI_PACKED;
587 
588 /**
589  * @ingroup Debugfs
590  * @brief request with #MRQ_DEBUGFS.
591  *
592  * The sender of an MRQ_DEBUGFS message uses #cmd to specify a debugfs
593  * command to execute. Legal commands are the values of @ref
594  * mrq_debugfs_commands. Each command requires a specific additional
595  * payload of data.
596  *
597  * |command            |payload|
598  * |-------------------|-------|
599  * |CMD_DEBUGFS_READ   |fop    |
600  * |CMD_DEBUGFS_WRITE  |fop    |
601  * |CMD_DEBUGFS_DUMPDIR|dumpdir|
602  */
603 struct mrq_debugfs_request {
604 	uint32_t cmd;
605 	union {
606 		struct cmd_debugfs_fileop_request fop;
607 		struct cmd_debugfs_dumpdir_request dumpdir;
608 	} __UNION_ANON;
609 } __ABI_PACKED;
610 
611 /**
612  * @ingroup Debugfs
613  */
614 struct mrq_debugfs_response {
615 	/** @brief always 0 */
616 	int32_t reserved;
617 	union {
618 		/** @brief response data for CMD_DEBUGFS_READ OR
619 		 * CMD_DEBUGFS_WRITE command
620 		 */
621 		struct cmd_debugfs_fileop_response fop;
622 		/** @brief response data for CMD_DEBUGFS_DUMPDIR command */
623 		struct cmd_debugfs_dumpdir_response dumpdir;
624 	} __UNION_ANON;
625 } __ABI_PACKED;
626 
627 /**
628  * @addtogroup Debugfs
629  * @{
630  */
631 #define DEBUGFS_S_ISDIR	(1 << 9)
632 #define DEBUGFS_S_IRUSR	(1 << 8)
633 #define DEBUGFS_S_IWUSR	(1 << 7)
634 /** @} */
635 
636 
637 /**
638  * @ingroup MRQ_Codes
639  * @def MRQ_RESET
640  * @brief reset an IP block
641  *
642  * * Platforms: T186
643  * * Initiators: Any
644  * * Targets: BPMP
645  * * Request Payload: @ref mrq_reset_request
646  * * Response Payload: @ref mrq_reset_response
647  */
648 
649 /**
650  * @ingroup Reset
651  */
652 enum mrq_reset_commands {
653 	CMD_RESET_ASSERT = 1,
654 	CMD_RESET_DEASSERT = 2,
655 	CMD_RESET_MODULE = 3,
656 	CMD_RESET_GET_MAX_ID = 4,
657 	CMD_RESET_MAX, /* not part of ABI and subject to change */
658 };
659 
660 /**
661  * @ingroup Reset
662  * @brief request with MRQ_RESET
663  *
664  * Used by the sender of an #MRQ_RESET message to request BPMP to
665  * assert or or deassert a given reset line.
666  */
667 struct mrq_reset_request {
668 	/** @brief reset action to perform (@enum mrq_reset_commands) */
669 	uint32_t cmd;
670 	/** @brief id of the reset to affected */
671 	uint32_t reset_id;
672 } __ABI_PACKED;
673 
674 /**
675  * @ingroup Reset
676  * @brief Response for MRQ_RESET sub-command CMD_RESET_GET_MAX_ID. When
677  * this sub-command is not supported, firmware will return -BPMP_EBADCMD
678  * in mrq_response::err.
679  */
680 struct cmd_reset_get_max_id_response {
681 	/** @brief max reset id */
682 	uint32_t max_id;
683 } __ABI_PACKED;
684 
685 /**
686  * @ingroup Reset
687  * @brief Response with MRQ_RESET
688  *
689  * Each sub-command supported by @ref mrq_reset_request may return
690  * sub-command-specific data. Some do and some do not as indicated
691  * in the following table
692  *
693  * | sub-command          | payload          |
694  * |----------------------|------------------|
695  * | CMD_RESET_ASSERT     | -                |
696  * | CMD_RESET_DEASSERT   | -                |
697  * | CMD_RESET_MODULE     | -                |
698  * | CMD_RESET_GET_MAX_ID | reset_get_max_id |
699  */
700 struct mrq_reset_response {
701 	union {
702 		struct cmd_reset_get_max_id_response reset_get_max_id;
703 	} __UNION_ANON;
704 } __ABI_PACKED;
705 
706 /**
707  * @ingroup MRQ_Codes
708  * @def MRQ_I2C
709  * @brief issue an i2c transaction
710  *
711  * * Platforms: T186
712  * * Initiators: Any
713  * * Targets: BPMP
714  * * Request Payload: @ref mrq_i2c_request
715  * * Response Payload: @ref mrq_i2c_response
716  */
717 
718 /**
719  * @addtogroup I2C
720  * @{
721  */
722 #define TEGRA_I2C_IPC_MAX_IN_BUF_SIZE	(MSG_DATA_MIN_SZ - 12)
723 #define TEGRA_I2C_IPC_MAX_OUT_BUF_SIZE	(MSG_DATA_MIN_SZ - 4)
724 /** @} */
725 
726 /**
727  * @ingroup I2C
728  * @name Serial I2C flags
729  * Use these flags with serial_i2c_request::flags
730  * @{
731  */
732 #define SERIALI2C_TEN           0x0010
733 #define SERIALI2C_RD            0x0001
734 #define SERIALI2C_STOP          0x8000
735 #define SERIALI2C_NOSTART       0x4000
736 #define SERIALI2C_REV_DIR_ADDR  0x2000
737 #define SERIALI2C_IGNORE_NAK    0x1000
738 #define SERIALI2C_NO_RD_ACK     0x0800
739 #define SERIALI2C_RECV_LEN      0x0400
740 /** @} */
741 /** @ingroup I2C */
742 enum {
743 	CMD_I2C_XFER = 1
744 };
745 
746 /**
747  * @ingroup I2C
748  * @brief serializable i2c request
749  *
750  * Instances of this structure are packed (little-endian) into
751  * cmd_i2c_xfer_request::data_buf. Each instance represents a single
752  * transaction (or a portion of a transaction with repeated starts) on
753  * an i2c bus.
754  *
755  * Because these structures are packed, some instances are likely to
756  * be misaligned. Additionally because #data is variable length, it is
757  * not possible to iterate through a serialized list of these
758  * structures without inspecting #len in each instance.  It may be
759  * easier to serialize or deserialize cmd_i2c_xfer_request::data_buf
760  * manually rather than using this structure definition.
761 */
762 struct serial_i2c_request {
763 	/** @brief I2C slave address */
764 	uint16_t addr;
765 	/** @brief bitmask of SERIALI2C_ flags */
766 	uint16_t flags;
767 	/** @brief length of I2C transaction in bytes */
768 	uint16_t len;
769 	/** @brief for write transactions only, #len bytes of data */
770 	uint8_t data[];
771 } __ABI_PACKED;
772 
773 /**
774  * @ingroup I2C
775  * @brief trigger one or more i2c transactions
776  */
777 struct cmd_i2c_xfer_request {
778 	/** @brief valid bus number from mach-t186/i2c-t186.h*/
779 	uint32_t bus_id;
780 
781 	/** @brief count of valid bytes in #data_buf*/
782 	uint32_t data_size;
783 
784 	/** @brief serialized packed instances of @ref serial_i2c_request*/
785 	uint8_t data_buf[TEGRA_I2C_IPC_MAX_IN_BUF_SIZE];
786 } __ABI_PACKED;
787 
788 /**
789  * @ingroup I2C
790  * @brief container for data read from the i2c bus
791  *
792  * Processing an cmd_i2c_xfer_request::data_buf causes BPMP to execute
793  * zero or more I2C reads. The data read from the bus is serialized
794  * into #data_buf.
795  */
796 struct cmd_i2c_xfer_response {
797 	/** @brief count of valid bytes in #data_buf*/
798 	uint32_t data_size;
799 	/** @brief i2c read data */
800 	uint8_t data_buf[TEGRA_I2C_IPC_MAX_OUT_BUF_SIZE];
801 } __ABI_PACKED;
802 
803 /**
804  * @ingroup I2C
805  * @brief request with #MRQ_I2C
806  */
807 struct mrq_i2c_request {
808 	/** @brief always CMD_I2C_XFER (i.e. 1) */
809 	uint32_t cmd;
810 	/** @brief parameters of the transfer request */
811 	struct cmd_i2c_xfer_request xfer;
812 } __ABI_PACKED;
813 
814 /**
815  * @ingroup I2C
816  * @brief response to #MRQ_I2C
817  */
818 struct mrq_i2c_response {
819 	struct cmd_i2c_xfer_response xfer;
820 } __ABI_PACKED;
821 
822 /**
823  * @ingroup MRQ_Codes
824  * @def MRQ_CLK
825  *
826  * * Platforms: T186
827  * * Initiators: Any
828  * * Targets: BPMP
829  * * Request Payload: @ref mrq_clk_request
830  * * Response Payload: @ref mrq_clk_response
831  * @addtogroup Clocks
832  * @{
833  */
834 
835 /**
836  * @name MRQ_CLK sub-commands
837  * @{
838  */
839 enum {
840 	CMD_CLK_GET_RATE = 1,
841 	CMD_CLK_SET_RATE = 2,
842 	CMD_CLK_ROUND_RATE = 3,
843 	CMD_CLK_GET_PARENT = 4,
844 	CMD_CLK_SET_PARENT = 5,
845 	CMD_CLK_IS_ENABLED = 6,
846 	CMD_CLK_ENABLE = 7,
847 	CMD_CLK_DISABLE = 8,
848 	CMD_CLK_GET_ALL_INFO = 14,
849 	CMD_CLK_GET_MAX_CLK_ID = 15,
850 	CMD_CLK_MAX,
851 };
852 /** @} */
853 
854 /**
855  * @name MRQ_CLK properties
856  * Flag bits for cmd_clk_properties_response::flags and
857  * cmd_clk_get_all_info_response::flags
858  * @{
859  */
860 #define BPMP_CLK_HAS_MUX	(1 << 0)
861 #define BPMP_CLK_HAS_SET_RATE	(1 << 1)
862 #define BPMP_CLK_IS_ROOT	(1 << 2)
863 /** @} */
864 
865 #define MRQ_CLK_NAME_MAXLEN	40
866 #define MRQ_CLK_MAX_PARENTS	16
867 
868 /** @private */
869 struct cmd_clk_get_rate_request {
870 	EMPTY
871 } __ABI_PACKED;
872 
873 struct cmd_clk_get_rate_response {
874 	int64_t rate;
875 } __ABI_PACKED;
876 
877 struct cmd_clk_set_rate_request {
878 	int32_t unused;
879 	int64_t rate;
880 } __ABI_PACKED;
881 
882 struct cmd_clk_set_rate_response {
883 	int64_t rate;
884 } __ABI_PACKED;
885 
886 struct cmd_clk_round_rate_request {
887 	int32_t unused;
888 	int64_t rate;
889 } __ABI_PACKED;
890 
891 struct cmd_clk_round_rate_response {
892 	int64_t rate;
893 } __ABI_PACKED;
894 
895 /** @private */
896 struct cmd_clk_get_parent_request {
897 	EMPTY
898 } __ABI_PACKED;
899 
900 struct cmd_clk_get_parent_response {
901 	uint32_t parent_id;
902 } __ABI_PACKED;
903 
904 struct cmd_clk_set_parent_request {
905 	uint32_t parent_id;
906 } __ABI_PACKED;
907 
908 struct cmd_clk_set_parent_response {
909 	uint32_t parent_id;
910 } __ABI_PACKED;
911 
912 /** @private */
913 struct cmd_clk_is_enabled_request {
914 	EMPTY
915 } __ABI_PACKED;
916 
917 struct cmd_clk_is_enabled_response {
918 	int32_t state;
919 } __ABI_PACKED;
920 
921 /** @private */
922 struct cmd_clk_enable_request {
923 	EMPTY
924 } __ABI_PACKED;
925 
926 /** @private */
927 struct cmd_clk_enable_response {
928 	EMPTY
929 } __ABI_PACKED;
930 
931 /** @private */
932 struct cmd_clk_disable_request {
933 	EMPTY
934 } __ABI_PACKED;
935 
936 /** @private */
937 struct cmd_clk_disable_response {
938 	EMPTY
939 } __ABI_PACKED;
940 
941 /** @private */
942 struct cmd_clk_get_all_info_request {
943 	EMPTY
944 } __ABI_PACKED;
945 
946 struct cmd_clk_get_all_info_response {
947 	uint32_t flags;
948 	uint32_t parent;
949 	uint32_t parents[MRQ_CLK_MAX_PARENTS];
950 	uint8_t num_parents;
951 	uint8_t name[MRQ_CLK_NAME_MAXLEN];
952 } __ABI_PACKED;
953 
954 /** @private */
955 struct cmd_clk_get_max_clk_id_request {
956 	EMPTY
957 } __ABI_PACKED;
958 
959 struct cmd_clk_get_max_clk_id_response {
960 	uint32_t max_id;
961 } __ABI_PACKED;
962 /** @} */
963 
964 /**
965  * @ingroup Clocks
966  * @brief request with #MRQ_CLK
967  *
968  * Used by the sender of an #MRQ_CLK message to control clocks. The
969  * clk_request is split into several sub-commands. Some sub-commands
970  * require no additional data. Others have a sub-command specific
971  * payload
972  *
973  * |sub-command                 |payload                |
974  * |----------------------------|-----------------------|
975  * |CMD_CLK_GET_RATE            |-                      |
976  * |CMD_CLK_SET_RATE            |clk_set_rate           |
977  * |CMD_CLK_ROUND_RATE          |clk_round_rate         |
978  * |CMD_CLK_GET_PARENT          |-                      |
979  * |CMD_CLK_SET_PARENT          |clk_set_parent         |
980  * |CMD_CLK_IS_ENABLED          |-                      |
981  * |CMD_CLK_ENABLE              |-                      |
982  * |CMD_CLK_DISABLE             |-                      |
983  * |CMD_CLK_GET_ALL_INFO        |-                      |
984  * |CMD_CLK_GET_MAX_CLK_ID      |-                      |
985  *
986  */
987 
988 struct mrq_clk_request {
989 	/** @brief sub-command and clock id concatenated to 32-bit word.
990 	 * - bits[31..24] is the sub-cmd.
991 	 * - bits[23..0] is the clock id
992 	 */
993 	uint32_t cmd_and_id;
994 
995 	union {
996 		/** @private */
997 		struct cmd_clk_get_rate_request clk_get_rate;
998 		struct cmd_clk_set_rate_request clk_set_rate;
999 		struct cmd_clk_round_rate_request clk_round_rate;
1000 		/** @private */
1001 		struct cmd_clk_get_parent_request clk_get_parent;
1002 		struct cmd_clk_set_parent_request clk_set_parent;
1003 		/** @private */
1004 		struct cmd_clk_enable_request clk_enable;
1005 		/** @private */
1006 		struct cmd_clk_disable_request clk_disable;
1007 		/** @private */
1008 		struct cmd_clk_is_enabled_request clk_is_enabled;
1009 		/** @private */
1010 		struct cmd_clk_get_all_info_request clk_get_all_info;
1011 		/** @private */
1012 		struct cmd_clk_get_max_clk_id_request clk_get_max_clk_id;
1013 	} __UNION_ANON;
1014 } __ABI_PACKED;
1015 
1016 /**
1017  * @ingroup Clocks
1018  * @brief response to MRQ_CLK
1019  *
1020  * Each sub-command supported by @ref mrq_clk_request may return
1021  * sub-command-specific data. Some do and some do not as indicated in
1022  * the following table
1023  *
1024  * |sub-command                 |payload                 |
1025  * |----------------------------|------------------------|
1026  * |CMD_CLK_GET_RATE            |clk_get_rate            |
1027  * |CMD_CLK_SET_RATE            |clk_set_rate            |
1028  * |CMD_CLK_ROUND_RATE          |clk_round_rate          |
1029  * |CMD_CLK_GET_PARENT          |clk_get_parent          |
1030  * |CMD_CLK_SET_PARENT          |clk_set_parent          |
1031  * |CMD_CLK_IS_ENABLED          |clk_is_enabled          |
1032  * |CMD_CLK_ENABLE              |-                       |
1033  * |CMD_CLK_DISABLE             |-                       |
1034  * |CMD_CLK_GET_ALL_INFO        |clk_get_all_info        |
1035  * |CMD_CLK_GET_MAX_CLK_ID      |clk_get_max_id          |
1036  *
1037  */
1038 
1039 struct mrq_clk_response {
1040 	union {
1041 		struct cmd_clk_get_rate_response clk_get_rate;
1042 		struct cmd_clk_set_rate_response clk_set_rate;
1043 		struct cmd_clk_round_rate_response clk_round_rate;
1044 		struct cmd_clk_get_parent_response clk_get_parent;
1045 		struct cmd_clk_set_parent_response clk_set_parent;
1046 		/** @private */
1047 		struct cmd_clk_enable_response clk_enable;
1048 		/** @private */
1049 		struct cmd_clk_disable_response clk_disable;
1050 		struct cmd_clk_is_enabled_response clk_is_enabled;
1051 		struct cmd_clk_get_all_info_response clk_get_all_info;
1052 		struct cmd_clk_get_max_clk_id_response clk_get_max_clk_id;
1053 	} __UNION_ANON;
1054 } __ABI_PACKED;
1055 
1056 /**
1057  * @ingroup MRQ_Codes
1058  * @def MRQ_QUERY_ABI
1059  * @brief check if an MRQ is implemented
1060  *
1061  * * Platforms: All
1062  * * Initiators: Any
1063  * * Targets: Any except DMCE
1064  * * Request Payload: @ref mrq_query_abi_request
1065  * * Response Payload: @ref mrq_query_abi_response
1066  */
1067 
1068 /**
1069  * @ingroup ABI_info
1070  * @brief request with MRQ_QUERY_ABI
1071  *
1072  * Used by #MRQ_QUERY_ABI call to check if MRQ code #mrq is supported
1073  * by the recipient.
1074  */
1075 struct mrq_query_abi_request {
1076 	/** @brief MRQ code to query */
1077 	uint32_t mrq;
1078 } __ABI_PACKED;
1079 
1080 /**
1081  * @ingroup ABI_info
1082  * @brief response to MRQ_QUERY_ABI
1083  *
1084  * @note mrq_response::err of 0 indicates that the query was
1085  * successful, not that the MRQ itself is supported!
1086  */
1087 struct mrq_query_abi_response {
1088 	/** @brief 0 if queried MRQ is supported. Else, -#BPMP_ENODEV */
1089 	int32_t status;
1090 } __ABI_PACKED;
1091 
1092 /**
1093  * @ingroup MRQ_Codes
1094  * @def MRQ_PG_READ_STATE
1095  * @brief read the power-gating state of a partition
1096  *
1097  * * Platforms: T186
1098  * * Initiators: Any
1099  * * Targets: BPMP
1100  * * Request Payload: @ref mrq_pg_read_state_request
1101  * * Response Payload: @ref mrq_pg_read_state_response
1102  * @addtogroup Powergating
1103  * @{
1104  */
1105 
1106 /**
1107  * @brief request with #MRQ_PG_READ_STATE
1108  *
1109  * Used by MRQ_PG_READ_STATE call to read the current state of a
1110  * partition.
1111  */
1112 struct mrq_pg_read_state_request {
1113 	/** @brief ID of partition */
1114 	uint32_t partition_id;
1115 } __ABI_PACKED;
1116 
1117 /**
1118  * @brief response to MRQ_PG_READ_STATE
1119  * @todo define possible errors.
1120  */
1121 struct mrq_pg_read_state_response {
1122 	/** @brief read as don't care */
1123 	uint32_t sram_state;
1124 	/** @brief state of power partition
1125 	 * * 0 : off
1126 	 * * 1 : on
1127 	 */
1128 	uint32_t logic_state;
1129 } __ABI_PACKED;
1130 
1131 /** @} */
1132 
1133 /**
1134  * @ingroup MRQ_Codes
1135  * @def MRQ_PG_UPDATE_STATE
1136  * @brief modify the power-gating state of a partition. In contrast to
1137  * MRQ_PG calls, the operations that change state (on/off) of power
1138  * partition are reference counted.
1139  *
1140  * * Platforms: T186
1141  * * Initiators: Any
1142  * * Targets: BPMP
1143  * * Request Payload: @ref mrq_pg_update_state_request
1144  * * Response Payload: N/A
1145  * @addtogroup Powergating
1146  * @{
1147  */
1148 
1149 /**
1150  * @brief request with mrq_pg_update_state_request
1151  *
1152  * Used by #MRQ_PG_UPDATE_STATE call to request BPMP to change the
1153  * state of a power partition #partition_id.
1154  */
1155 struct mrq_pg_update_state_request {
1156 	/** @brief ID of partition */
1157 	uint32_t partition_id;
1158 	/** @brief secondary control of power partition
1159 	 *  @details Ignored by many versions of the BPMP
1160 	 *  firmware. For maximum compatibility, set the value
1161 	 *  according to @logic_state
1162 	 * *  0x1: power ON partition (@ref logic_state == 0x3)
1163 	 * *  0x3: power OFF partition (@ref logic_state == 0x1)
1164 	 */
1165 	uint32_t sram_state;
1166 	/** @brief controls state of power partition, legal values are
1167 	 * *  0x1 : power OFF partition
1168 	 * *  0x3 : power ON partition
1169 	 */
1170 	uint32_t logic_state;
1171 	/** @brief change state of clocks of the power partition, legal values
1172 	 * *  0x0 : do not change clock state
1173 	 * *  0x1 : disable partition clocks (only applicable when
1174 	 *          @ref logic_state == 0x1)
1175 	 * *  0x3 : enable partition clocks (only applicable when
1176 	 *          @ref logic_state == 0x3)
1177 	 */
1178 	uint32_t clock_state;
1179 } __ABI_PACKED;
1180 /** @} */
1181 
1182 /**
1183  * @ingroup MRQ_Codes
1184  * @def MRQ_PG
1185  * @brief Control power-gating state of a partition. In contrast to
1186  * MRQ_PG_UPDATE_STATE, operations that change the power partition
1187  * state are NOT reference counted
1188  *
1189  * * Platforms: T186
1190  * * Initiators: Any
1191  * * Targets: BPMP
1192  * * Request Payload: @ref mrq_pg_request
1193  * * Response Payload: @ref mrq_pg_response
1194  * @addtogroup Powergating
1195  * @{
1196  */
1197 
1198 /**
1199  * @name MRQ_PG sub-commands
1200  * @{
1201  */
1202 enum mrq_pg_cmd {
1203 	/**
1204 	 * @brief Check whether the BPMP driver supports the specified
1205 	 * request type
1206 	 *
1207 	 * mrq_response::err is 0 if the specified request is
1208 	 * supported and -#BPMP_ENODEV otherwise.
1209 	 */
1210 	CMD_PG_QUERY_ABI = 0,
1211 
1212 	/**
1213 	 * @brief Set the current state of specified power domain. The
1214 	 * possible values for power domains are defined in enum
1215 	 * pg_states
1216 	 *
1217 	 * mrq_response:err is
1218 	 * 0: Success
1219 	 * -#BPMP_EINVAL: Invalid request parameters
1220 	 */
1221 	CMD_PG_SET_STATE = 1,
1222 
1223 	/**
1224 	 * @brief Get the current state of specified power domain. The
1225 	 * possible values for power domains are defined in enum
1226 	 * pg_states
1227 	 *
1228 	 * mrq_response:err is
1229 	 * 0: Success
1230 	 * -#BPMP_EINVAL: Invalid request parameters
1231 	 */
1232 	CMD_PG_GET_STATE = 2,
1233 
1234 	/**
1235 	 * @brief get the name string of specified power domain id.
1236 	 *
1237 	 * mrq_response:err is
1238 	 * 0: Success
1239 	 * -#BPMP_EINVAL: Invalid request parameters
1240 	 */
1241 	CMD_PG_GET_NAME = 3,
1242 
1243 
1244 	/**
1245 	 * @brief get the highest power domain id in the system. Not
1246 	 * all IDs between 0 and max_id are valid IDs.
1247 	 *
1248 	 * mrq_response:err is
1249 	 * 0: Success
1250 	 * -#BPMP_EINVAL: Invalid request parameters
1251 	 */
1252 	CMD_PG_GET_MAX_ID = 4,
1253 };
1254 /** @} */
1255 
1256 #define MRQ_PG_NAME_MAXLEN	40
1257 
1258 /**
1259  * @brief possible power domain states in
1260  * cmd_pg_set_state_request:state and cmd_pg_get_state_response:state.
1261  *  PG_STATE_OFF: power domain is OFF
1262  *  PG_STATE_ON: power domain is ON
1263  *  PG_STATE_RUNNING: power domain is ON and made into directly usable
1264  *                    state by turning on the clocks associated with
1265  *                    the domain
1266  */
1267 enum pg_states {
1268 	PG_STATE_OFF = 0,
1269 	PG_STATE_ON = 1,
1270 	PG_STATE_RUNNING = 2,
1271 };
1272 
1273 struct cmd_pg_query_abi_request {
1274 	uint32_t type; /* enum mrq_pg_cmd */
1275 } __ABI_PACKED;
1276 
1277 struct cmd_pg_set_state_request {
1278 	uint32_t state; /* enum pg_states */
1279 } __ABI_PACKED;
1280 
1281 struct cmd_pg_get_state_response {
1282 	uint32_t state; /* enum pg_states */
1283 } __ABI_PACKED;
1284 
1285 struct cmd_pg_get_name_response {
1286 	uint8_t name[MRQ_PG_NAME_MAXLEN];
1287 } __ABI_PACKED;
1288 
1289 struct cmd_pg_get_max_id_response {
1290 	uint32_t max_id;
1291 } __ABI_PACKED;
1292 
1293 /**
1294  * @ingroup Powergating
1295  * @brief request with #MRQ_PG
1296  *
1297  * Used by the sender of an #MRQ_PG message to control power
1298  * partitions. The pg_request is split into several sub-commands. Some
1299  * sub-commands require no additional data. Others have a sub-command
1300  * specific payload
1301  *
1302  * |sub-command                 |payload                |
1303  * |----------------------------|-----------------------|
1304  * |CMD_PG_QUERY_ABI            | query_abi             |
1305  * |CMD_PG_SET_STATE            | set_state             |
1306  * |CMD_PG_GET_STATE            | -                     |
1307  * |CMD_PG_GET_NAME             | -                     |
1308  * |CMD_PG_GET_MAX_ID           | -                     |
1309  *
1310  */
1311 
1312 struct mrq_pg_request {
1313 	uint32_t cmd;
1314 	uint32_t id;
1315 	union {
1316 		struct cmd_pg_query_abi_request query_abi;
1317 		struct cmd_pg_set_state_request set_state;
1318 	} __UNION_ANON;
1319 } __ABI_PACKED;
1320 
1321 /**
1322  * @ingroup Powergating
1323  * @brief response to MRQ_PG
1324  *
1325  * Each sub-command supported by @ref mrq_pg_request may return
1326  * sub-command-specific data. Some do and some do not as indicated in
1327  * the following table
1328  *
1329  * |sub-command                 |payload                |
1330  * |----------------------------|-----------------------|
1331  * |CMD_PG_QUERY_ABI            | -                     |
1332  * |CMD_PG_SET_STATE            | -                     |
1333  * |CMD_PG_GET_STATE            | get_state             |
1334  * |CMD_PG_GET_NAME             | get_name              |
1335  * |CMD_PG_GET_MAX_ID           | get_max_id            |
1336  *
1337  */
1338 
1339 struct mrq_pg_response {
1340 	union {
1341 		struct cmd_pg_get_state_response get_state;
1342 		struct cmd_pg_get_name_response get_name;
1343 		struct cmd_pg_get_max_id_response get_max_id;
1344 	} __UNION_ANON;
1345 } __ABI_PACKED;
1346 
1347 /**
1348  * @ingroup MRQ_Codes
1349  * @def MRQ_THERMAL
1350  * @brief interact with BPMP thermal framework
1351  *
1352  * * Platforms: T186
1353  * * Initiators: Any
1354  * * Targets: Any
1355  * * Request Payload: TODO
1356  * * Response Payload: TODO
1357  *
1358  * @addtogroup Thermal
1359  *
1360  * The BPMP firmware includes a thermal framework. Drivers within the
1361  * bpmp firmware register with the framework to provide thermal
1362  * zones. Each thermal zone corresponds to an entity whose temperature
1363  * can be measured. The framework also has a notion of trip points. A
1364  * trip point consists of a thermal zone id, a temperature, and a
1365  * callback routine. The framework invokes the callback when the zone
1366  * hits the indicated temperature. The BPMP firmware uses this thermal
1367  * framework interally to implement various temperature-dependent
1368  * functions.
1369  *
1370  * Software on the CPU can use #MRQ_THERMAL (with payload @ref
1371  * mrq_thermal_host_to_bpmp_request) to interact with the BPMP thermal
1372  * framework. The CPU must It can query the number of supported zones,
1373  * query zone temperatures, and set trip points.
1374  *
1375  * When a trip point set by the CPU gets crossed, BPMP firmware issues
1376  * an IPC to the CPU having mrq_request::mrq = #MRQ_THERMAL and a
1377  * payload of @ref mrq_thermal_bpmp_to_host_request.
1378  * @{
1379  */
1380 enum mrq_thermal_host_to_bpmp_cmd {
1381 	/**
1382 	 * @brief Check whether the BPMP driver supports the specified
1383 	 * request type.
1384 	 *
1385 	 * Host needs to supply request parameters.
1386 	 *
1387 	 * mrq_response::err is 0 if the specified request is
1388 	 * supported and -#BPMP_ENODEV otherwise.
1389 	 */
1390 	CMD_THERMAL_QUERY_ABI = 0,
1391 
1392 	/**
1393 	 * @brief Get the current temperature of the specified zone.
1394 	 *
1395 	 * Host needs to supply request parameters.
1396 	 *
1397 	 * mrq_response::err is
1398 	 * *  0: Temperature query succeeded.
1399 	 * *  -#BPMP_EINVAL: Invalid request parameters.
1400 	 * *  -#BPMP_ENOENT: No driver registered for thermal zone..
1401 	 * *  -#BPMP_EFAULT: Problem reading temperature measurement.
1402 	 */
1403 	CMD_THERMAL_GET_TEMP = 1,
1404 
1405 	/**
1406 	 * @brief Enable or disable and set the lower and upper
1407 	 *   thermal limits for a thermal trip point. Each zone has
1408 	 *   one trip point.
1409 	 *
1410 	 * Host needs to supply request parameters. Once the
1411 	 * temperature hits a trip point, the BPMP will send a message
1412 	 * to the CPU having MRQ=MRQ_THERMAL and
1413 	 * type=CMD_THERMAL_HOST_TRIP_REACHED
1414 	 *
1415 	 * mrq_response::err is
1416 	 * *  0: Trip successfully set.
1417 	 * *  -#BPMP_EINVAL: Invalid request parameters.
1418 	 * *  -#BPMP_ENOENT: No driver registered for thermal zone.
1419 	 * *  -#BPMP_EFAULT: Problem setting trip point.
1420 	 */
1421 	CMD_THERMAL_SET_TRIP = 2,
1422 
1423 	/**
1424 	 * @brief Get the number of supported thermal zones.
1425 	 *
1426 	 * No request parameters required.
1427 	 *
1428 	 * mrq_response::err is always 0, indicating success.
1429 	 */
1430 	CMD_THERMAL_GET_NUM_ZONES = 3,
1431 
1432 	/** @brief: number of supported host-to-bpmp commands. May
1433 	 * increase in future
1434 	 */
1435 	CMD_THERMAL_HOST_TO_BPMP_NUM
1436 };
1437 
1438 enum mrq_thermal_bpmp_to_host_cmd {
1439 	/**
1440 	 * @brief Indication that the temperature for a zone has
1441 	 *   exceeded the range indicated in the thermal trip point
1442 	 *   for the zone.
1443 	 *
1444 	 * BPMP needs to supply request parameters. Host only needs to
1445 	 * acknowledge.
1446 	 */
1447 	CMD_THERMAL_HOST_TRIP_REACHED = 100,
1448 
1449 	/** @brief: number of supported bpmp-to-host commands. May
1450 	 * increase in future
1451 	 */
1452 	CMD_THERMAL_BPMP_TO_HOST_NUM
1453 };
1454 
1455 /*
1456  * Host->BPMP request data for request type CMD_THERMAL_QUERY_ABI
1457  *
1458  * zone: Request type for which to check existence.
1459  */
1460 struct cmd_thermal_query_abi_request {
1461 	uint32_t type;
1462 } __ABI_PACKED;
1463 
1464 /*
1465  * Host->BPMP request data for request type CMD_THERMAL_GET_TEMP
1466  *
1467  * zone: Number of thermal zone.
1468  */
1469 struct cmd_thermal_get_temp_request {
1470 	uint32_t zone;
1471 } __ABI_PACKED;
1472 
1473 /*
1474  * BPMP->Host reply data for request CMD_THERMAL_GET_TEMP
1475  *
1476  * error: 0 if request succeeded.
1477  *	-BPMP_EINVAL if request parameters were invalid.
1478  *      -BPMP_ENOENT if no driver was registered for the specified thermal zone.
1479  *      -BPMP_EFAULT for other thermal zone driver errors.
1480  * temp: Current temperature in millicelsius.
1481  */
1482 struct cmd_thermal_get_temp_response {
1483 	int32_t temp;
1484 } __ABI_PACKED;
1485 
1486 /*
1487  * Host->BPMP request data for request type CMD_THERMAL_SET_TRIP
1488  *
1489  * zone: Number of thermal zone.
1490  * low: Temperature of lower trip point in millicelsius
1491  * high: Temperature of upper trip point in millicelsius
1492  * enabled: 1 to enable trip point, 0 to disable trip point
1493  */
1494 struct cmd_thermal_set_trip_request {
1495 	uint32_t zone;
1496 	int32_t low;
1497 	int32_t high;
1498 	uint32_t enabled;
1499 } __ABI_PACKED;
1500 
1501 /*
1502  * BPMP->Host request data for request type CMD_THERMAL_HOST_TRIP_REACHED
1503  *
1504  * zone: Number of thermal zone where trip point was reached.
1505  */
1506 struct cmd_thermal_host_trip_reached_request {
1507 	uint32_t zone;
1508 } __ABI_PACKED;
1509 
1510 /*
1511  * BPMP->Host reply data for request type CMD_THERMAL_GET_NUM_ZONES
1512  *
1513  * num: Number of supported thermal zones. The thermal zones are indexed
1514  *      starting from zero.
1515  */
1516 struct cmd_thermal_get_num_zones_response {
1517 	uint32_t num;
1518 } __ABI_PACKED;
1519 
1520 /*
1521  * Host->BPMP request data.
1522  *
1523  * Reply type is union mrq_thermal_bpmp_to_host_response.
1524  *
1525  * type: Type of request. Values listed in enum mrq_thermal_type.
1526  * data: Request type specific parameters.
1527  */
1528 struct mrq_thermal_host_to_bpmp_request {
1529 	uint32_t type;
1530 	union {
1531 		struct cmd_thermal_query_abi_request query_abi;
1532 		struct cmd_thermal_get_temp_request get_temp;
1533 		struct cmd_thermal_set_trip_request set_trip;
1534 	} __UNION_ANON;
1535 } __ABI_PACKED;
1536 
1537 /*
1538  * BPMP->Host request data.
1539  *
1540  * type: Type of request. Values listed in enum mrq_thermal_type.
1541  * data: Request type specific parameters.
1542  */
1543 struct mrq_thermal_bpmp_to_host_request {
1544 	uint32_t type;
1545 	union {
1546 		struct cmd_thermal_host_trip_reached_request host_trip_reached;
1547 	} __UNION_ANON;
1548 } __ABI_PACKED;
1549 
1550 /*
1551  * Data in reply to a Host->BPMP request.
1552  */
1553 union mrq_thermal_bpmp_to_host_response {
1554 	struct cmd_thermal_get_temp_response get_temp;
1555 	struct cmd_thermal_get_num_zones_response get_num_zones;
1556 } __ABI_PACKED;
1557 /** @} */
1558 
1559 /**
1560  * @ingroup MRQ_Codes
1561  * @def MRQ_CPU_VHINT
1562  * @brief Query CPU voltage hint data
1563  *
1564  * * Platforms: T186
1565  * * Initiators: CCPLEX
1566  * * Targets: BPMP
1567  * * Request Payload: @ref mrq_cpu_vhint_request
1568  * * Response Payload: N/A
1569  *
1570  * @addtogroup Vhint CPU Voltage hint
1571  * @{
1572  */
1573 
1574 /**
1575  * @brief request with #MRQ_CPU_VHINT
1576  *
1577  * Used by #MRQ_CPU_VHINT call by CCPLEX to retrieve voltage hint data
1578  * from BPMP to memory space pointed by #addr. CCPLEX is responsible
1579  * to allocate sizeof(cpu_vhint_data) sized block of memory and
1580  * appropriately map it for BPMP before sending the request.
1581  */
1582 struct mrq_cpu_vhint_request {
1583 	/** @brief IOVA address for the #cpu_vhint_data */
1584 	uint32_t addr; /* struct cpu_vhint_data * */
1585 	/** @brief ID of the cluster whose data is requested */
1586 	uint32_t cluster_id; /* enum cluster_id */
1587 } __ABI_PACKED;
1588 
1589 /**
1590  * @brief description of the CPU v/f relation
1591  *
1592  * Used by #MRQ_CPU_VHINT call to carry data pointed by #addr of
1593  * struct mrq_cpu_vhint_request
1594  */
1595 struct cpu_vhint_data {
1596 	uint32_t ref_clk_hz; /**< reference frequency in Hz */
1597 	uint16_t pdiv; /**< post divider value */
1598 	uint16_t mdiv; /**< input divider value */
1599 	uint16_t ndiv_max; /**< fMAX expressed with max NDIV value */
1600 	/** table of ndiv values as a function of vINDEX (voltage index) */
1601 	uint16_t ndiv[80];
1602 	/** minimum allowed NDIV value */
1603 	uint16_t ndiv_min;
1604 	/** minimum allowed voltage hint value (as in vINDEX) */
1605 	uint16_t vfloor;
1606 	/** maximum allowed voltage hint value (as in vINDEX) */
1607 	uint16_t vceil;
1608 	/** post-multiplier for vindex value */
1609 	uint16_t vindex_mult;
1610 	/** post-divider for vindex value */
1611 	uint16_t vindex_div;
1612 	/** reserved for future use */
1613 	uint16_t reserved[328];
1614 } __ABI_PACKED;
1615 
1616 /** @} */
1617 
1618 /**
1619  * @ingroup MRQ_Codes
1620  * @def MRQ_ABI_RATCHET
1621  * @brief ABI ratchet value query
1622  *
1623  * * Platforms: T186
1624  * * Initiators: Any
1625  * * Targets: BPMP
1626  * * Request Payload: @ref mrq_abi_ratchet_request
1627  * * Response Payload: @ref mrq_abi_ratchet_response
1628  * @addtogroup ABI_info
1629  * @{
1630  */
1631 
1632 /**
1633  * @brief an ABI compatibility mechanism
1634  *
1635  * BPMP_ABI_RATCHET_VALUE may increase for various reasons in a future
1636  * revision of this header file.
1637  * 1. That future revision deprecates some MRQ
1638  * 2. That future revision introduces a breaking change to an existing
1639  *    MRQ or
1640  * 3. A bug is discovered in an existing implementation of the BPMP-FW
1641  *    (or possibly one of its clients) which warrants deprecating that
1642  *    implementation.
1643  */
1644 #define BPMP_ABI_RATCHET_VALUE 3
1645 
1646 /**
1647  * @brief request with #MRQ_ABI_RATCHET.
1648  *
1649  * #ratchet should be #BPMP_ABI_RATCHET_VALUE from the ABI header
1650  * against which the requester was compiled.
1651  *
1652  * If ratchet is less than BPMP's #BPMP_ABI_RATCHET_VALUE, BPMP may
1653  * reply with mrq_response::err = -#BPMP_ERANGE to indicate that
1654  * BPMP-FW cannot interoperate correctly with the requester. Requester
1655  * should cease further communication with BPMP.
1656  *
1657  * Otherwise, err shall be 0.
1658  */
1659 struct mrq_abi_ratchet_request {
1660 	/** @brief requester's ratchet value */
1661 	uint16_t ratchet;
1662 };
1663 
1664 /**
1665  * @brief response to #MRQ_ABI_RATCHET
1666  *
1667  * #ratchet shall be #BPMP_ABI_RATCHET_VALUE from the ABI header
1668  * against which BPMP firwmare was compiled.
1669  *
1670  * If #ratchet is less than the requester's #BPMP_ABI_RATCHET_VALUE,
1671  * the requster must either interoperate with BPMP according to an ABI
1672  * header version with BPMP_ABI_RATCHET_VALUE = ratchet or cease
1673  * communication with BPMP.
1674  *
1675  * If mrq_response::err is 0 and ratchet is greater than or equal to the
1676  * requester's BPMP_ABI_RATCHET_VALUE, the requester should continue
1677  * normal operation.
1678  */
1679 struct mrq_abi_ratchet_response {
1680 	/** @brief BPMP's ratchet value */
1681 	uint16_t ratchet;
1682 };
1683 /** @} */
1684 
1685 /**
1686  * @ingroup MRQ_Codes
1687  * @def MRQ_EMC_DVFS_LATENCY
1688  * @brief query frequency dependent EMC DVFS latency
1689  *
1690  * * Platforms: T186
1691  * * Initiators: CCPLEX
1692  * * Targets: BPMP
1693  * * Request Payload: N/A
1694  * * Response Payload: @ref mrq_emc_dvfs_latency_response
1695  * @addtogroup EMC
1696  * @{
1697  */
1698 
1699 /**
1700  * @brief used by @ref mrq_emc_dvfs_latency_response
1701  */
1702 struct emc_dvfs_latency {
1703 	/** @brief EMC frequency in kHz */
1704 	uint32_t freq;
1705 	/** @brief EMC DVFS latency in nanoseconds */
1706 	uint32_t latency;
1707 } __ABI_PACKED;
1708 
1709 #define EMC_DVFS_LATENCY_MAX_SIZE	14
1710 /**
1711  * @brief response to #MRQ_EMC_DVFS_LATENCY
1712  */
1713 struct mrq_emc_dvfs_latency_response {
1714 	/** @brief the number valid entries in #pairs */
1715 	uint32_t num_pairs;
1716 	/** @brief EMC <frequency, latency> information */
1717 	struct emc_dvfs_latency pairs[EMC_DVFS_LATENCY_MAX_SIZE];
1718 } __ABI_PACKED;
1719 
1720 /** @} */
1721 
1722 /**
1723  * @ingroup MRQ_Codes
1724  * @def MRQ_TRACE_ITER
1725  * @brief manage the trace iterator
1726  *
1727  * * Platforms: All
1728  * * Initiators: CCPLEX
1729  * * Targets: BPMP
1730  * * Request Payload: N/A
1731  * * Response Payload: @ref mrq_trace_iter_request
1732  * @addtogroup Trace
1733  * @{
1734  */
1735 enum {
1736 	/** @brief (re)start the tracing now. Ignore older events */
1737 	TRACE_ITER_INIT = 0,
1738 	/** @brief clobber all events in the trace buffer */
1739 	TRACE_ITER_CLEAN = 1
1740 };
1741 
1742 /**
1743  * @brief request with #MRQ_TRACE_ITER
1744  */
1745 struct mrq_trace_iter_request {
1746 	/** @brief TRACE_ITER_INIT or TRACE_ITER_CLEAN */
1747 	uint32_t cmd;
1748 } __ABI_PACKED;
1749 
1750 /** @} */
1751 
1752 /**
1753  * @ingroup MRQ_Codes
1754  * @def MRQ_RINGBUF_CONSOLE
1755  * @brief A ring buffer debug console for BPMP
1756  * @addtogroup RingbufConsole
1757  *
1758  * The ring buffer debug console aims to be a substitute for the UART debug
1759  * console. The debug console is implemented with two ring buffers in the
1760  * BPMP-FW, the RX (receive) and TX (transmit) buffers. Characters can be read
1761  * and written to the buffers by the host via the MRQ interface.
1762  *
1763  * @{
1764  */
1765 
1766 /**
1767  * @brief Maximum number of bytes transferred in a single write command to the
1768  * BPMP
1769  *
1770  * This is determined by the number of free bytes in the message struct,
1771  * rounded down to a multiple of four.
1772  */
1773 #define MRQ_RINGBUF_CONSOLE_MAX_WRITE_LEN 112
1774 
1775 /**
1776  * @brief Maximum number of bytes transferred in a single read command to the
1777  * BPMP
1778  *
1779  * This is determined by the number of free bytes in the message struct,
1780  * rounded down to a multiple of four.
1781  */
1782 #define MRQ_RINGBUF_CONSOLE_MAX_READ_LEN 116
1783 
1784 enum mrq_ringbuf_console_host_to_bpmp_cmd {
1785 	/**
1786 	 * @brief Check whether the BPMP driver supports the specified request
1787 	 * type
1788 	 *
1789 	 * mrq_response::err is 0 if the specified request is supported and
1790 	 * -#BPMP_ENODEV otherwise
1791 	 */
1792 	CMD_RINGBUF_CONSOLE_QUERY_ABI = 0,
1793 	/**
1794 	 * @brief Perform a read operation on the BPMP TX buffer
1795 	 *
1796 	 * mrq_response::err is 0
1797 	 */
1798 	CMD_RINGBUF_CONSOLE_READ = 1,
1799 	/**
1800 	 * @brief Perform a write operation on the BPMP RX buffer
1801 	 *
1802 	 * mrq_response::err is 0 if the operation was successful and
1803 	 * -#BPMP_ENODEV otherwise
1804 	 */
1805 	CMD_RINGBUF_CONSOLE_WRITE = 2,
1806 	/**
1807 	 * @brief Get the length of the buffer and the physical addresses of
1808 	 * the buffer data and the head and tail counters
1809 	 *
1810 	 * mrq_response::err is 0 if the operation was successful and
1811 	 * -#BPMP_ENODEV otherwise
1812 	 */
1813 	CMD_RINGBUF_CONSOLE_GET_FIFO = 3,
1814 };
1815 
1816 /**
1817  * @ingroup RingbufConsole
1818  * @brief Host->BPMP request data for request type
1819  * #CMD_RINGBUF_CONSOLE_QUERY_ABI
1820  */
1821 struct cmd_ringbuf_console_query_abi_req {
1822 	/** @brief Command identifier to be queried */
1823 	uint32_t cmd;
1824 } __ABI_PACKED;
1825 
1826 /** @private */
1827 struct cmd_ringbuf_console_query_abi_resp {
1828 	EMPTY
1829 } __ABI_PACKED;
1830 
1831 /**
1832  * @ingroup RingbufConsole
1833  * @brief Host->BPMP request data for request type #CMD_RINGBUF_CONSOLE_READ
1834  */
1835 struct cmd_ringbuf_console_read_req {
1836 	/**
1837 	 * @brief Number of bytes requested to be read from the BPMP TX buffer
1838 	 */
1839 	uint8_t len;
1840 } __ABI_PACKED;
1841 
1842 /**
1843  * @ingroup RingbufConsole
1844  * @brief BPMP->Host response data for request type #CMD_RINGBUF_CONSOLE_READ
1845  */
1846 struct cmd_ringbuf_console_read_resp {
1847 	/** @brief The actual data read from the BPMP TX buffer */
1848 	uint8_t data[MRQ_RINGBUF_CONSOLE_MAX_READ_LEN];
1849 	/** @brief Number of bytes in cmd_ringbuf_console_read_resp::data */
1850 	uint8_t len;
1851 } __ABI_PACKED;
1852 
1853 /**
1854  * @ingroup RingbufConsole
1855  * @brief Host->BPMP request data for request type #CMD_RINGBUF_CONSOLE_WRITE
1856  */
1857 struct cmd_ringbuf_console_write_req {
1858 	/** @brief The actual data to be written to the BPMP RX buffer */
1859 	uint8_t data[MRQ_RINGBUF_CONSOLE_MAX_WRITE_LEN];
1860 	/** @brief Number of bytes in cmd_ringbuf_console_write_req::data */
1861 	uint8_t len;
1862 } __ABI_PACKED;
1863 
1864 /**
1865  * @ingroup RingbufConsole
1866  * @brief BPMP->Host response data for request type #CMD_RINGBUF_CONSOLE_WRITE
1867  */
1868 struct cmd_ringbuf_console_write_resp {
1869 	/** @brief Number of bytes of available space in the BPMP RX buffer */
1870 	uint32_t space_avail;
1871 	/** @brief Number of bytes that were written to the BPMP RX buffer */
1872 	uint8_t len;
1873 } __ABI_PACKED;
1874 
1875 /** @private */
1876 struct cmd_ringbuf_console_get_fifo_req {
1877 	EMPTY
1878 } __ABI_PACKED;
1879 
1880 /**
1881  * @ingroup RingbufConsole
1882  * @brief BPMP->Host reply data for request type #CMD_RINGBUF_CONSOLE_GET_FIFO
1883  */
1884 struct cmd_ringbuf_console_get_fifo_resp {
1885 	/** @brief Physical address of the BPMP TX buffer */
1886 	uint64_t bpmp_tx_buf_addr;
1887 	/** @brief Physical address of the BPMP TX buffer head counter */
1888 	uint64_t bpmp_tx_head_addr;
1889 	/** @brief Physical address of the BPMP TX buffer tail counter */
1890 	uint64_t bpmp_tx_tail_addr;
1891 	/** @brief Length of the BPMP TX buffer */
1892 	uint32_t bpmp_tx_buf_len;
1893 } __ABI_PACKED;
1894 
1895 /**
1896  * @ingroup RingbufConsole
1897  * @brief Host->BPMP request data.
1898  *
1899  * Reply type is union #mrq_ringbuf_console_bpmp_to_host_response .
1900  */
1901 struct mrq_ringbuf_console_host_to_bpmp_request {
1902 	/**
1903 	 * @brief type of request. Values listed in enum
1904 	 * #mrq_ringbuf_console_host_to_bpmp_cmd.
1905 	 */
1906 	uint32_t type;
1907 	/** @brief  request type specific parameters. */
1908 	union {
1909 		struct cmd_ringbuf_console_query_abi_req query_abi;
1910 		struct cmd_ringbuf_console_read_req read;
1911 		struct cmd_ringbuf_console_write_req write;
1912 		struct cmd_ringbuf_console_get_fifo_req get_fifo;
1913 	} __UNION_ANON;
1914 } __ABI_PACKED;
1915 
1916 /**
1917  * @ingroup RingbufConsole
1918  * @brief Host->BPMP reply data
1919  *
1920  * In response to struct #mrq_ringbuf_console_host_to_bpmp_request.
1921  */
1922 union mrq_ringbuf_console_bpmp_to_host_response {
1923 	struct cmd_ringbuf_console_query_abi_resp query_abi;
1924 	struct cmd_ringbuf_console_read_resp read;
1925 	struct cmd_ringbuf_console_write_resp write;
1926 	struct cmd_ringbuf_console_get_fifo_resp get_fifo;
1927 } __ABI_PACKED;
1928 /** @} */
1929 
1930 /*
1931  *  4. Enumerations
1932  */
1933 
1934 /*
1935  *   4.1 CPU enumerations
1936  *
1937  * See <mach-t186/system-t186.h>
1938  *
1939  *   4.2 CPU Cluster enumerations
1940  *
1941  * See <mach-t186/system-t186.h>
1942  *
1943  *   4.3 System low power state enumerations
1944  *
1945  * See <mach-t186/system-t186.h>
1946  */
1947 
1948 /*
1949  *   4.4 Clock enumerations
1950  *
1951  * For clock enumerations, see <mach-t186/clk-t186.h>
1952  */
1953 
1954 /*
1955  *   4.5 Reset enumerations
1956  *
1957  * For reset enumerations, see <mach-t186/reset-t186.h>
1958  */
1959 
1960 /*
1961  *   4.6 Thermal sensor enumerations
1962  *
1963  * For thermal sensor enumerations, see <mach-t186/thermal-t186.h>
1964  */
1965 
1966 /**
1967  * @defgroup Error_Codes
1968  * Negative values for mrq_response::err generally indicate some
1969  * error. The ABI defines the following error codes. Negating these
1970  * defines is an exercise left to the user.
1971  * @{
1972  */
1973 /** @brief No such file or directory */
1974 #define BPMP_ENOENT	2
1975 /** @brief No MRQ handler */
1976 #define BPMP_ENOHANDLER	3
1977 /** @brief I/O error */
1978 #define BPMP_EIO	5
1979 /** @brief Bad sub-MRQ command */
1980 #define BPMP_EBADCMD	6
1981 /** @brief Not enough memory */
1982 #define BPMP_ENOMEM	12
1983 /** @brief Permission denied */
1984 #define BPMP_EACCES	13
1985 /** @brief Bad address */
1986 #define BPMP_EFAULT	14
1987 /** @brief No such device */
1988 #define BPMP_ENODEV	19
1989 /** @brief Argument is a directory */
1990 #define BPMP_EISDIR	21
1991 /** @brief Invalid argument */
1992 #define BPMP_EINVAL	22
1993 /** @brief Timeout during operation */
1994 #define BPMP_ETIMEDOUT  23
1995 /** @brief Out of range */
1996 #define BPMP_ERANGE	34
1997 /** @} */
1998 /** @} */
1999 #endif
2000