2 * Copyright (c) 2014-2016, NVIDIA CORPORATION.
4 * SPDX-License-Identifier: GPL-2.0
7 #ifndef _ABI_BPMP_ABI_H_
8 #define _ABI_BPMP_ABI_H_
15 #define __ABI_PACKED __attribute__((packed))
18 #ifdef NO_GCC_EXTENSIONS
19 #define EMPTY char empty;
35 * @defgroup MRQ MRQ Messages
36 * @brief Messages sent to/from BPMP via IPC
38 * @defgroup MRQ_Format Message Format
39 * @defgroup MRQ_Codes Message Request (MRQ) Codes
40 * @defgroup MRQ_Payloads Message Payloads
41 * @defgroup Error_Codes Error Codes
46 * @addtogroup MRQ_Format Message Format
48 * The CPU requests the BPMP to perform a particular service by
49 * sending it an IVC frame containing a single MRQ message. An MRQ
50 * message consists of a @ref mrq_request followed by a payload whose
51 * format depends on mrq_request::mrq.
53 * The BPMP processes the data and replies with an IVC frame (on the
54 * same IVC channel) containing and MRQ response. An MRQ response
55 * consists of a @ref mrq_response followed by a payload whose format
56 * depends on the associated mrq_request::mrq.
58 * A well-defined subset of the MRQ messages that the CPU sends to the
59 * BPMP can lead to BPMP eventually sending an MRQ message to the
60 * CPU. For example, when the CPU uses an #MRQ_THERMAL message to set
61 * a thermal trip point, the BPMP may eventually send a single
62 * #MRQ_THERMAL message of its own to the CPU indicating that the trip
63 * point has been crossed.
69 * @brief header for an MRQ message
71 * Provides the MRQ number for the MRQ message: #mrq. The remainder of
72 * the MRQ message is a payload (immediately following the
73 * mrq_request) whose format depends on mrq.
75 * @todo document the flags
78 /** @brief MRQ number of the request */
80 /** @brief flags for the request */
86 * @brief header for an MRQ response
88 * Provides an error code for the associated MRQ message. The
89 * remainder of the MRQ response is a payload (immediately following
90 * the mrq_response) whose format depends on the associated
93 * @todo document the flags
96 /** @brief error code for the MRQ request itself */
98 /** @brief flags for the response */
103 * @ingroup MRQ_Format
104 * Minimum needed size for an IPC message buffer
106 #define MSG_MIN_SZ 128
108 * @ingroup MRQ_Format
109 * Minimum size guaranteed for data in an IPC message buffer
111 #define MSG_DATA_MIN_SZ 120
115 * @name Legal MRQ codes
116 * These are the legal values for mrq_request::mrq
121 #define MRQ_QUERY_TAG 1
122 #define MRQ_MODULE_LOAD 4
123 #define MRQ_MODULE_UNLOAD 5
124 #define MRQ_TRACE_MODIFY 7
125 #define MRQ_WRITE_TRACE 8
126 #define MRQ_THREADED_PING 9
127 #define MRQ_MODULE_MAIL 11
128 #define MRQ_DEBUGFS 19
132 #define MRQ_QUERY_ABI 23
133 #define MRQ_PG_READ_STATE 25
134 #define MRQ_PG_UPDATE_STATE 26
135 #define MRQ_THERMAL 27
136 #define MRQ_CPU_VHINT 28
137 #define MRQ_ABI_RATCHET 29
138 #define MRQ_EMC_DVFS_LATENCY 31
139 #define MRQ_TRACE_ITER 64
145 * @brief Maximum MRQ code to be sent by CPU software to
146 * BPMP. Subject to change in future
148 #define MAX_CPU_MRQ_ID 64
151 * @addtogroup MRQ_Payloads Message Payloads
154 * @defgroup Query_Tag Query Tag
155 * @defgroup Module Loadable Modules
161 * @defgroup ABI_info ABI Info
162 * @defgroup MC_Flush MC Flush
163 * @defgroup Powergating
165 * @defgroup Vhint CPU Voltage hint
166 * @defgroup MRQ_Deprecated Deprecated MRQ messages
175 * @brief A simple ping
180 * * Request Payload: @ref mrq_ping_request
181 * * Response Payload: @ref mrq_ping_response
184 * @def MRQ_THREADED_PING
185 * @brief A deeper ping
190 * * Request Payload: @ref mrq_ping_request
191 * * Response Payload: @ref mrq_ping_response
193 * Behavior is equivalent to a simple #MRQ_PING except that BPMP
194 * responds from a thread context (providing a slightly more robust
201 * @brief request with #MRQ_PING
203 * Used by the sender of an #MRQ_PING message to request a pong from
204 * recipient. The response from the recipient is computed based on
207 struct mrq_ping_request {
208 /** @brief arbitrarily chosen value */
214 * @brief response to #MRQ_PING
216 * Sent in response to an #MRQ_PING message. #reply should be the
217 * mrq_ping_request challenge left shifted by 1 with the carry-bit
221 struct mrq_ping_response {
222 /** @brief response to the MRQ_PING challege */
229 * @brief Query BPMP firmware's tag (i.e. version information)
232 * * Initiators: CCPLEX
234 * * Request Payload: @ref mrq_query_tag_request
235 * * Response Payload: N/A
241 * @brief request with #MRQ_QUERY_TAG
243 * Used by #MRQ_QUERY_TAG call to ask BPMP to fill in the memory
244 * pointed by #addr with BPMP firmware header.
246 * The sender is reponsible for ensuring that #addr is mapped in to
247 * the recipient's address map.
249 struct mrq_query_tag_request {
250 /** @brief base address to store the firmware header */
256 * @def MRQ_MODULE_LOAD
257 * @brief dynamically load a BPMP code module
260 * * Initiators: CCPLEX
262 * * Request Payload: @ref mrq_module_load_request
263 * * Response Payload: @ref mrq_module_load_response
265 * @note This MRQ is disabled on production systems
271 * @brief request with #MRQ_MODULE_LOAD
273 * Used by #MRQ_MODULE_LOAD calls to ask the recipient to dynamically
274 * load the code located at #phys_addr and having size #size
275 * bytes. #phys_addr is treated as a void pointer.
277 * The recipient copies the code from #phys_addr to locally allocated
278 * memory prior to responding to this message.
280 * @todo document the module header format
282 * The sender is responsible for ensuring that the code is mapped in
283 * the recipient's address map.
286 struct mrq_module_load_request {
287 /** @brief base address of the code to load. Treated as (void *) */
288 uint32_t phys_addr; /* (void *) */
289 /** @brief size in bytes of code to load */
295 * @brief response to #MRQ_MODULE_LOAD
297 * @todo document mrq_response::err
299 struct mrq_module_load_response {
300 /** @brief handle to the loaded module */
306 * @def MRQ_MODULE_UNLOAD
307 * @brief unload a previously loaded code module
310 * * Initiators: CCPLEX
312 * * Request Payload: @ref mrq_module_unload_request
313 * * Response Payload: N/A
315 * @note This MRQ is disabled on production systems
320 * @brief request with #MRQ_MODULE_UNLOAD
322 * Used by #MRQ_MODULE_UNLOAD calls to request that a previously loaded
323 * module be unloaded.
325 struct mrq_module_unload_request {
326 /** @brief handle of the module to unload */
332 * @def MRQ_TRACE_MODIFY
333 * @brief modify the set of enabled trace events
336 * * Initiators: CCPLEX
338 * * Request Payload: @ref mrq_trace_modify_request
339 * * Response Payload: @ref mrq_trace_modify_response
341 * @note This MRQ is disabled on production systems
346 * @brief request with #MRQ_TRACE_MODIFY
348 * Used by %MRQ_TRACE_MODIFY calls to enable or disable specify trace
349 * events. #set takes precedence for any bit set in both #set and
352 struct mrq_trace_modify_request {
353 /** @brief bit mask of trace events to disable */
355 /** @brief bit mask of trace events to enable */
361 * @brief response to #MRQ_TRACE_MODIFY
363 * Sent in repsonse to an #MRQ_TRACE_MODIFY message. #mask reflects the
364 * state of which events are enabled after the recipient acted on the
368 struct mrq_trace_modify_response {
369 /** @brief bit mask of trace event enable states */
375 * @def MRQ_WRITE_TRACE
376 * @brief Write trace data to a buffer
379 * * Initiators: CCPLEX
381 * * Request Payload: @ref mrq_write_trace_request
382 * * Response Payload: @ref mrq_write_trace_response
384 * mrq_response::err depends on the @ref mrq_write_trace_request field
385 * values. err is -#BPMP_EINVAL if size is zero or area is NULL or
386 * area is in an illegal range. A positive value for err indicates the
387 * number of bytes written to area.
389 * @note This MRQ is disabled on production systems
394 * @brief request with #MRQ_WRITE_TRACE
396 * Used by MRQ_WRITE_TRACE calls to ask the recipient to copy trace
397 * data from the recipient's local buffer to the output buffer. #area
398 * is treated as a byte-aligned pointer in the recipient's address
401 * The sender is responsible for ensuring that the output
402 * buffer is mapped in the recipient's address map. The recipient is
403 * responsible for protecting its own code and data from accidental
406 struct mrq_write_trace_request {
407 /** @brief base address of output buffer */
409 /** @brief size in bytes of the output buffer */
415 * @brief response to #MRQ_WRITE_TRACE
417 * Once this response is sent, the respondent will not access the
418 * output buffer further.
420 struct mrq_write_trace_response {
422 * @brief flag whether more data remains in local buffer
424 * Value is 1 if the entire local trace buffer has been
425 * drained to the outputbuffer. Value is 0 otherwise.
431 struct mrq_threaded_ping_request {
436 struct mrq_threaded_ping_response {
442 * @def MRQ_MODULE_MAIL
443 * @brief send a message to a loadable module
448 * * Request Payload: @ref mrq_module_mail_request
449 * * Response Payload: @ref mrq_module_mail_response
451 * @note This MRQ is disabled on production systems
456 * @brief request with #MRQ_MODULE_MAIL
458 struct mrq_module_mail_request {
459 /** @brief handle to the previously loaded module */
461 /** @brief module-specific mail payload
463 * The length of data[ ] is unknown to the BPMP core firmware
464 * but it is limited to the size of an IPC message.
466 uint8_t data[EMPTY_ARRAY];
471 * @brief response to #MRQ_MODULE_MAIL
473 struct mrq_module_mail_response {
474 /** @brief module-specific mail payload
476 * The length of data[ ] is unknown to the BPMP core firmware
477 * but it is limited to the size of an IPC message.
479 uint8_t data[EMPTY_ARRAY];
485 * @brief Interact with BPMP's debugfs file nodes
490 * * Request Payload: @ref mrq_debugfs_request
491 * * Response Payload: @ref mrq_debugfs_response
495 * @addtogroup Debugfs
498 * The BPMP firmware implements a pseudo-filesystem called
499 * debugfs. Any driver within the firmware may register with debugfs
500 * to expose an arbitrary set of "files" in the filesystem. When
501 * software on the CPU writes to a debugfs file, debugfs passes the
502 * written data to a callback provided by the driver. When software on
503 * the CPU reads a debugfs file, debugfs queries the driver for the
504 * data to return to the CPU. The intention of the debugfs filesystem
505 * is to provide information useful for debugging the system at
508 * @note The files exposed via debugfs are not part of the
509 * BPMP firmware's ABI. debugfs files may be added or removed in any
510 * given version of the firmware. Typically the semantics of a debugfs
511 * file are consistent from version to version but even that is not
516 /** @ingroup Debugfs */
517 enum mrq_debugfs_commands {
518 CMD_DEBUGFS_READ = 1,
519 CMD_DEBUGFS_WRITE = 2,
520 CMD_DEBUGFS_DUMPDIR = 3,
526 * @brief parameters for CMD_DEBUGFS_READ/WRITE command
528 struct cmd_debugfs_fileop_request {
529 /** @brief physical address pointing at filename */
531 /** @brief length in bytes of filename buffer */
533 /** @brief physical address pointing to data buffer */
535 /** @brief length in bytes of data buffer */
541 * @brief parameters for CMD_DEBUGFS_READ/WRITE command
543 struct cmd_debugfs_dumpdir_request {
544 /** @brief physical address pointing to data buffer */
546 /** @brief length in bytes of data buffer */
552 * @brief response data for CMD_DEBUGFS_READ/WRITE command
554 struct cmd_debugfs_fileop_response {
555 /** @brief always 0 */
557 /** @brief number of bytes read from or written to data buffer */
563 * @brief response data for CMD_DEBUGFS_DUMPDIR command
565 struct cmd_debugfs_dumpdir_response {
566 /** @brief always 0 */
568 /** @brief number of bytes read from or written to data buffer */
574 * @brief request with #MRQ_DEBUGFS.
576 * The sender of an MRQ_DEBUGFS message uses #cmd to specify a debugfs
577 * command to execute. Legal commands are the values of @ref
578 * mrq_debugfs_commands. Each command requires a specific additional
582 * |-------------------|-------|
583 * |CMD_DEBUGFS_READ |fop |
584 * |CMD_DEBUGFS_WRITE |fop |
585 * |CMD_DEBUGFS_DUMPDIR|dumpdir|
587 struct mrq_debugfs_request {
590 struct cmd_debugfs_fileop_request fop;
591 struct cmd_debugfs_dumpdir_request dumpdir;
598 struct mrq_debugfs_response {
599 /** @brief always 0 */
602 /** @brief response data for CMD_DEBUGFS_READ OR
603 * CMD_DEBUGFS_WRITE command
605 struct cmd_debugfs_fileop_response fop;
606 /** @brief response data for CMD_DEBUGFS_DUMPDIR command */
607 struct cmd_debugfs_dumpdir_response dumpdir;
612 * @addtogroup Debugfs
615 #define DEBUGFS_S_ISDIR (1 << 9)
616 #define DEBUGFS_S_IRUSR (1 << 8)
617 #define DEBUGFS_S_IWUSR (1 << 7)
624 * @brief reset an IP block
629 * * Request Payload: @ref mrq_reset_request
630 * * Response Payload: N/A
636 enum mrq_reset_commands {
637 CMD_RESET_ASSERT = 1,
638 CMD_RESET_DEASSERT = 2,
639 CMD_RESET_MODULE = 3,
640 CMD_RESET_MAX, /* not part of ABI and subject to change */
645 * @brief request with MRQ_RESET
647 * Used by the sender of an #MRQ_RESET message to request BPMP to
648 * assert or or deassert a given reset line.
650 struct mrq_reset_request {
651 /** @brief reset action to perform (@enum mrq_reset_commands) */
653 /** @brief id of the reset to affected */
660 * @brief issue an i2c transaction
665 * * Request Payload: @ref mrq_i2c_request
666 * * Response Payload: @ref mrq_i2c_response
673 #define TEGRA_I2C_IPC_MAX_IN_BUF_SIZE (MSG_DATA_MIN_SZ - 12)
674 #define TEGRA_I2C_IPC_MAX_OUT_BUF_SIZE (MSG_DATA_MIN_SZ - 4)
679 * @name Serial I2C flags
680 * Use these flags with serial_i2c_request::flags
683 #define SERIALI2C_TEN 0x0010
684 #define SERIALI2C_RD 0x0001
685 #define SERIALI2C_STOP 0x8000
686 #define SERIALI2C_NOSTART 0x4000
687 #define SERIALI2C_REV_DIR_ADDR 0x2000
688 #define SERIALI2C_IGNORE_NAK 0x1000
689 #define SERIALI2C_NO_RD_ACK 0x0800
690 #define SERIALI2C_RECV_LEN 0x0400
699 * @brief serializable i2c request
701 * Instances of this structure are packed (little-endian) into
702 * cmd_i2c_xfer_request::data_buf. Each instance represents a single
703 * transaction (or a portion of a transaction with repeated starts) on
706 * Because these structures are packed, some instances are likely to
707 * be misaligned. Additionally because #data is variable length, it is
708 * not possible to iterate through a serialized list of these
709 * structures without inspecting #len in each instance. It may be
710 * easier to serialize or deserialize cmd_i2c_xfer_request::data_buf
711 * manually rather than using this structure definition.
713 struct serial_i2c_request {
714 /** @brief I2C slave address */
716 /** @brief bitmask of SERIALI2C_ flags */
718 /** @brief length of I2C transaction in bytes */
720 /** @brief for write transactions only, #len bytes of data */
726 * @brief trigger one or more i2c transactions
728 struct cmd_i2c_xfer_request {
729 /** @brief valid bus number from mach-t186/i2c-t186.h*/
732 /** @brief count of valid bytes in #data_buf*/
735 /** @brief serialized packed instances of @ref serial_i2c_request*/
736 uint8_t data_buf[TEGRA_I2C_IPC_MAX_IN_BUF_SIZE];
741 * @brief container for data read from the i2c bus
743 * Processing an cmd_i2c_xfer_request::data_buf causes BPMP to execute
744 * zero or more I2C reads. The data read from the bus is serialized
747 struct cmd_i2c_xfer_response {
748 /** @brief count of valid bytes in #data_buf*/
750 /** @brief i2c read data */
751 uint8_t data_buf[TEGRA_I2C_IPC_MAX_OUT_BUF_SIZE];
756 * @brief request with #MRQ_I2C
758 struct mrq_i2c_request {
759 /** @brief always CMD_I2C_XFER (i.e. 1) */
761 /** @brief parameters of the transfer request */
762 struct cmd_i2c_xfer_request xfer;
767 * @brief response to #MRQ_I2C
769 struct mrq_i2c_response {
770 struct cmd_i2c_xfer_response xfer;
780 * * Request Payload: @ref mrq_clk_request
781 * * Response Payload: @ref mrq_clk_response
787 * @name MRQ_CLK sub-commands
791 CMD_CLK_GET_RATE = 1,
792 CMD_CLK_SET_RATE = 2,
793 CMD_CLK_ROUND_RATE = 3,
794 CMD_CLK_GET_PARENT = 4,
795 CMD_CLK_SET_PARENT = 5,
796 CMD_CLK_IS_ENABLED = 6,
799 CMD_CLK_GET_ALL_INFO = 14,
800 CMD_CLK_GET_MAX_CLK_ID = 15,
805 #define MRQ_CLK_NAME_MAXLEN 40
806 #define MRQ_CLK_MAX_PARENTS 16
809 struct cmd_clk_get_rate_request {
813 struct cmd_clk_get_rate_response {
817 struct cmd_clk_set_rate_request {
822 struct cmd_clk_set_rate_response {
826 struct cmd_clk_round_rate_request {
831 struct cmd_clk_round_rate_response {
836 struct cmd_clk_get_parent_request {
840 struct cmd_clk_get_parent_response {
844 struct cmd_clk_set_parent_request {
848 struct cmd_clk_set_parent_response {
853 struct cmd_clk_is_enabled_request {
857 struct cmd_clk_is_enabled_response {
862 struct cmd_clk_enable_request {
867 struct cmd_clk_enable_response {
872 struct cmd_clk_disable_request {
877 struct cmd_clk_disable_response {
882 struct cmd_clk_get_all_info_request {
886 struct cmd_clk_get_all_info_response {
889 uint32_t parents[MRQ_CLK_MAX_PARENTS];
891 uint8_t name[MRQ_CLK_NAME_MAXLEN];
895 struct cmd_clk_get_max_clk_id_request {
899 struct cmd_clk_get_max_clk_id_response {
906 * @brief request with #MRQ_CLK
908 * Used by the sender of an #MRQ_CLK message to control clocks. The
909 * clk_request is split into several sub-commands. Some sub-commands
910 * require no additional data. Others have a sub-command specific
913 * |sub-command |payload |
914 * |----------------------------|-----------------------|
915 * |CMD_CLK_GET_RATE |- |
916 * |CMD_CLK_SET_RATE |clk_set_rate |
917 * |CMD_CLK_ROUND_RATE |clk_round_rate |
918 * |CMD_CLK_GET_PARENT |- |
919 * |CMD_CLK_SET_PARENT |clk_set_parent |
920 * |CMD_CLK_IS_ENABLED |- |
921 * |CMD_CLK_ENABLE |- |
922 * |CMD_CLK_DISABLE |- |
923 * |CMD_CLK_GET_ALL_INFO |- |
924 * |CMD_CLK_GET_MAX_CLK_ID |- |
928 struct mrq_clk_request {
929 /** @brief sub-command and clock id concatenated to 32-bit word.
930 * - bits[31..24] is the sub-cmd.
931 * - bits[23..0] is the clock id
937 struct cmd_clk_get_rate_request clk_get_rate;
938 struct cmd_clk_set_rate_request clk_set_rate;
939 struct cmd_clk_round_rate_request clk_round_rate;
941 struct cmd_clk_get_parent_request clk_get_parent;
942 struct cmd_clk_set_parent_request clk_set_parent;
944 struct cmd_clk_enable_request clk_enable;
946 struct cmd_clk_disable_request clk_disable;
948 struct cmd_clk_is_enabled_request clk_is_enabled;
950 struct cmd_clk_get_all_info_request clk_get_all_info;
952 struct cmd_clk_get_max_clk_id_request clk_get_max_clk_id;
958 * @brief response to MRQ_CLK
960 * Each sub-command supported by @ref mrq_clk_request may return
961 * sub-command-specific data. Some do and some do not as indicated in
962 * the following table
964 * |sub-command |payload |
965 * |----------------------------|------------------------|
966 * |CMD_CLK_GET_RATE |clk_get_rate |
967 * |CMD_CLK_SET_RATE |clk_set_rate |
968 * |CMD_CLK_ROUND_RATE |clk_round_rate |
969 * |CMD_CLK_GET_PARENT |clk_get_parent |
970 * |CMD_CLK_SET_PARENT |clk_set_parent |
971 * |CMD_CLK_IS_ENABLED |clk_is_enabled |
972 * |CMD_CLK_ENABLE |- |
973 * |CMD_CLK_DISABLE |- |
974 * |CMD_CLK_GET_ALL_INFO |clk_get_all_info |
975 * |CMD_CLK_GET_MAX_CLK_ID |clk_get_max_id |
979 struct mrq_clk_response {
981 struct cmd_clk_get_rate_response clk_get_rate;
982 struct cmd_clk_set_rate_response clk_set_rate;
983 struct cmd_clk_round_rate_response clk_round_rate;
984 struct cmd_clk_get_parent_response clk_get_parent;
985 struct cmd_clk_set_parent_response clk_set_parent;
987 struct cmd_clk_enable_response clk_enable;
989 struct cmd_clk_disable_response clk_disable;
990 struct cmd_clk_is_enabled_response clk_is_enabled;
991 struct cmd_clk_get_all_info_response clk_get_all_info;
992 struct cmd_clk_get_max_clk_id_response clk_get_max_clk_id;
999 * @brief check if an MRQ is implemented
1004 * * Request Payload: @ref mrq_query_abi_request
1005 * * Response Payload: @ref mrq_query_abi_response
1010 * @brief request with MRQ_QUERY_ABI
1012 * Used by #MRQ_QUERY_ABI call to check if MRQ code #mrq is supported
1015 struct mrq_query_abi_request {
1016 /** @brief MRQ code to query */
1022 * @brief response to MRQ_QUERY_ABI
1024 struct mrq_query_abi_response {
1025 /** @brief 0 if queried MRQ is supported. Else, -#BPMP_ENODEV */
1030 * @ingroup MRQ_Codes
1031 * @def MRQ_PG_READ_STATE
1032 * @brief read the power-gating state of a partition
1037 * * Request Payload: @ref mrq_pg_read_state_request
1038 * * Response Payload: @ref mrq_pg_read_state_response
1039 * @addtogroup Powergating
1044 * @brief request with #MRQ_PG_READ_STATE
1046 * Used by MRQ_PG_READ_STATE call to read the current state of a
1049 struct mrq_pg_read_state_request {
1050 /** @brief ID of partition */
1051 uint32_t partition_id;
1055 * @brief response to MRQ_PG_READ_STATE
1056 * @todo define possible errors.
1058 struct mrq_pg_read_state_response {
1059 /** @brief read as don't care */
1060 uint32_t sram_state;
1061 /** @brief state of power partition
1065 uint32_t logic_state;
1071 * @ingroup MRQ_Codes
1072 * @def MRQ_PG_UPDATE_STATE
1073 * @brief modify the power-gating state of a partition
1078 * * Request Payload: @ref mrq_pg_update_state_request
1079 * * Response Payload: N/A
1080 * @addtogroup Powergating
1085 * @brief request with mrq_pg_update_state_request
1087 * Used by #MRQ_PG_UPDATE_STATE call to request BPMP to change the
1088 * state of a power partition #partition_id.
1090 struct mrq_pg_update_state_request {
1091 /** @brief ID of partition */
1092 uint32_t partition_id;
1093 /** @brief secondary control of power partition
1094 * @details Ignored by many versions of the BPMP
1095 * firmware. For maximum compatibility, set the value
1096 * according to @logic_state
1097 * * 0x1: power ON partition (@ref logic_state == 0x3)
1098 * * 0x3: power OFF partition (@ref logic_state == 0x1)
1100 uint32_t sram_state;
1101 /** @brief controls state of power partition, legal values are
1102 * * 0x1 : power OFF partition
1103 * * 0x3 : power ON partition
1105 uint32_t logic_state;
1106 /** @brief change state of clocks of the power partition, legal values
1107 * * 0x0 : do not change clock state
1108 * * 0x1 : disable partition clocks (only applicable when
1109 * @ref logic_state == 0x1)
1110 * * 0x3 : enable partition clocks (only applicable when
1111 * @ref logic_state == 0x3)
1113 uint32_t clock_state;
1118 * @ingroup MRQ_Codes
1120 * @brief interact with BPMP thermal framework
1125 * * Request Payload: TODO
1126 * * Response Payload: TODO
1128 * @addtogroup Thermal
1130 * The BPMP firmware includes a thermal framework. Drivers within the
1131 * bpmp firmware register with the framework to provide thermal
1132 * zones. Each thermal zone corresponds to an entity whose temperature
1133 * can be measured. The framework also has a notion of trip points. A
1134 * trip point consists of a thermal zone id, a temperature, and a
1135 * callback routine. The framework invokes the callback when the zone
1136 * hits the indicated temperature. The BPMP firmware uses this thermal
1137 * framework interally to implement various temperature-dependent
1140 * Software on the CPU can use #MRQ_THERMAL (with payload @ref
1141 * mrq_thermal_host_to_bpmp_request) to interact with the BPMP thermal
1142 * framework. The CPU must It can query the number of supported zones,
1143 * query zone temperatures, and set trip points.
1145 * When a trip point set by the CPU gets crossed, BPMP firmware issues
1146 * an IPC to the CPU having mrq_request::mrq = #MRQ_THERMAL and a
1147 * payload of @ref mrq_thermal_bpmp_to_host_request.
1150 enum mrq_thermal_host_to_bpmp_cmd {
1152 * @brief Check whether the BPMP driver supports the specified
1155 * Host needs to supply request parameters.
1157 * mrq_response::err is 0 if the specified request is
1158 * supported and -#BPMP_ENODEV otherwise.
1160 CMD_THERMAL_QUERY_ABI = 0,
1163 * @brief Get the current temperature of the specified zone.
1165 * Host needs to supply request parameters.
1167 * mrq_response::err is
1168 * * 0: Temperature query succeeded.
1169 * * -#BPMP_EINVAL: Invalid request parameters.
1170 * * -#BPMP_ENOENT: No driver registered for thermal zone..
1171 * * -#BPMP_EFAULT: Problem reading temperature measurement.
1173 CMD_THERMAL_GET_TEMP = 1,
1176 * @brief Enable or disable and set the lower and upper
1177 * thermal limits for a thermal trip point. Each zone has
1180 * Host needs to supply request parameters. Once the
1181 * temperature hits a trip point, the BPMP will send a message
1182 * to the CPU having MRQ=MRQ_THERMAL and
1183 * type=CMD_THERMAL_HOST_TRIP_REACHED
1185 * mrq_response::err is
1186 * * 0: Trip successfully set.
1187 * * -#BPMP_EINVAL: Invalid request parameters.
1188 * * -#BPMP_ENOENT: No driver registered for thermal zone.
1189 * * -#BPMP_EFAULT: Problem setting trip point.
1191 CMD_THERMAL_SET_TRIP = 2,
1194 * @brief Get the number of supported thermal zones.
1196 * No request parameters required.
1198 * mrq_response::err is always 0, indicating success.
1200 CMD_THERMAL_GET_NUM_ZONES = 3,
1202 /** @brief: number of supported host-to-bpmp commands. May
1203 * increase in future
1205 CMD_THERMAL_HOST_TO_BPMP_NUM
1208 enum mrq_thermal_bpmp_to_host_cmd {
1210 * @brief Indication that the temperature for a zone has
1211 * exceeded the range indicated in the thermal trip point
1214 * BPMP needs to supply request parameters. Host only needs to
1217 CMD_THERMAL_HOST_TRIP_REACHED = 100,
1219 /** @brief: number of supported bpmp-to-host commands. May
1220 * increase in future
1222 CMD_THERMAL_BPMP_TO_HOST_NUM
1226 * Host->BPMP request data for request type CMD_THERMAL_QUERY_ABI
1228 * zone: Request type for which to check existence.
1230 struct cmd_thermal_query_abi_request {
1235 * Host->BPMP request data for request type CMD_THERMAL_GET_TEMP
1237 * zone: Number of thermal zone.
1239 struct cmd_thermal_get_temp_request {
1244 * BPMP->Host reply data for request CMD_THERMAL_GET_TEMP
1246 * error: 0 if request succeeded.
1247 * -BPMP_EINVAL if request parameters were invalid.
1248 * -BPMP_ENOENT if no driver was registered for the specified thermal zone.
1249 * -BPMP_EFAULT for other thermal zone driver errors.
1250 * temp: Current temperature in millicelsius.
1252 struct cmd_thermal_get_temp_response {
1257 * Host->BPMP request data for request type CMD_THERMAL_SET_TRIP
1259 * zone: Number of thermal zone.
1260 * low: Temperature of lower trip point in millicelsius
1261 * high: Temperature of upper trip point in millicelsius
1262 * enabled: 1 to enable trip point, 0 to disable trip point
1264 struct cmd_thermal_set_trip_request {
1272 * BPMP->Host request data for request type CMD_THERMAL_HOST_TRIP_REACHED
1274 * zone: Number of thermal zone where trip point was reached.
1276 struct cmd_thermal_host_trip_reached_request {
1281 * BPMP->Host reply data for request type CMD_THERMAL_GET_NUM_ZONES
1283 * num: Number of supported thermal zones. The thermal zones are indexed
1284 * starting from zero.
1286 struct cmd_thermal_get_num_zones_response {
1291 * Host->BPMP request data.
1293 * Reply type is union mrq_thermal_bpmp_to_host_response.
1295 * type: Type of request. Values listed in enum mrq_thermal_type.
1296 * data: Request type specific parameters.
1298 struct mrq_thermal_host_to_bpmp_request {
1301 struct cmd_thermal_query_abi_request query_abi;
1302 struct cmd_thermal_get_temp_request get_temp;
1303 struct cmd_thermal_set_trip_request set_trip;
1308 * BPMP->Host request data.
1310 * type: Type of request. Values listed in enum mrq_thermal_type.
1311 * data: Request type specific parameters.
1313 struct mrq_thermal_bpmp_to_host_request {
1316 struct cmd_thermal_host_trip_reached_request host_trip_reached;
1321 * Data in reply to a Host->BPMP request.
1323 union mrq_thermal_bpmp_to_host_response {
1324 struct cmd_thermal_get_temp_response get_temp;
1325 struct cmd_thermal_get_num_zones_response get_num_zones;
1330 * @ingroup MRQ_Codes
1331 * @def MRQ_CPU_VHINT
1332 * @brief Query CPU voltage hint data
1335 * * Initiators: CCPLEX
1337 * * Request Payload: @ref mrq_cpu_vhint_request
1338 * * Response Payload: N/A
1340 * @addtogroup Vhint CPU Voltage hint
1345 * @brief request with #MRQ_CPU_VHINT
1347 * Used by #MRQ_CPU_VHINT call by CCPLEX to retrieve voltage hint data
1348 * from BPMP to memory space pointed by #addr. CCPLEX is responsible
1349 * to allocate sizeof(cpu_vhint_data) sized block of memory and
1350 * appropriately map it for BPMP before sending the request.
1352 struct mrq_cpu_vhint_request {
1353 /** @brief IOVA address for the #cpu_vhint_data */
1354 uint32_t addr; /* struct cpu_vhint_data * */
1355 /** @brief ID of the cluster whose data is requested */
1356 uint32_t cluster_id; /* enum cluster_id */
1360 * @brief description of the CPU v/f relation
1362 * Used by #MRQ_CPU_VHINT call to carry data pointed by #addr of
1363 * struct mrq_cpu_vhint_request
1365 struct cpu_vhint_data {
1366 uint32_t ref_clk_hz; /**< reference frequency in Hz */
1367 uint16_t pdiv; /**< post divider value */
1368 uint16_t mdiv; /**< input divider value */
1369 uint16_t ndiv_max; /**< fMAX expressed with max NDIV value */
1370 /** table of ndiv values as a function of vINDEX (voltage index) */
1372 /** minimum allowed NDIV value */
1374 /** minimum allowed voltage hint value (as in vINDEX) */
1376 /** maximum allowed voltage hint value (as in vINDEX) */
1378 /** post-multiplier for vindex value */
1379 uint16_t vindex_mult;
1380 /** post-divider for vindex value */
1381 uint16_t vindex_div;
1382 /** reserved for future use */
1383 uint16_t reserved[328];
1389 * @ingroup MRQ_Codes
1390 * @def MRQ_ABI_RATCHET
1391 * @brief ABI ratchet value query
1396 * * Request Payload: @ref mrq_abi_ratchet_request
1397 * * Response Payload: @ref mrq_abi_ratchet_response
1398 * @addtogroup ABI_info
1403 * @brief an ABI compatibility mechanism
1405 * BPMP_ABI_RATCHET_VALUE may increase for various reasons in a future
1406 * revision of this header file.
1407 * 1. That future revision deprecates some MRQ
1408 * 2. That future revision introduces a breaking change to an existing
1410 * 3. A bug is discovered in an existing implementation of the BPMP-FW
1411 * (or possibly one of its clients) which warrants deprecating that
1414 #define BPMP_ABI_RATCHET_VALUE 3
1417 * @brief request with #MRQ_ABI_RATCHET.
1419 * #ratchet should be #BPMP_ABI_RATCHET_VALUE from the ABI header
1420 * against which the requester was compiled.
1422 * If ratchet is less than BPMP's #BPMP_ABI_RATCHET_VALUE, BPMP may
1423 * reply with mrq_response::err = -#BPMP_ERANGE to indicate that
1424 * BPMP-FW cannot interoperate correctly with the requester. Requester
1425 * should cease further communication with BPMP.
1427 * Otherwise, err shall be 0.
1429 struct mrq_abi_ratchet_request {
1430 /** @brief requester's ratchet value */
1435 * @brief response to #MRQ_ABI_RATCHET
1437 * #ratchet shall be #BPMP_ABI_RATCHET_VALUE from the ABI header
1438 * against which BPMP firwmare was compiled.
1440 * If #ratchet is less than the requester's #BPMP_ABI_RATCHET_VALUE,
1441 * the requster must either interoperate with BPMP according to an ABI
1442 * header version with BPMP_ABI_RATCHET_VALUE = ratchet or cease
1443 * communication with BPMP.
1445 * If mrq_response::err is 0 and ratchet is greater than or equal to the
1446 * requester's BPMP_ABI_RATCHET_VALUE, the requester should continue
1449 struct mrq_abi_ratchet_response {
1450 /** @brief BPMP's ratchet value */
1456 * @ingroup MRQ_Codes
1457 * @def MRQ_EMC_DVFS_LATENCY
1458 * @brief query frequency dependent EMC DVFS latency
1461 * * Initiators: CCPLEX
1463 * * Request Payload: N/A
1464 * * Response Payload: @ref mrq_emc_dvfs_latency_response
1470 * @brief used by @ref mrq_emc_dvfs_latency_response
1472 struct emc_dvfs_latency {
1473 /** @brief EMC frequency in kHz */
1475 /** @brief EMC DVFS latency in nanoseconds */
1479 #define EMC_DVFS_LATENCY_MAX_SIZE 14
1481 * @brief response to #MRQ_EMC_DVFS_LATENCY
1483 struct mrq_emc_dvfs_latency_response {
1484 /** @brief the number valid entries in #pairs */
1486 /** @brief EMC <frequency, latency> information */
1487 struct emc_dvfs_latency pairs[EMC_DVFS_LATENCY_MAX_SIZE];
1493 * @ingroup MRQ_Codes
1494 * @def MRQ_TRACE_ITER
1495 * @brief manage the trace iterator
1498 * * Initiators: CCPLEX
1500 * * Request Payload: N/A
1501 * * Response Payload: @ref mrq_trace_iter_request
1506 /** @brief (re)start the tracing now. Ignore older events */
1507 TRACE_ITER_INIT = 0,
1508 /** @brief clobber all events in the trace buffer */
1509 TRACE_ITER_CLEAN = 1
1513 * @brief request with #MRQ_TRACE_ITER
1515 struct mrq_trace_iter_request {
1516 /** @brief TRACE_ITER_INIT or TRACE_ITER_CLEAN */
1527 * 4.1 CPU enumerations
1529 * See <mach-t186/system-t186.h>
1531 * 4.2 CPU Cluster enumerations
1533 * See <mach-t186/system-t186.h>
1535 * 4.3 System low power state enumerations
1537 * See <mach-t186/system-t186.h>
1541 * 4.4 Clock enumerations
1543 * For clock enumerations, see <mach-t186/clk-t186.h>
1547 * 4.5 Reset enumerations
1549 * For reset enumerations, see <mach-t186/reset-t186.h>
1553 * 4.6 Thermal sensor enumerations
1555 * For thermal sensor enumerations, see <mach-t186/thermal-t186.h>
1559 * @defgroup Error_Codes
1560 * Negative values for mrq_response::err generally indicate some
1561 * error. The ABI defines the following error codes. Negating these
1562 * defines is an exercise left to the user.
1565 /** @brief No such file or directory */
1566 #define BPMP_ENOENT 2
1567 /** @brief No MRQ handler */
1568 #define BPMP_ENOHANDLER 3
1569 /** @brief I/O error */
1571 /** @brief Bad sub-MRQ command */
1572 #define BPMP_EBADCMD 6
1573 /** @brief Not enough memory */
1574 #define BPMP_ENOMEM 12
1575 /** @brief Permission denied */
1576 #define BPMP_EACCES 13
1577 /** @brief Bad address */
1578 #define BPMP_EFAULT 14
1579 /** @brief No such device */
1580 #define BPMP_ENODEV 19
1581 /** @brief Argument is a directory */
1582 #define BPMP_EISDIR 21
1583 /** @brief Invalid argument */
1584 #define BPMP_EINVAL 22
1585 /** @brief Timeout during operation */
1586 #define BPMP_ETIMEDOUT 23
1587 /** @brief Out of range */
1588 #define BPMP_ERANGE 34