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 <mliljeberg@nvidia.com>
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 <mryttylainen@nvidia.com>
Reviewed-by: Frank Chen <frankc@nvidia.com>
GVS: Gerrit_Virtual_Submit <buildbot_gerritrpt@nvidia.com>

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
+ * Combine 8 character values into a 64-bit tag value.
- * file supports only uintX_t types, where X can be 8,16,32,64.
+ *
- * @{
+ * @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')
+ * @defgroup RceTags Command tags for shared memory setup
-#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')
+ */
-/** }@ */
 
 /**
- * @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)
 /* @} */
 

include/soc/tegra/camrtc-commands.h

@@ -4,10 +4,7 @@
  */
 
 /**
- * @file camrtc-commands.h
+ * @file camrtc-commands.h Commands for the HSP-VM and legacy HSP protocols.
- *
- * @brief Commands used with "nvidia,tegra-camrtc-hsp-vm" & "nvidia,tegra-hsp-mailbox"
- * protocol
  */
 
 #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))
+
+/**
+ * @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
+ * @defgroup HspVmCmds HSP-VM commands
- * (i.e. the messages for higher level protocols implementing HSP such as IVC
+ *
- * channel protocol) and the sender has updated its shared semaphore bits.
+ * 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
+/** Resume to active state failed (session cookie mismatch). */
-
-#define RTCPU_FW_INVALID_VERSION	MK_U32(0xFFFFFF)
-
 #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)