From 3c1c8cb6721865525c7e905bd00a1194b3b30368 Mon Sep 17 00:00:00 2001 From: Mika Liljeberg Date: Fri, 27 Oct 2023 11:29:15 +0300 Subject: [PATCH] firmware-api: document HSP-VM mailbox commands Updated the documentation for HSP-VM mailbox messages and the related definitions and data structures. Jira CAMERASW-14056 Change-Id: I734c921647fe0408b89adbfce82d4bc471a2c315 Reviewed-on: https://git-master.nvidia.com/r/c/tegra/camera/firmware-api/+/3007234 Signed-off-by: Mika Liljeberg Reviewed-on: https://git-master.nvidia.com/r/c/linux-nv-oot/+/3009887 (cherry picked from commit 9662cc3124f3a9ed6bdc9b4aca46480c7f43f162) Reviewed-on: https://git-master.nvidia.com/r/c/linux-nv-oot/+/3011732 Reviewed-by: Matti Ryttylainen Reviewed-by: Frank Chen GVS: Gerrit_Virtual_Submit --- include/soc/tegra/camrtc-channels.h | 143 ++++++- include/soc/tegra/camrtc-commands.h | 638 ++++++++++++++++++++++++---- 2 files changed, 679 insertions(+), 102 deletions(-) diff --git a/include/soc/tegra/camrtc-channels.h b/include/soc/tegra/camrtc-channels.h index 0964aae0..dc0e149c 100644 --- a/include/soc/tegra/camrtc-channels.h +++ b/include/soc/tegra/camrtc-channels.h @@ -15,11 +15,22 @@ #include "camrtc-common.h" /** - * @defgroups RceTags RCE tags + * @brief Create 64-bit TLV tag value from characters. * - * All the enums and the fields inside the structs described in this header - * file supports only uintX_t types, where X can be 8,16,32,64. - * @{ + * Combine 8 character values into a 64-bit tag value. + * + * @pre None. + * + * @param s0 1st character (LSB) [0,UINT8_MAX] + * @param s1 2nd character [0,UINT8_MAX] + * @param s2 3rd character [0,UINT8_MAX] + * @param s3 4th character [0,UINT8_MAX] + * @param s4 5th character [0,UINT8_MAX] + * @param s5 6th character [0,UINT8_MAX] + * @param s6 7th character [0,UINT8_MAX] + * @param s7 8th character (MSB) [0,UINT8_MAX] + * + * @return 64-bit TLV tag value (uint64_t) */ #define CAMRTC_TAG64(s0, s1, s2, s3, s4, s5, s6, s7) ( \ ((uint64_t)(s0) << 0U) | ((uint64_t)(s1) << 8U) | \ @@ -27,19 +38,70 @@ ((uint64_t)(s4) << 32U) | ((uint64_t)(s5) << 40U) | \ ((uint64_t)(s6) << 48U) | ((uint64_t)(s7) << 56U)) -#define CAMRTC_TAG_IVC_SETUP CAMRTC_TAG64('I', 'V', 'C', '-', 'S', 'E', 'T', 'U') -#define CAMRTC_TAG_NV_TRACE CAMRTC_TAG64('N', 'V', ' ', 'T', 'R', 'A', 'C', 'E') -#define CAMRTC_TAG_NV_TRCON CAMRTC_TAG64('N', 'V', ' ', 'T', 'R', 'C', 'O', 'N') -#define CAMRTC_TAG_NV_COVERAGE CAMRTC_TAG64('N', 'V', ' ', 'C', 'O', 'V', 'E', 'R') -/** }@ */ +/** + * @defgroup RceTags Command tags for shared memory setup + * @{ + */ /** - * @brief RCE Tag, length, and value (TLV) + * @ref RceTags "Command tag" for IVC channel setup. In this case, the TLV + * instance is a @ref camrtc_tlv_ivc_setup "IVC setup header" with IVC channel + * parameters. Multiple such TLV entries may provided as a list to configure + * multiple IVC channels. The TLV list must be terminated with the + * @ref CAMRTC_TAG_TLV_NULL command tag. + */ +#define CAMRTC_TAG_IVC_SETUP CAMRTC_TAG64('I', 'V', 'C', '-', 'S', 'E', 'T', 'U') + +/** + * @ref RceTags "Command tag" for trace buffer setup. In this case, the TLV + * instance is a @ref camrtc_trace_memory_header "trace memory header" and will + * not be followed by any additional TLV entries. This tag is used to set up + * a trace buffer and to indicate that the trace receiver does not support + * string format console prints via the trace system. In this case, RCE FW will + * route any console prints to another console port, such as TCU, if available. + * (non-safety) + */ +#define CAMRTC_TAG_NV_TRACE CAMRTC_TAG64('N', 'V', ' ', 'T', 'R', 'A', 'C', 'E') + +/** + * @ref RceTags "Command tag" for trace buffer setup. In this case, the TLV + * is a @ref camrtc_trace_memory_header "trace memory header" and will + * not be followed by any additional TLV entries. This tag is used to set up + * a trace buffer and to indicate that the trace receiver additionally support + * console prints via the trace system, and will route any string format log + * and debug prints to the console and/or store them in an appropriate system + * log. (non-safety) + */ +#define CAMRTC_TAG_NV_TRCON CAMRTC_TAG64('N', 'V', ' ', 'T', 'R', 'C', 'O', 'N') + +/** + * @ref RceTags "Command tag" for falcon coverage buffer setup. In this case, the + * TLV isa @ref camrtc_coverage_memory_header "coverage memory header" and will + * not be followed by any additional TLV entries. (non-safety) + */ +#define CAMRTC_TAG_NV_COVERAGE CAMRTC_TAG64('N', 'V', ' ', 'C', 'O', 'V', 'E', 'R') + +/** + * @ref RceTags "Command tag" for terminating a TLV list. + */ +#define CAMRTC_TAG_NV_NULL MK_U64(0) +/** @} */ + +/** + * @brief RCE Tag, length, and value (TLV) descriptor. + * + * The structure is followed in memory by a variable length payload. + * The generic TLV descriptors may be concatenated into a list, which + * must be terminated with the @ref CAMRTC_TAG_NV_NULL "NULL TLV". */ struct camrtc_tlv { - /** Command tag. See @ref RceTags "RCE Tags" */ + /** @ref RceTags "Command tag" for shared memory setup. */ uint64_t tag; - /** Length of the tag specific data */ + + /** + * Total length of the TLV (sizeof(@erf camrtc_tlv) + sizeof(Value)) + * [0,UINT64_MAX]. Must be a multiple of 8. + */ uint64_t len; }; @@ -49,27 +111,50 @@ struct camrtc_tlv { * Multiple setup structures can follow each other. */ struct camrtc_tlv_ivc_setup { - /** Command tag. See @ref RceTags "RCE Tags" */ + /** @ref CAMRTC_TAG_IVC_SETUP "IVC setup command tag". */ uint64_t tag; - /** Length of the tag specific data */ + + /** + * Length of the tag specific data. Must be >= + * sizeof(@ref camrtc_tlv_ivc_setup) and a multiple of 8. + */ uint64_t len; - /** Base address of write header. RX from CCPLEX point of view */ + + /** + * Base IOVA address of IVC read header. Receive queue from CCPLEX + * point of view. Must be non-zero and multiple of 64. + */ uint64_t rx_iova; - /** Size of IVC write frame */ + + /** Size of IVC RX frame. Must be non-zero and a multiple of 64. */ uint32_t rx_frame_size; - /** Number of IVC write frames */ + + /** Size of the queue as number of RX frames [1,UINT32_MAX]. */ uint32_t rx_nframes; - /** Base address of read header. TX from CCPLEX point of view */ + + /** + * Base IOVA address of write header. Transmit queue from CCPLEX + * point of view. Must be non-zero and multiple of 64. + */ uint64_t tx_iova; - /** Size of IVC read frame */ + + /** Size of IVC TX frame. Must be non-zero and a multiple of 64. */ uint32_t tx_frame_size; - /** Number of IVC read frames */ + + /** Maximum number of IVC TX frames in the queue [1,UINT32_MAX]. */ uint32_t tx_nframes; - /** IVC channel group*/ + + /** + * IVC channel group mask [1, @ref CAMRTC_HSP_SS_IVC_MASK]. + * A bit-mask indicating which IVC channel wakeup group(s) + * the IVC channel belongs to (see @ref CAMRTC_HSP_IRQ). + */ uint32_t channel_group; - /** IVC version */ + + /** Version number of the IVC service [0,UINT32_MAX]. */ uint32_t ivc_version; - /** IVC service name */ + + /** IVC service name. Need not be NUL terminated. */ char ivc_service[32]; }; @@ -77,11 +162,23 @@ struct camrtc_tlv_ivc_setup { * @defgroup CamRTCChannelErrors Channel setup error codes * @{ */ + +/** Channel setup successful. */ #define RTCPU_CH_SUCCESS MK_U32(0) + +/** Channel setup failed: no matching IVC service found. */ #define RTCPU_CH_ERR_NO_SERVICE MK_U32(128) + +/** Channel setup failed: IVC service is already configured. */ #define RTCPU_CH_ERR_ALREADY MK_U32(129) + +/** Channel setup failed: Unknown command tag. */ #define RTCPU_CH_ERR_UNKNOWN_TAG MK_U32(130) + +/** Channel setup failed: Invalid IOVA address. */ #define RTCPU_CH_ERR_INVALID_IOVA MK_U32(131) + +/** Channel setup failed: Invalid parameter. */ #define RTCPU_CH_ERR_INVALID_PARAM MK_U32(132) /* @} */ diff --git a/include/soc/tegra/camrtc-commands.h b/include/soc/tegra/camrtc-commands.h index d80d7711..7d7d4dfb 100644 --- a/include/soc/tegra/camrtc-commands.h +++ b/include/soc/tegra/camrtc-commands.h @@ -4,10 +4,7 @@ */ /** - * @file camrtc-commands.h - * - * @brief Commands used with "nvidia,tegra-camrtc-hsp-vm" & "nvidia,tegra-hsp-mailbox" - * protocol + * @file camrtc-commands.h Commands for the HSP-VM and legacy HSP protocols. */ #ifndef INCLUDE_CAMRTC_COMMANDS_H @@ -16,24 +13,532 @@ #include "camrtc-common.h" /** - * @defgroup HspVmMsgs Definitions for "nvidia,tegra-camrtc-hsp-vm" protocol - * @{ + * @brief Create HSP-VM message. + * + * Combine a 7-bit command ID with a 24-bit parameter in order to + * form a 32-bit HSP-VM message. + * + * @pre None. + * + * @param _id Command ID [1,0x7F]. See @ref HspVmCmds + * "HSP-VM commands" for valid values. + * @param _param Command-specific parameter value [0, 0xFFFFFF]. + * See @ref @HspVmCmds "HSP-VM commands" for + * parameter definitions. + * @return 32-bit HSP mailbox message (uint32_t) + */ +#define CAMRTC_HSP_MSG(_id, _param) \ + (((uint32_t)(_id) << MK_U32(24)) | ((uint32_t)(_param) & MK_U32(0xffffff))) + +/** + * @brief Decode command ID from HSP-VM message. + * + * Decode a 7-bit command ID from a 32-bit HSP-VM message. + * + * @pre None. + * + * @param _msg 32-bit HSP mailbox message (uint32_t). + * @return Command ID [0,0x7F]. See @ref HspVmCmds + * "HSP-VM commands" for valid values. */ -#define CAMRTC_HSP_MSG(_id, _param) ( \ - ((uint32_t)(_id) << MK_U32(24)) | \ - ((uint32_t)(_param) & MK_U32(0xffffff))) #define CAMRTC_HSP_MSG_ID(_msg) \ (((_msg) >> MK_U32(24)) & MK_U32(0x7f)) -#define CAMRTC_HSP_MSG_PARAM(_msg) \ + +/** + * @brief Decode parameter value from HSP-VM message. + * + * Decode a 24-bit parameter value from a 32-bit HSP-VM message. + * + * @param _msg 32-bit HSP mailbox message (uint32_t). + * @return Command-specific parameter value [0, 0xFFFFFF]. + * See @ref @HspVmCmds "HSP-VM commands" for + * parameter definitions. + */ +#define CAMRTC_HSP_MSG_PARAM(_msg) \ ((uint32_t)(_msg) & MK_U32(0xffffff)) /** - * The IRQ message is sent when no other HSP-VM protocol message is being sent - * (i.e. the messages for higher level protocols implementing HSP such as IVC - * channel protocol) and the sender has updated its shared semaphore bits. + * @defgroup HspVmCmds HSP-VM commands + * + * The HSP-VM protocol is a synchronous request-reply protocol (except for + * one notable @ref CAMRTC_HSP_IRQ "exception"), where the CCPLEX VM client + * first writes a command word into a HSP shared mailbox and then waits for + * RCE FW to respond over the same mailbox. The responses are formatted + * with the same command ID as the associated requests, but the parameter + * values in each direction may differ. + * + * The protocol observes a state machine with state transitions triggered + * by message interactions. The protocol is described in more detail in + * the unit design documentation. + * + * The 32-bit HSP messages have the following format: + * + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 31 | Valid bit (managed by HSP driver) | + * | | 0 = mailbox is empty | + * | | 1 = mailbox is populated with a message | + * +-------+---------------------------------------------------+ + * | 30:24 | Command ID | + * +-------+---------------------------------------------------+ + * | 23:0 | Command parameter | + * +-------+---------------------------------------------------+ + * @endrst + * + * The command ID and parameter values are described below. + * @{ + */ + +/** + * This is a @ref HspVmCmds "HSP-VM command" that signals the peer that + * some action is needed, for example, that new IVC messages are available + * in the receive queue of the peer. Unlike the other HSP-VM messages, + * the CAMRTC_HSP_IRQ message can be sent by either by the client + * (e.g. VM on CCPLEX) or RCE itself. The message is asynchronous and + * is never directly acknowledged by the peer. + * + * @note Each peer is required to check its IVC receive queue whenever + * any HSP message is received, not just when a CAMRTC_HSP_IRQ is received. + * Therefore, the CAMRTC_HSP_IRQ message need not be sent if another message + * for the peer is already pending in the HSP shared mailbox. For the + * same reason, it is permitted to overwrite an outgoing CAMRTC_HSP_IRQ + * message populated in a HSP mailbox with another outgoing HSP message. + * + * The HSP-VM protocol defines an optional mechanism to optimize the + * IVC wakeups. Each IVC channel is associated with one or more + * @ref camrtc_tlv_ivc_setup::channel_group "channel wakeup groups". + * The sender may use an associated HSP @ref HspSsReg "shared semaphore" + * to set @ref CAMRTC_HSP_SS_IVC_MASK "IVC group bits" to indicate that + * the receiver needs to inspect the IVC channels belonging to those + * groups for incoming messages. + * + * RCE FW uses bits [7:0] (@ref CAMRTC_HSP_SS_IVC_MASK "IVC group bits" + * << @ref CAMRTC_HSP_SS_FW_SHIFT) of the @ref HspSsReg + * "shared semaphore register" to signal outgoing messages to CCPLEX VM. + * + * CCPLEX VM uses bits [23:16] (@ref CAMRTC_HSP_SS_IVC_MASK + * "IVC group bits" << @ref CAMRTC_HSP_SS_VM_SHIFT) of the @ref HspSsReg + * "shared semaphore register" to signal outgoing messages to RCE FW. + * + * If no IVC group bits are set (sender likely does not support the + * optimization) or the receiver itself does not support the + * optimization, it must always check all IVC channels for incoming + * messages after receiving a HSP message. + * + * Other bits in the 32-bit @ref HspSsReg "shared semaphore register" + * are reserved for additional signalling between CCPLEX VM and RCE. + * These bits are currently unused. + * + * @pre IVC channels have been set up with @ref CAMRTC_HSP_CH_SETUP and + * RCE has been placed into active state with @ref CAMRTC_HSP_RESUME. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_IRQ | + * +-------+---------------------------------------------------+ + * | 23:0 | 0x000000 | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * None */ #define CAMRTC_HSP_IRQ MK_U32(0x00) +/** + * @brief HELLO message + * + * The CAMRTC_HSP_HELLO message is sent by the client in the beginning of + * a HSP-VM session. RCE FW will respond with a CAMRTC_HSP_HELLO of its + * own. + * + * The HELLO message exchange ensures there are no unprocessed messages + * in transit within VM or RCE FW. The parameter field contains a + * randomly chosen cookie value that will identify the new session. + * RCE FW stores the cookie value and responds in acknowledgement. + * + * If RCE FW already has an active HSP-VM session for the HSP mailbox, + * with a different cookie value, RCE FW will reset its HSP-VM machine + * for the client before responding. This mechanism allows RCE FW to + * detect unexpected client restarts. + * + * @pre None. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_HELLO | + * +-------+---------------------------------------------------+ + * | 23:0 | Cookie [0x1,0xFFFFFF] | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_HELLO | + * +-------+---------------------------------------------------+ + * | 23:0 | Cookie, value copied from request message | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_HELLO MK_U32(0x40) + +/** + * @brief BYE message + * + * VM session close in indicated using BYE message, + * RCE FW reclaims the resources assigned to given VM. + * It must be sent before the Camera VM shuts down self. + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_BYE | + * +-------+---------------------------------------------------+ + * | 23:0 | Undefined | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_BYE | + * +-------+---------------------------------------------------+ + * | 23:0 | 0x000000 | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_BYE MK_U32(0x41) + +/** + * @brief RESUME message + * + * The CAMRTC_HSP_RESUME message is sent when VM wants to activate + * the RCE FW and access the camera hardware through it. The + * RESUME message is required after CAMRTC_HSP_HELLO, as the + * state machine will always be in inactive state at first. + * + * The Cookie value given as parameter must match the stored + * cookie value for the active HSP-VM session, otherwise + * RCE FW will ignore the command respond with RTCPU_RESUME_ERROR. + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_RESUME | + * +-------+---------------------------------------------------+ + * | 23:0 | Cookie | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_RESUME | + * +-------+---------------------------------------------------+ + * | 23:0 | 0x000000 or RTCPU_RESUME_ERROR (0xFFFFFF) | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_RESUME MK_U32(0x42) + +/** + * @brief SUSPEND message + * + * The CAMRTC_HSP_SUSPEND message is sent when VM wants to deactivate + * the RCE FW and let it power off the camera hardware if there are + * no other users. The SUSPEND message is normally sent when entering + * runtime suspend state (Linux). RCE FW can be brought back into + * active state by sending the @ref CAMRTC_HSP_RESUME "RESUME" + * message. + * + * @note RCE FW can support multiple HSP-VM clients. Every one of them + * must be in inactve state, before camera hardware is powered off. + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_SUSPEND | + * +-------+---------------------------------------------------+ + * | 23:0 | Undefined | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_SUSPEND | + * +-------+---------------------------------------------------+ + * | 23:0 | 0x000000 | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_SUSPEND MK_U32(0x43) + +/** + * Used to set up a shared memory area (such as IVC channels, trace buffer etc) + * between Camera VM and RCE FW. + */ +/** + * @brief CH_SETUP message + * + * The CAMRTC_CH_SETUP message is sent when VM wants to + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * @ref CAMRTC_HSP_PROTOCOL exchange is recommended to + * have been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_CH_SETUP | + * +-------+---------------------------------------------------+ + * | 23:0 | Bits [31:8] of IOVA pointing to channel setup | + * | | structures in shared memory. See 1) | + * +-------+---------------------------------------------------+ + * @endrst + * + * 1) A 32-bit IOVA pointing to one or more @ref camrtc_tlv + * structures in shared memory, containing detailed channel + * setup information. + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_CH_SETUP | + * +-------+---------------------------------------------------+ + * | 23:0 | Channel setup error code. See 2) | + * +-------+---------------------------------------------------+ + * @endrst + * + * 2) @ref CamRTCChannelErrors "Channel setup errors". + */ +#define CAMRTC_HSP_CH_SETUP MK_U32(0x44) + +/** + * @brief PING message + * + * The CAMRTC_HSP_PING message provides a simple connectivity + * test to see if RCE FW is responding. The client can send + * any value in the parameter field and RCE FW will echo it + * back. + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_PING | + * +-------+---------------------------------------------------+ + * | 23:0 | Ping payload [0x0, 0xFFFFFF ] | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_SUSPEND | + * +-------+---------------------------------------------------+ + * | 23:0 | Ping payload, copied from request | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_PING MK_U32(0x45) +/** + * SHA1 hash code for RCE FW binary. + */ + +/** + * @brief FW_HASH message + * + * The CAMRTC_FW_HASH message can be used to query the RCE FW + * firmware hash (SHA1) value from RCE FW. Retrieving the full + * hash value requires multiple queries, one for each byte. + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_FW_HASH | + * +-------+---------------------------------------------------+ + * | 23:0 | Hash byte index [0, 19] | + * +-------+---------------------------------------------------+ + * @endrst + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_FW_HASH | + * +-------+---------------------------------------------------+ + * | 23:0 | Hash byte [0,0xFF] or | + * | | RTCPU_FW_HASH_ERROR (0xFFFFFF) | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_FW_HASH MK_U32(0x46) + +/** + * The VM includes its protocol version as a parameter to PROTOCOL message. + * FW responds with its protocol version, or RTCPU_FW_INVALID_VERSION + * if the VM protocol is not supported. + */ +/** + * @brief PROTOCOL message + * + * The CAMRTC_HSP_PROTOCOL message is used to exchange HSP-VM + * protocol versions between client and RCE FW. While the message + * is optional, it is recommended to use it after the HELLOW + * exchange in order to enable all supported protocol features. + * + * @pre @ref CAMRTC_HSP_HELLO exchange has been completed. + * + * @par Request + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_PROTOCOL | + * +-------+---------------------------------------------------+ + * | 23:0 | HSP-VM host version. See 1) | + * +-------+---------------------------------------------------+ + * @endrst + * + * + * 1) @ref HspHostVersions "Host HSP protocol version" + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_PROTOCOL | + * +-------+---------------------------------------------------+ + * | 23:0 | HSP-VM FW version. See 2) | + * +-------+---------------------------------------------------+ + * @endrst + * + * 2) @ref HspFwVersions "Firmware HSP protocol version" + */ +#define CAMRTC_HSP_PROTOCOL MK_U32(0x47) + +/** Reserved, not to be used. */ +#define CAMRTC_HSP_RESERVED_5E MK_U32(0x5E) /* bug 200395605 */ + +/** + * @brief UNKNOWN HSP command response. + * + * The CAMRTC_HSP_UNKNOWN message is used for responding with + * an error to a client that has sent an unsupported HSP command. + * + * @pre An unsupported HSP command has been sent to RCE FW. + * + * @par Response + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 30:24 | CAMRTC_HSP_UNKNOWN | + * +-------+---------------------------------------------------+ + * | 23:0 | Unsupported HSP command ID | + * +-------+---------------------------------------------------+ + * @endrst + */ +#define CAMRTC_HSP_UNKNOWN MK_U32(0x7F) +/** @} */ + +/** + * @defgroup HspSsReg HSP shared semaphore register. + * + * A HSP shared semaphore register may be associated with the HSP + * shared mailbox to provide additional signaling capabilities + * between VM and RCE FW. The 32-bit shared semaphore contains + * 32 bits which may set or cleared individually without affecting + * other bits in the semaphore register. The semaphore bits can + * be used to signal different conditions to the peer. Half of + * the bits are assigned to RCE FW and the other half to CCPLEX VM. + * The assignment are described in the following table. + * + * @rststar + * +-------+---------------------------------------------------+ + * | Bits | Description | + * +=======+===================================================+ + * | 31 | Reserved, not to be used. (Bug 200395605) | + * +-------+---------------------------------------------------+ + * | 30:24 | Reserved bits for CCPLEX VM. | + * +-------+---------------------------------------------------+ + * | 23:16 | IVC group bits for CCPLEX VM. | + * +-------+---------------------------------------------------+ + * | 15:8 | Reserved bits for RCE FW. | + * +-------+---------------------------------------------------+ + * | 7:0 | IVC group bits for RCE FW. | + * +-------+---------------------------------------------------+ + * @endrst + * + * @{ + */ +/** Mask for shared semaphore bits (FW->VM) */ +#define CAMRTC_HSP_SS_FW_MASK MK_U32(0xFFFF) + +/** Shift value for shared semaphore bits (FW->VM) */ +#define CAMRTC_HSP_SS_FW_SHIFT MK_U32(0) + +/** Mask for shared semaphore bits (VM->FW) */ +#define CAMRTC_HSP_SS_VM_MASK MK_U32(0x7FFF0000) + +/** Shift value for shared semaphore bits (VM->FW) */ +#define CAMRTC_HSP_SS_VM_SHIFT MK_U32(16) + +/** Shared semaphore bits used to identify IVC channel groups */ +#define CAMRTC_HSP_SS_IVC_MASK MK_U32(0xFF) +/** @} */ + +/** + * @defgroup HspVmI2cCmds I2C commands for the HSP-VM protocol. + * Currently not implemented. + * @{ + */ + /** * Configure I2C controller. This will activate the given * I2C controller and configure the base address of a shared memory @@ -62,61 +567,6 @@ * param[11:0] = send byte count */ #define CAMRTC_HSP_I2C_XFER MK_U32(0x12) - -/** - * The HELLO messages are exchanged at the beginning of VM and RCE FW session. - * The HELLO message exchange ensures there are no unprocessed messages - * in transit within VM or RCE FW. - */ -#define CAMRTC_HSP_HELLO MK_U32(0x40) -/** - * VM session close in indicated using BYE message, - * RCE FW reclaims the resources assigned to given VM. - * It must be sent before the Camera VM shuts down self. - */ -#define CAMRTC_HSP_BYE MK_U32(0x41) -/** - * The RESUME message is sent when VM wants to activate the RCE FW - * and access the camera hardware through it. - */ -#define CAMRTC_HSP_RESUME MK_U32(0x42) -/** - * Power off camera HW, switch to idle state. VM initiates it during runtime suspend or SC7. - */ -#define CAMRTC_HSP_SUSPEND MK_U32(0x43) -/** - * Used to set up a shared memory area (such as IVC channels, trace buffer etc) - * between Camera VM and RCE FW. - */ -#define CAMRTC_HSP_CH_SETUP MK_U32(0x44) -/** - * The Camera VM can use the PING message to check aliveness of RCE FW and the HSP protocol. - */ -#define CAMRTC_HSP_PING MK_U32(0x45) -/** - * SHA1 hash code for RCE FW binary. - */ -#define CAMRTC_HSP_FW_HASH MK_U32(0x46) -/** - * The VM includes its protocol version as a parameter to PROTOCOL message. - * FW responds with its protocol version, or RTCPU_FW_INVALID_VERSION - * if the VM protocol is not supported. - */ -#define CAMRTC_HSP_PROTOCOL MK_U32(0x47) -#define CAMRTC_HSP_RESERVED_5E MK_U32(0x5E) /* bug 200395605 */ -#define CAMRTC_HSP_UNKNOWN MK_U32(0x7F) - -/** Shared semaphore bits (FW->VM) */ -#define CAMRTC_HSP_SS_FW_MASK MK_U32(0xFFFF) -#define CAMRTC_HSP_SS_FW_SHIFT MK_U32(0) - -/** Shared semaphore bits (VM->FW) */ -#define CAMRTC_HSP_SS_VM_MASK MK_U32(0x7FFF0000) -#define CAMRTC_HSP_SS_VM_SHIFT MK_U32(16) - -/** Bits used by IVC channels */ -#define CAMRTC_HSP_SS_IVC_MASK MK_U32(0xFF) - /** @} */ /** @@ -186,43 +636,73 @@ #define RTCPU_CMD_RESERVED_7D MK_U32(0x7d) #define RTCPU_CMD_RESERVED_7E MK_U32(0x7e) #define RTCPU_CMD_ERROR MK_U32(0x7f) +/** @} */ +/** + * @defgroup HspFwVersions Firmare HSP protocol firmware + * @{ + */ +/** @deprecated Historical firmware version. */ #define RTCPU_FW_DB_VERSION MK_U32(0) + +/** @deprecated Historical firmware version. */ #define RTCPU_FW_VERSION MK_U32(1) + +/** @deprecated Historical firmware version. */ #define RTCPU_FW_SM2_VERSION MK_U32(2) + +/** @deprecated Historical firmware version. */ #define RTCPU_FW_SM3_VERSION MK_U32(3) -/** SM4 firmware can restore itself after suspend */ + +/** Legacy HSP version: firmware can restore itself after suspend. */ #define RTCPU_FW_SM4_VERSION MK_U32(4) -/** SM5 firmware supports IVC synchronization */ +/** Legacy HSP version: firmware supports IVC synchronization (IVC reset). */ #define RTCPU_FW_SM5_VERSION MK_U32(5) -/** SM5 driver supports IVC synchronization */ -#define RTCPU_DRIVER_SM5_VERSION MK_U32(5) -/** SM6 firmware/driver supports camrtc-hsp-vm protocol */ +/** SM6 firmware supports HSP-VM protocol. */ #define RTCPU_FW_SM6_VERSION MK_U32(6) -#define RTCPU_DRIVER_SM6_VERSION MK_U32(6) +/** Current firmware version. */ +#define RTCPU_FW_CURRENT_VERSION RTCPU_FW_SM6_VERSION + +/** Invalid firmware version. */ +#define RTCPU_FW_INVALID_VERSION MK_U32(0xFFFFFF) +/** @} */ + +/** + * @defgroup HspHostVersions Host HSP protocol versions + * @{ + */ +/** @deprecated Historical driver version. */ #define RTCPU_IVC_SANS_TRACE MK_U32(1) + +/** @deprecated Historical driver version. */ #define RTCPU_IVC_WITH_TRACE MK_U32(2) +/** SM5 driver supports IVC synchronization (IVC reset). */ +#define RTCPU_DRIVER_SM5_VERSION MK_U32(5) + +/** SM6 driver supports HSP-VM protocol. */ +#define RTCPU_DRIVER_SM6_VERSION MK_U32(6) +/** @} */ + +/** Size if firmware hash value in bytes */ #define RTCPU_FW_HASH_SIZE MK_U32(20) +/** Firmware hash error (invalid hash index) */ #define RTCPU_FW_HASH_ERROR MK_U32(0xFFFFFF) #define RTCPU_PM_SUSPEND_SUCCESS MK_U32(0x100) #define RTCPU_PM_SUSPEND_FAILURE MK_U32(0x001) -#define RTCPU_FW_CURRENT_VERSION RTCPU_FW_SM6_VERSION - -#define RTCPU_FW_INVALID_VERSION MK_U32(0xFFFFFF) - +/** Resume to active state failed (session cookie mismatch). */ #define RTCPU_RESUME_ERROR MK_U32(0xFFFFFF) /** @} */ /** - * @defgroup I2C HSP protocol responses + * @defgroup I2cErrors I2C HSP protocol responses * @{ */ #define RTCPU_I2C_DONE MK_U32(1)