firmware-api: capture control MSG documentation

Update documentation for capture channel control messages and
associated structures and definitions.

Jira CAMERASW-14048

Change-Id: I525eca545eef64eb8fceac14480348b2dd173d1c
Signed-off-by: Mika Liljeberg <mliljeberg@nvidia.com>
Reviewed-on: https://git-master.nvidia.com/r/c/tegra/camera/firmware-api/+/2980882
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nv-oot/+/2988969
Reviewed-on: https://git-master.nvidia.com/r/c/linux-nv-oot/+/2994201
GVS: Gerrit_Virtual_Submit <buildbot_gerritrpt@nvidia.com>
Reviewed-by: Matti Ryttylainen <mryttylainen@nvidia.com>
Reviewed-by: Viktor Horsmanheimo <viktorh@nvidia.com>

include/soc/tegra/camrtc-capture-messages.h

@@ -1,6 +1,6 @@
 /* SPDX-License-Identifier: GPL-2.0-only */
 /*
- * Copyright (c) 2016-2022, NVIDIA Corporation.  All rights reserved.
+ * Copyright (c) 2016-2023, NVIDIA Corporation.  All rights reserved.
  */
 
 /**
@@ -25,28 +25,213 @@
  * the request message.
  */
 struct CAPTURE_MSG_HEADER {
-	/** Message identifier. */
+	/** Message identifier (See @ref CapCtrlMsgType). */
 	uint32_t msg_id;
 	/** @anon_union */
 	union {
-		/** Channel number. @anon_union_member */
+		/**
+		 * @anon_union_member
+		 * Capture channel ID [0, UINT32_MAX]. Used when the message
+		 * is related to a specific capture channel. The channel ID
+		 * must be a valid ID previously assigned by RCE FW.
+		 */
 		uint32_t channel_id;
-		/** Transaction id. @anon_union_member */
+		/**
+		 * @anon_union_member
+		 * Transaction id [0, UINT32_MAX]. Used when the message is not
+		 * related to a specific capture channel. The transaction ID in
+		 * a request message must be unique and may not collide with any
+		 * existing channel ID. The transaction in a response message
+		 * must match the transaction ID of the associated request.
+		 */
 		uint32_t transaction;
 	};
 } CAPTURE_IVC_ALIGN;
 
 /**
- * @defgroup ViCapCtrlMsgType Message types for capture-control IVC channel messages.
+ * @defgroup CapCtrlMsgType Message types for capture-control IVC channel messages
+ *
+ * The capture-control IVC channel is established during boot using the
+ * @ref CAMRTC_HSP_CH_SETUP command. The IVC channel is bi-directional
+ * and can be used to carry out control operations on RCE firmware. Each
+ * control operation consists of a request message and an associated
+ * response message.
+ *
+ * The overall message structure is defined by @ref CAPTURE_CONTROL_MSG
+ * and the structure is the same for both requests and responses. Each control
+ * message consists of a common @ref CAPTURE_MSG_HEADER followed by message
+ * specific data.
+ *
+ * The type of a message is identified by @ref CAPTURE_MSG_HEADER::msg_id.
+ *
+ * Requests and responses may be associated with a logical channel. All
+ * requests on the same logical channel must be strictly serialized, so
+ * that only a single request may be pending at any time. Requests and
+ * responses must specify the logical channel ID in the
+ * @ref CAPTURE_MSG_HEADER::channel_id. The channel ID is assigned by
+ * RCE FW when the logical channel is created.
+ *
+ * Requests and responses that are not associated with a specific logical
+ * channel must instead specify a transaction ID in
+ * @ref CAPTURE_MSG_HEADER::transaction. The transaction ID must be unique
+ * for each request and must not collide with any existing channel ID.
+ * A response message must use the same transaction ID as the associated
+ * request message. Examples of control messages that are not associated
+ * with an existing logical channel are messages that are used to
+ * establish a new logical channel. There are also other control operations
+ * that are not specific to a logical channel.
+ *
  * @{
  */
-#define CAPTURE_CONTROL_RESERVED_10		MK_U32(0x10)
+
+/**
+ * @defgroup ViCapCtrlMsgType Message types for VI capture channel control messages
+ *
+ * Capture channel control messages are used to set up, reset, and release
+ * channels for capturing images from an imaging stream source, as well as
+ * execute other control operations on the VI capture channel.
+ *
+ * See @ref CapCtrlMsgType for more information on the message protocol.
+ *
+ * @{
+ */
+
+/**
+ * @brief VI capture channel setup request.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" to
+ * allocate a VI capture channel and associated resources.
+ *
+ * @pre The capture-control IVC channel has been set up during
+ *      boot using the @ref CAMRTC_HSP_CH_SETUP command.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_SETUP_REQ
+ *   - @ref CAPTURE_MSG_HEADER::transaction "transaction" = <em>unique ID</em>
+ *
+ * @par Payload
+ * - @ref CAPTURE_CHANNEL_SETUP_REQ_MSG
+ *
+ * @par Response
+ * - @ref CAPTURE_CHANNEL_SETUP_RESP
+ */
 #define CAPTURE_CHANNEL_SETUP_REQ		MK_U32(0x1E)
+
+/**
+ * @brief VI capture channel setup response.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" sent as a
+ * response to a @ref CAPTURE_CHANNEL_SETUP_REQ message.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_SETUP_RESP
+ *   - @ref CAPTURE_MSG_HEADER::transaction "transaction" =
+ *     @ref CAPTURE_CHANNEL_SETUP_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::transaction "transaction"
+ *
+ * @par Payload
+ *  - @ref CAPTURE_CHANNEL_SETUP_RESP_MSG
+ */
 #define CAPTURE_CHANNEL_SETUP_RESP		MK_U32(0x11)
+
+/**
+ * @brief VI capture channel reset request.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" to
+ * reset a VI capture channel. The client must also send a @ref
+ * CAPTURE_RESET_BARRIER_IND message on the @em capture IVC channel
+ * in order to define a boundary between capture requests submitted
+ * before the reset and requests submitted after it.
+ *
+ * When RCE FW receives the @ref CAPTURE_CHANNEL_RESET_REQ message, it
+ * will cancel all capture requests in the channel queue upto the @ref
+ * CAPTURE_RESET_BARRIER_IND message. The response is sent after the
+ * RCE side channel cleanup is complete. If the reset barrier is not
+ * received within 5 ms, all requests currently in the queue will be
+ * cleared and a @ref CAPTURE_ERROR_TIMEOUT error will be reported
+ * in the response message.
+ *
+ * @pre A VI capture channel has been set up with
+ *      @ref CAPTURE_CHANNEL_SETUP_REQ.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_RESET_REQ
+ *   - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" =
+ *     @ref CAPTURE_CHANNEL_SETUP_RESP_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id"
+ *
+ * @par Payload
+ * - @ref CAPTURE_CHANNEL_RESET_REQ_MSG
+ *
+ * @par Response
+ * - @ref CAPTURE_CHANNEL_RESET_RESP
+ */
 #define CAPTURE_CHANNEL_RESET_REQ		MK_U32(0x12)
+
+/**
+ * @brief VI capture channel reset response.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" sent as a
+ * response to a @ref CAPTURE_CHANNEL_RESET_REQ message.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_RESET_RESP
+ *   - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" =
+ *     @ref CAPTURE_CHANNEL_RESET_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id"
+ *
+ * @par Payload
+ * - @ref CAPTURE_CHANNEL_RESET_RESP_MSG
+ */
 #define CAPTURE_CHANNEL_RESET_RESP		MK_U32(0x13)
+
+/**
+ * @brief VI capture channel release request.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" to
+ * release a VI capture channel. Cancels all pending capture
+ * requests.
+ *
+ * @pre A VI capture channel has been set up with
+ *     @ref CAPTURE_CHANNEL_SETUP_REQ.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_RELEASE_REQ
+ *   - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" =
+ *     @ref CAPTURE_CHANNEL_SETUP_RESP_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id"
+ *
+ * @par Payload
+ * - @ref CAPTURE_CHANNEL_RELEASE_REQ_MSG
+ *
+ * @par Response
+ * - @ref CAPTURE_CHANNEL_RELEASE_RESP
+ */
 #define CAPTURE_CHANNEL_RELEASE_REQ		MK_U32(0x14)
+
+/**
+ * @brief VI capture channel release response.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" sent as a
+ * response to a @ref CAPTURE_CHANNEL_RELEASE_REQ message.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_RELEASE_RESP
+ *   - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" =
+ *     @ref CAPTURE_CHANNEL_RELEASE_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id"
+ *
+ * @par Payload
+ * - @ref CAPTURE_CHANNEL_RELEASE_RESP_MSG
+ */
 #define CAPTURE_CHANNEL_RELEASE_RESP		MK_U32(0x15)
+/** @} */
+
+/**
+ * @defgroup ViCapCtrlMsgTypeNonsafe Message types for VI capture channel control messages (non-safety)
+ * @{
+ */
 #define CAPTURE_COMPAND_CONFIG_REQ		MK_U32(0x16)
 #define CAPTURE_COMPAND_CONFIG_RESP		MK_U32(0x17)
 #define CAPTURE_PDAF_CONFIG_REQ			MK_U32(0x18)
@@ -89,6 +274,7 @@ struct CAPTURE_MSG_HEADER {
 #define CAPTURE_ISP_RESET_BARRIER_IND		MK_U32(0x08)
 #define CAPTURE_ISP_EX_STATUS_IND		MK_U32(0x09)
 /** @} */
+/** @} */
 
 /**
  * @brief Invalid message type. This can be used to respond to an invalid request.
@@ -106,47 +292,43 @@ typedef uint32_t capture_result;
  * @defgroup CapErrorCodes Unsigned 32-bit return values for the capture-control IVC messages.
  * @{
  */
+/** Request succeeded */
 #define CAPTURE_OK				MK_U32(0)
+/** Request failed: invalid parameter */
 #define CAPTURE_ERROR_INVALID_PARAMETER		MK_U32(1)
+/** Request failed: insufficient memory */
 #define CAPTURE_ERROR_NO_MEMORY			MK_U32(2)
+/** Request failed: service busy */
 #define CAPTURE_ERROR_BUSY			MK_U32(3)
+/** Request failed: not supported */
 #define CAPTURE_ERROR_NOT_SUPPORTED		MK_U32(4)
+/** Request failed: not initialized */
 #define CAPTURE_ERROR_NOT_INITIALIZED		MK_U32(5)
+/** Request failed: overflow */
 #define CAPTURE_ERROR_OVERFLOW			MK_U32(6)
+/** Request failed: no resource available */
 #define CAPTURE_ERROR_NO_RESOURCES		MK_U32(7)
+/** Request failed: timeout */
 #define CAPTURE_ERROR_TIMEOUT			MK_U32(8)
+/** Request failed: service in invalid state */
 #define CAPTURE_ERROR_INVALID_STATE		MK_U32(9)
 /** @} */
 
-/**
+/** Message data for @ref CAPTURE_CHANNEL_SETUP_REQ message */
- * @brief VI capture channel setup request message.
- *
- * Setup the VI Falcon channel context and initialize the
- * RCE capture channel context. The GOS tables are also configured.
- * The client shall use the transaction id field
- * in the standard message header to associate request and response.
- */
 struct CAPTURE_CHANNEL_SETUP_REQ_MSG {
 	/** Capture channel configuration. */
 	struct capture_channel_config	channel_config;
 } CAPTURE_IVC_ALIGN;
 
-/**
+/** Message data for @ref CAPTURE_CHANNEL_SETUP_RESP message */
- * @brief VI Capture channel setup response message.
- *
- * The transaction id field in the standard message header
- * will be copied from the associated request.
- *
- * The setup response message returns a channel_id, which
- * identifies this set of resources and is used to refer to the
- * allocated capture channel in subsequent messages.
- */
 struct CAPTURE_CHANNEL_SETUP_RESP_MSG {
-	/** Capture result return value. See @ref CapErrorCodes "Return values" */
+	/** Request result code. See @ref CapErrorCodes "result codes". */
 	capture_result result;
-	/** Capture channel identifier for the new channel. */
+	/** Capture channel identifier for the new channel [0, UINT32_MAX]. */
 	uint32_t channel_id;
-	/** Bitmask of allocated VI channel(s). LSB is VI channel 0. */
+	/** 1-hot encoded bitmask indicating the allocated VI hardware
+	 *  channel [0, 0xFFFFFFFFF ]. LSB is VI channel 0.
+	 */
 	uint64_t vi_channel_mask;
 } CAPTURE_IVC_ALIGN;
 
@@ -154,58 +336,38 @@ struct CAPTURE_CHANNEL_SETUP_RESP_MSG {
  * @defgroup CapResetFlags VI Capture channel reset flags
  * @{
  */
-/** Reset the channel without waiting for FE first. */
+/** Reset the channel without waiting for frame-end first. */
 #define CAPTURE_CHANNEL_RESET_FLAG_IMMEDIATE	MK_U32(0x01)
 /** @} */
 
-/**
+/** Message data for @ref CAPTURE_CHANNEL_RESET_REQ message */
- * @brief Reset a VI capture channel.
- *
- * Halt the associated VI channel. Flush the request queue for the
- * channel and increment syncpoints in the request queue to their target
- * values.
- */
 struct CAPTURE_CHANNEL_RESET_REQ_MSG {
-	/** See @ref CapResetFlags "Reset flags" */
+	/** See @ref CapResetFlags "reset flags". */
 	uint32_t reset_flags;
 	/** Reserved */
 	uint32_t pad__;
 } CAPTURE_IVC_ALIGN;
 
-/**
+/** Message data for @ref CAPTURE_CHANNEL_RESET_RESP message */
- * @brief VI capture channel reset response message.
- *
- * The response is sent after the RCE side channel cleanup is
- * complete. If the reset barrier is not received within the timeout
- * interval a CAPTURE_ERROR_TIMEOUT error is reported as the return value.
- * If the reset succeeds then the return value is CAPTURE_OK.
- */
 struct CAPTURE_CHANNEL_RESET_RESP_MSG {
-	/** Reset status return value. See @ref CapErrorCodes "Return values" */
+	/** Request result code. See @ref CapErrorCodes "result codes". */
 	capture_result result;
 	uint32_t pad__;
 } CAPTURE_IVC_ALIGN;
 
-/**
+/** Message data for @ref CAPTURE_CHANNEL_RELEASE_REQ message */
- * @brief Release a VI capture channel and all the associated resources.
- *
- * Halt the associated VI channel and release the channel context.
- */
 struct CAPTURE_CHANNEL_RELEASE_REQ_MSG {
-	/** Reset flags. Currently not used in release request. */
+	/** Unused */
 	uint32_t reset_flags;
+	/** Reserved */
 	uint32_t pad__;
 } CAPTURE_IVC_ALIGN;
 
-/**
+/** Message data for @ref CAPTURE_CHANNEL_RELEASE_RESP message */
- * @brief Capture channel release response message.
- *
- * The release is acknowledged after the channel cleanup is complete
- * and all resources have been freed on RCE.
- */
 struct CAPTURE_CHANNEL_RELEASE_RESP_MSG {
-	/** Release status return value. See @ref CapErrorCodes "Return values" */
+	/** Request result code. See @ref CapErrorCodes "result codes". */
 	capture_result result;
+	/** Reserved */
 	uint32_t pad__;
 } CAPTURE_IVC_ALIGN;
 
@@ -531,7 +693,7 @@ struct CAPTURE_CSI_STREAM_TPG_START_RATE_RESP_MSG {
 } CAPTURE_IVC_ALIGN;
 
 /**
- * @defgroup gain ratio settings that can be set to frame generated by NVCSI TPG.
+ * @defgroup NvCsiTpgGain gain ratio settings that can be set to frame generated by NVCSI TPG.
  * @{
  */
 #define CAPTURE_CSI_STREAM_TPG_GAIN_RATIO_EIGHT_TO_ONE		MK_U8(0) /* 8:1 gain */
@@ -541,6 +703,7 @@ struct CAPTURE_CSI_STREAM_TPG_START_RATE_RESP_MSG {
 #define CAPTURE_CSI_STREAM_TPG_GAIN_RATIO_HALF			MK_U8(4) /* 0.5:1 gain */
 #define CAPTURE_CSI_STREAM_TPG_GAIN_RATIO_ONE_FOURTH		MK_U8(5) /* 0.25:1 gain */
 #define CAPTURE_CSI_STREAM_TPG_GAIN_RATIO_ONE_EIGHTH		MK_U8(6) /* 0.125:1 gain */
+/** @} */
 
 /**
  * @brief Apply gain ratio on specified VC of the desired CSI stream.
@@ -636,25 +799,42 @@ struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG {
 } CAPTURE_IVC_ALIGN;
 
 /**
- * @defgroup PhyStreamMsgType Message types for NvPhy
+ * @addtogroup CapCtrlMsgType
+ * @{
+ */
+
+/**
+ * @defgroup PhyStreamMsgType NVCSI PHY Control Message Types
  * @{
  */
 #define CAPTURE_PHY_STREAM_OPEN_REQ		MK_U32(0x36)
 #define CAPTURE_PHY_STREAM_OPEN_RESP		MK_U32(0x37)
 #define CAPTURE_PHY_STREAM_CLOSE_REQ		MK_U32(0x38)
 #define CAPTURE_PHY_STREAM_CLOSE_RESP		MK_U32(0x39)
+/** @} */
+
+/**
+ * @defgroup PhyStreamDebugMsgType NVCSI Phy Debug Message types (non-safety)
+ * @{
+ */
 #define CAPTURE_PHY_STREAM_DUMPREGS_REQ		MK_U32(0x3C)
 #define CAPTURE_PHY_STREAM_DUMPREGS_RESP	MK_U32(0x3D)
 /** @} */
 
 /**
- * @defgroup NvCsiMsgType Message types for NVCSI
+ * @defgroup NvCsiMsgType NVCSI Configuration Message Types
  * @{
  */
 #define CAPTURE_CSI_STREAM_SET_CONFIG_REQ	MK_U32(0x40)
 #define CAPTURE_CSI_STREAM_SET_CONFIG_RESP	MK_U32(0x41)
 #define CAPTURE_CSI_STREAM_SET_PARAM_REQ	MK_U32(0x42)
 #define CAPTURE_CSI_STREAM_SET_PARAM_RESP	MK_U32(0x43)
+/** @} */
+
+/**
+ * @defgroup NvCsiTpgMsgType NVCSI TPG Configuration Message Types
+ * @{
+ */
 #define CAPTURE_CSI_STREAM_TPG_SET_CONFIG_REQ	MK_U32(0x44)
 #define CAPTURE_CSI_STREAM_TPG_SET_CONFIG_RESP	MK_U32(0x45)
 #define CAPTURE_CSI_STREAM_TPG_START_REQ	MK_U32(0x46)
@@ -668,7 +848,7 @@ struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG {
 /** @} */
 
 /**
- * @addtogroup NvCsiMsgType Message types for NVCSI
+ * @defgroup ViEiCapCtrlMsgType VI Event Injection Message Types (non-safety)
  * @{
  */
 #define CAPTURE_CHANNEL_EI_REQ			MK_U32(0x50)
@@ -681,27 +861,58 @@ struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG {
  * @addtogroup ViCapCtrlMsgType
  * @{
  */
+/**
+ * @brief Override VI CHANSEL safety error masks.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" to
+ * override the default VI CHANSEL safety error masks on all
+ * active VI units.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ
+ *   - @ref CAPTURE_MSG_HEADER::transaction "transaction" = <em>unique ID</em>
+ *
+ * @par Payload
+ * - @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ_MSG
+ *
+ * @par Response
+ * - @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP
+ */
 #define CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ	MK_U32(0x54)
+
+/**
+ * @brief Override VI CHANSEL safety error masks response.
+ *
+ * This is a @ref CapCtrlMsgType "capture control message" sent as a
+ * response to a @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message.
+ *
+ * @par Header
+ * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header"
+ *   - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP
+ *   - @ref CAPTURE_MSG_HEADER::transaction "transaction" =
+ *     @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::transaction "transaction"
+ *
+ * @par Payload
+ * - @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP_MSG
+ */
 #define CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP	MK_U32(0x55)
 /** @} */
+/** @} */
 
 /**
  * @addtogroup ViCapCtrlMsgs
  * @{
  */
-/**
+/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message */
- * @brief Set CHANSEL error mask from HSM reporting message
- */
 struct CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ_MSG {
-	/** VI EC/HSM global CHANSEL error mask configuration */
+	/** VI CHANSEL safety error mask configuration */
 	struct vi_hsm_chansel_error_mask_config hsm_chansel_error_config;
 } CAPTURE_IVC_ALIGN;
 
-/**
+/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP message */
- * @brief Acknowledge CHANEL error mask request
- */
 struct CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP_MSG {
-	/** HSM CHANSEL error mask request result. See @ref CapErrorCodes "Return values". */
+	/** Request result. See @ref CapErrorCodes "result codes". */
 	capture_result result;
 	/** Reserved */
 	uint32_t pad__;
@@ -736,134 +947,237 @@ struct CAPTURE_CHANNEL_ISP_SETUP_RESP_MSG {
 	uint32_t channel_id;
 } CAPTURE_IVC_ALIGN;
 
-typedef struct CAPTURE_CHANNEL_RESET_REQ_MSG
+typedef struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG
 			CAPTURE_CHANNEL_ISP_RESET_REQ_MSG;
-typedef struct CAPTURE_CHANNEL_RESET_RESP_MSG
+typedef struct CAPTURE_CHANNEL_ISP_RESET_RESP_MSG
 			CAPTURE_CHANNEL_ISP_RESET_RESP_MSG;
-typedef struct CAPTURE_CHANNEL_RELEASE_REQ_MSG
+typedef struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG
 			CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG;
-typedef struct CAPTURE_CHANNEL_RELEASE_RESP_MSG
+typedef struct CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG
 			CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG;
 
+/**
+ * @brief Reset ISP channel request.
+ *
+ * Halt the associated ISP channel. Flush the request queue for the
+ * channel and increment syncpoints in the request queue to their target
+ * values.
+ */
+struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG {
+	/** Unused */
+	uint32_t reset_flags;
+	/** Reserved */
+	uint32_t pad__;
+} CAPTURE_IVC_ALIGN;
+
+/**
+ * @brief Reset ISP channel response message.
+ *
+ * The response is sent after the RCE side channel cleanup is
+ * complete. If the reset barrier is not received within the timeout
+ * interval a CAPTURE_ERROR_TIMEOUT error is reported as the return value.
+ * If the reset succeeds then the return value is CAPTURE_OK.
+ */
+struct CAPTURE_CHANNEL_ISP_RESET_RESP_MSG {
+	/** Reset status return value. See @ref CapErrorCodes "Return values" */
+	capture_result result;
+	uint32_t pad__;
+} CAPTURE_IVC_ALIGN;
+
+/**
+ * @brief Release ISP channel and all the associated resources.
+ *
+ * Halt the associated ISP channel and release the channel context.
+ */
+struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG {
+	/** Reset flags. Currently not used in release request. */
+	uint32_t reset_flags;
+	uint32_t pad__;
+} CAPTURE_IVC_ALIGN;
+
+/**
+ * @brief ISP channel release response message.
+ *
+ * The release is acknowledged after the channel cleanup is complete
+ * and all resources have been freed on RCE.
+ */
+struct CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG {
+	/** Release status return value. See @ref CapErrorCodes "Return values" */
+	capture_result result;
+	uint32_t pad__;
+} CAPTURE_IVC_ALIGN;
+
 /**
  * @brief Message frame for capture-control IVC channel.
+ *
+ * This structure describes a common message format for all capture channel
+ * IVC messages. The message format includes a message header that is common
+ * to all messages, followed by a message-specific message data.  The message
+ * data is represented as an anonymous union of message structures.
  */
 struct CAPTURE_CONTROL_MSG {
+	/** Common capture control channel message header */
 	struct CAPTURE_MSG_HEADER header;
 	/** @anon_union */
 	union {
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_SETUP_REQ message */
 		struct CAPTURE_CHANNEL_SETUP_REQ_MSG channel_setup_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_SETUP_RESP message */
 		struct CAPTURE_CHANNEL_SETUP_RESP_MSG channel_setup_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_RESET_REQ message */
 		struct CAPTURE_CHANNEL_RESET_REQ_MSG channel_reset_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_RESET_RESP message */
 		struct CAPTURE_CHANNEL_RESET_RESP_MSG channel_reset_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_RELEASE_REQ message */
 		struct CAPTURE_CHANNEL_RELEASE_REQ_MSG channel_release_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_RELEASE_RESP message */
 		struct CAPTURE_CHANNEL_RELEASE_RESP_MSG channel_release_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_COMPAND_CONFIG_REQ message (non-safety) */
 		struct CAPTURE_COMPAND_CONFIG_REQ_MSG compand_config_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_COMPAND_CONFIG_RESP message (non-safety) */
 		struct CAPTURE_COMPAND_CONFIG_RESP_MSG compand_config_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PDAF_CONFIG_REQ message (non-safety) */
 		struct CAPTURE_PDAF_CONFIG_REQ_MSG pdaf_config_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PDAF_CONFIG_RESP message (non-safety) */
 		struct CAPTURE_PDAF_CONFIG_RESP_MSG pdaf_config_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_SYNCGEN_ENABLE_REQ message (non-safety) */
 		struct CAPTURE_SYNCGEN_ENABLE_REQ_MSG syncgen_enable_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_SYNCGEN_ENABLE_RESP message (non-safety) */
 		struct CAPTURE_SYNCGEN_ENABLE_RESP_MSG syncgen_enable_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_SYNCGEN_DISABLE_REQ message (non-safety) */
 		struct CAPTURE_SYNCGEN_DISABLE_REQ_MSG syncgen_disable_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_SYNCGEN_DISABLE_RESP message (non-safety) */
 		struct CAPTURE_SYNCGEN_DISABLE_RESP_MSG syncgen_disable_resp;
 
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PHY_STREAM_OPEN_REQ message */
 		struct CAPTURE_PHY_STREAM_OPEN_REQ_MSG phy_stream_open_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PHY_STREAM_OPEN_RESP message */
 		struct CAPTURE_PHY_STREAM_OPEN_RESP_MSG phy_stream_open_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PHY_STREAM_CLOSE_REQ message */
 		struct CAPTURE_PHY_STREAM_CLOSE_REQ_MSG phy_stream_close_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PHY_STREAM_CLOSE_RESP message */
 		struct CAPTURE_PHY_STREAM_CLOSE_RESP_MSG phy_stream_close_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PHY_STREAM_DUMPREGS_REQ message (non-safety) */
 		struct CAPTURE_PHY_STREAM_DUMPREGS_REQ_MSG
 			phy_stream_dumpregs_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_PHY_STREAM_DUMPREGS_RESP message (non-safety) */
 		struct CAPTURE_PHY_STREAM_DUMPREGS_RESP_MSG
 			phy_stream_dumpregs_resp;
 
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_SET_CONFIG_REQ message */
 		struct CAPTURE_CSI_STREAM_SET_CONFIG_REQ_MSG
 			csi_stream_set_config_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_SET_CONFIG_RESP message */
 		struct CAPTURE_CSI_STREAM_SET_CONFIG_RESP_MSG
 			csi_stream_set_config_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_SET_PARAM_REQ message */
 		struct CAPTURE_CSI_STREAM_SET_PARAM_REQ_MSG
 			csi_stream_set_param_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_SET_PARAM_RESP message */
 		struct CAPTURE_CSI_STREAM_SET_PARAM_RESP_MSG
 			csi_stream_set_param_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_SET_CONFIG_REQ message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_SET_CONFIG_REQ_MSG
 			csi_stream_tpg_set_config_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_SET_CONFIG_RESP message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_SET_CONFIG_RESP_MSG
 			csi_stream_tpg_set_config_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_START_REQ message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_START_REQ_MSG
 			csi_stream_tpg_start_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_START_RESP message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_START_RESP_MSG
 			csi_stream_tpg_start_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_STOP_REQ message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_STOP_REQ_MSG
 			csi_stream_tpg_stop_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_STOP_RESP message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_STOP_RESP_MSG
 			csi_stream_tpg_stop_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_START_RATE_REQ message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_START_RATE_REQ_MSG
 			csi_stream_tpg_start_rate_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_START_RATE_RESP message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_START_RATE_RESP_MSG
 			csi_stream_tpg_start_rate_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_APPLY_GAIN_REQ message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_APPLY_GAIN_REQ_MSG
 			csi_stream_tpg_apply_gain_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CSI_STREAM_TPG_APPLY_GAIN_RESP message (non-safety) */
 		struct CAPTURE_CSI_STREAM_TPG_APPLY_GAIN_RESP_MSG
 			csi_stream_tpg_apply_gain_resp;
 
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_EI_REQ message (non-safety) */
 		struct CAPTURE_CHANNEL_EI_REQ_MSG ei_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_EI_RESP message (non-safety) */
 		struct CAPTURE_CHANNEL_EI_RESP_MSG ei_resp;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_EI_RESET_REQ message (non-safety) */
 		struct CAPTURE_CHANNEL_EI_RESET_REQ_MSG ei_reset_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_EI_RESET_RESP message (non-safety) */
 		struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG ei_reset_resp;
 
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_REQ message */
 		struct CAPTURE_CHANNEL_ISP_SETUP_REQ_MSG channel_isp_setup_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_RESP message */
 		struct CAPTURE_CHANNEL_ISP_SETUP_RESP_MSG channel_isp_setup_resp;
 		/** @anon_union_member */
-		CAPTURE_CHANNEL_ISP_RESET_REQ_MSG channel_isp_reset_req;
+		/** Message data for @ref CAPTURE_CHANNEL_ISP_RESET_REQ message */
+		struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG channel_isp_reset_req;
 		/** @anon_union_member */
-		CAPTURE_CHANNEL_ISP_RESET_RESP_MSG channel_isp_reset_resp;
+		/** Message data for @ref CAPTURE_CHANNEL_ISP_RESET_RESP message */
+		struct CAPTURE_CHANNEL_ISP_RESET_RESP_MSG channel_isp_reset_resp;
 		/** @anon_union_member */
-		CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG channel_isp_release_req;
+		/** Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ message */
+		struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG channel_isp_release_req;
 		/** @anon_union_member */
-		CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG channel_isp_release_resp;
+		/** Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP message */
+		struct CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG channel_isp_release_resp;
 
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message */
 		struct CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ_MSG hsm_chansel_mask_req;
 		/** @anon_union_member */
+		/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP message */
 		struct CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP_MSG hsm_chansel_mask_resp;
 	};
 } CAPTURE_IVC_ALIGN;

include/soc/tegra/camrtc-capture.h

@@ -17,7 +17,7 @@
 #pragma GCC diagnostic error "-Wpadded"
 
 #define CAPTURE_IVC_ALIGNOF		MK_ALIGN(8)
-#define CAPTURE_DESCRIPTOR_ALIGN_BYTES (64)
+#define CAPTURE_DESCRIPTOR_ALIGN_BYTES (64)	/**< Descriptor alignment in shared memory */
 #define CAPTURE_DESCRIPTOR_ALIGNOF	MK_ALIGN(CAPTURE_DESCRIPTOR_ALIGN_BYTES)
 
 #define CAPTURE_IVC_ALIGN		CAMRTC_ALIGN(CAPTURE_IVC_ALIGNOF)
@@ -37,17 +37,20 @@ typedef uint64_t iova_t CAPTURE_IVC_ALIGN;
 typedef struct syncpoint_info {
 	/** Syncpoint ID */
 	uint32_t id;
-	/** Syncpoint threshold when storing a fence */
+	/** Syncpoint threshold when storing a fence [0, UIN32_MAX] */
 	uint32_t threshold;
-	/** Grid of Semaphores (GOS) SMMU stream id */
+	/** Grid-of-Semaphores (GoS) SMMU stream id [1, 127] (non-safety) */
 	uint8_t gos_sid;
-	/** GOS index */
+	/**
+	 * Index into a table of GoS page base pointers (see @ref
+	 * capture_channel_config::vi_gos_tables) (non-safety)
+	 */
 	uint8_t gos_index;
-	/** GOS offset */
+	/** Offset of a semaphore within a Grid-of-Semaphores [0, 63] (non-safety) */
 	uint16_t gos_offset;
 	/** Reserved */
 	uint32_t pad_;
-	/** IOVA address of the Host1x syncpoint register */
+	/** IOVA address of the Host1x syncpoint register. Must be a multiple of 4. */
 	iova_t shim_addr;
 } syncpoint_info_t CAPTURE_IVC_ALIGN;
 
@@ -375,36 +378,38 @@ typedef struct syncpoint_info {
 #define CAPTURE_CHANNEL_FLAG_PLANAR		MK_U32(0x0004)
 /** Channel supports semi-planar YUV output */
 #define CAPTURE_CHANNEL_FLAG_SEMI_PLANAR	MK_U32(0x0008)
-/** Channel supports phase-detection auto-focus */
+/** Channel supports phase-detection auto-focus (non-safety) */
 #define CAPTURE_CHANNEL_FLAG_PDAF		MK_U32(0x0010)
 /** Channel outputs sensor embedded data */
 #define CAPTURE_CHANNEL_FLAG_EMBDATA		MK_U32(0x0040)
-/** Channel outputs to ISPA */
+/** Channel outputs to ISPA (deprecated, non-safety) */
 #define CAPTURE_CHANNEL_FLAG_ISPA		MK_U32(0x0080)
-/** Channel outputs to ISPB */
+/** Channel outputs to ISPB (deprecated, non-safety) */
 #define CAPTURE_CHANNEL_FLAG_ISPB		MK_U32(0x0100)
-/** Channel outputs directly to selected ISP (ISO mode) */
+/** Channel outputs directly to selected ISP (ISO mode) (deprecated, non-safety) */
 #define CAPTURE_CHANNEL_FLAG_ISP_DIRECT		MK_U32(0x0200)
 /** Channel outputs to software ISP (reserved) */
 #define CAPTURE_CHANNEL_FLAG_ISPSW		MK_U32(0x0400)
-/** Channel treats all errors as stop-on-error and requires reset for recovery.*/
+/** Channel treats all errors as stop-on-error and requires reset for recovery (non-safety)*/
 #define CAPTURE_CHANNEL_FLAG_RESET_ON_ERROR	MK_U32(0x0800)
 /** Channel has line timer enabled */
 #define CAPTURE_CHANNEL_FLAG_LINETIMER		MK_U32(0x1000)
-/** Channel supports SLVSEC sensors */
+/** Channel supports SLVSEC sensors (non-safety) */
 #define CAPTURE_CHANNEL_FLAG_SLVSEC		MK_U32(0x2000)
-/** Channel reports errors to HSM based on error_mask_correctable and error_mask_uncorrectable.*/
+/**
+ * Channel reports errors to System Error Handler based on
+ * @ref capture_channel_config::error_mask_correctable and
+ * @ref capture_channel_config::error_mask_uncorrectable.
+ */
 #define CAPTURE_CHANNEL_FLAG_ENABLE_HSM_ERROR_MASKS	MK_U32(0x4000)
-/** Capture with VI PFSD enabled */
+/** Capture with VI PFSD enabled (deprecated) */
 #define CAPTURE_CHANNEL_FLAG_ENABLE_VI_PFSD	MK_U32(0x8000)
 /** Channel binds to a CSI stream and channel */
 #define CAPTURE_CHANNEL_FLAG_CSI		MK_U32(0x10000)
-
+/**@}*/
-  /**@}*/
 
 /**
- * @defgroup CaptureChannelErrMask
+ * @defgroup CaptureChannelErrMask VI error numbers
- * Bitmask for masking "Uncorrected errors" and "Errors with threshold".
  */
 /**@{*/
 /** VI Frame start error timeout */
@@ -462,11 +467,14 @@ typedef struct syncpoint_info {
  * @brief Identifies a specific CSI stream.
  */
 struct csi_stream_config {
-	/** See @ref NvCsiStream "NVCSI stream id" */
+	/** See @ref NvCsiStream "NvCSI Stream ID" */
 	uint32_t stream_id;
-	/** See @ref NvCsiPort "NvCSI Port" */
+	/**
+	 * See @ref NvCsiPort "CSI Port". If the CSI port is specified,
+	 * the value must map correctly to the @ref stream_id value.
+	 */
 	uint32_t csi_port;
-	/** CSI Virtual Channel */
+	/** See @ref NvCsiVirtualChannel "CSI Virtual Channel". */
 	uint32_t virtual_channel;
 	/** Reserved */
 	uint32_t pad__;
@@ -480,10 +488,7 @@ struct capture_channel_config {
 	 * A bitmask describing the set of non-shareable
 	 * HW resources that the capture channel will need. These HW resources
 	 * will be assigned to the new capture channel and will be owned by the
-	 * channel until it is released with CAPTURE_CHANNEL_RELEASE_REQ.
+	 * channel until it is released with @ref CAPTURE_CHANNEL_RELEASE_REQ.
-	 *
-	 * The HW resources that can be assigned to a channel include a VI
-	 * channel, ISPBUF A/B interface (T18x only), Focus Metric Lite module (FML).
 	 *
 	 * VI channels can have different capabilities. The flags are checked
 	 * against the VI channel capabilities to make sure the allocated VI
@@ -496,131 +501,188 @@ struct capture_channel_config {
 	/** rtcpu internal data field - Should be set to zero */
 	uint32_t channel_id;
 
-	/** VI unit ID. See @ref ViUnitIds "VI Unit Identifiers". */
+	/** VI unit ID. See @ref ViUnitIds "VI Unit Identifiers" */
 	uint32_t vi_unit_id;
 
 	/** Reserved */
 	uint32_t pad__;
 
 	/**
-	 * A bitmask indicating which VI channels to consider for allocation. LSB is VI channel 0.
+	 * A bitmask indicating which VI hardware channels to consider for
-	 * This allows the client to enforce allocation of HW VI channel in particular range for its own
+	 * allocation [0, 0xFFFFFFFFF]. LSB is VI channel 0.
-	 * purpose.
 	 *
-	 * Beware that client VM may have restricted range of available VI channels.
+	 * Normal usage is to set all the bits, so as not to restrict the
+	 * channel allocation. Note that a client VM may also have additional
+	 * restrictions on the range of VI channels available to it.
 	 *
-	 * In most of the cases client can set to ~0ULL to let RTCPU to allocate any available channel
+	 * This control is provided for special use cases and for testing.
-	 * permitted for client VM.
-	 *
-	 * This mask is expected to be useful for following use-cases:
-	 * 1. Debugging functionality of particular HW VI channel.
-	 * 2. Verify that RTCPU enforces VI channel permissions defined in VM DT.
 	 */
 	uint64_t vi_channel_mask;
 
 	/**
-	 * A bitmask indicating which VI2 channels to consider for allocation. LSB is VI2 channel 0.
+	 * A bitmask indicating which VI2 hardware channels to consider for
-	 * This allows the client to enforce allocation of HW VI channel in particular range for its own
+	 * allocation [0, 0xFFFFFFFFF]. LSB is VI2 channel 0.
-	 * purpose.
 	 *
-	 * Beware that client VM may have restricted range of available VI2 channels.
+	 * Normal usage is to set all the bits, so as not to restrict the
+	 * channel allocation. Note that a client VM may also have additional
+	 * restrictions on the range of VI channels available to it.
 	 *
-	 * In most of the cases client can set to ~0ULL to let RTCPU to allocate any available channel
+	 * This control is provided for special use cases and for testing.
-	 * permitted for client VM.
-	 *
-	 * This mask is expected to be useful for following use-cases:
-	 * 1. Debugging functionality of particular HW VI2 channel.
-	 * 2. Verify that RTCPU enforces VI channel permissions defined in VM DT.
 	 */
 	uint64_t vi2_channel_mask;
 
 	/**
-	 * CSI stream configuration identifies the CSI stream input for this channel.
+	 * CSI stream configuration identifies the CSI stream input for
+	 * this channel.
 	 */
 	struct csi_stream_config csi_stream;
 
 	/**
-	 * Base address of a memory mapped ring buffer containing capture requests.
+	 * Base address of the @ref capture_descriptor ring buffer.
-	 * The size of the buffer is queue_depth * request_size
+	 * The size of the buffer is @ref queue_depth * @ref request_size.
+	 * The value must be non-zero and a multiple of
+	 * @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES.
 	 */
 	iova_t requests;
 
 	/**
-	 * Base address of a memory mapped ring buffer containing capture requests buffer
+	 * Base address of a memory mapped ring buffer containing capture
-	 * information.
+	 * requests buffer information. The size of the buffer is @ref
-	 * The size of the buffer is queue_depth * request_memoryinfo_size
+	 * queue_depth * @ref request_memoryinfo_size. The value must be
+	 * non-zero and a multiple of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES.
 	 */
 	iova_t requests_memoryinfo;
 
 	/**
-	 * Maximum number of capture requests in the requests queue.
+	 * Maximum number of capture requests in the requests queue [1, 240].
-	 * Determines the size of the ring buffer.
+	 * Determines the size of the @ref capture_descriptor ring buffer
+	 * (@ref requests).
 	 */
 	uint32_t queue_depth;
 
-	/** Size of the buffer reserved for each capture request. */
+	/**
+	 * Size of the buffer reserved for each capture descriptor. The size
+	 * must be >= sizeof(@ref capture_descriptor) and a multiple of
+	 * @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES.
+	 */
 	uint32_t request_size;
 
-	/** Size of the memoryinfo buffer reserved for each capture request. */
+	/**
+	 * Size of the memoryinfo buffer reserved for each capture request.
+	 * Must be >= sizeof(@ref capture_descriptor_memoryinfo) and
+	 * a multiple of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES.
+	 */
 	uint32_t request_memoryinfo_size;
 
 	/** Reserved */
 	uint32_t reserved2;
 
-	/** SLVS-EC main stream */
+	/** SLVS-EC main stream (non-safety) */
 	uint8_t slvsec_stream_main;
-	/** SLVS-EC sub stream */
+	/** SLVS-EC sub stream (non-safety) */
 	uint8_t slvsec_stream_sub;
 	/** Reserved */
 	uint16_t reserved1;
 
 #define HAVE_VI_GOS_TABLES
 	/**
-	 * GoS tables can only be programmed when there are no
+	 * Number of elements in @ref vi_gos_tables array
-	 * active channels. For subsequent channels we check that
+	 * [0, @ref VI_NUM_GOS_TABLES].
-	 * the channel configuration matches with the active
-	 * configuration.
-	 *
-	 * Number of Grid of Semaphores (GOS) tables
 	 */
 	uint32_t num_vi_gos_tables;
-	/** VI GOS tables */
-	iova_t vi_gos_tables[VI_NUM_GOS_TABLES];
-
-	/** Capture progress syncpoint info */
-	struct syncpoint_info progress_sp;
-	/** Embedded data syncpoint info */
-	struct syncpoint_info embdata_sp;
-	/** VI line timer syncpoint info */
-	struct syncpoint_info linetimer_sp;
-
 	/**
-	 * User-defined HSM error reporting policy is specified by error masks bits
+	 * Array of IOVA pointers to VI Grid-of-Semaphores (GoS) tables
+	 * (non-safety).
 	 *
-	 * CAPTURE_CHANNEL_FLAG_ENABLE_HSM_ERROR_MASKS must be set to enable these error masks,
+	 * GoS table configuration, if present, must be the same on all
-	 * otherwise default HSM reporting policy is used.
+	 * active channels. The IOVA addresses must be a multiple of 256.
-	 *
-	 * VI-falcon reports error to EC/HSM as uncorrected if error is not masked
-	 * in "Uncorrected" mask.
-	 * VI-falcon reports error to EC/HSM as corrected if error is masked
-	 * in "Uncorrected" mask and not masked in "Errors with threshold" mask.
-	 * VI-falcon does not report error to EC/HSM if error masked
-	 * in both "Uncorrected" and "Errors with threshold" masks.
 	 */
+	iova_t vi_gos_tables[VI_NUM_GOS_TABLES];
 	/**
-	 * Error mask for "uncorrected" errors. See @ref CaptureChannelErrMask "Channel Error bitmask".
+	 * Capture progress syncpoint information. The progress syncpoint
-	 * There map to the uncorrected error line in HSM
+	 * is incremented on Start-Of-Frame, whenever a slice of pixel
+	 * data has been written to memory, and finally when the status
+	 * of a capture has been written to memory. The same progress
+	 * syncpoint will keep incrementing for every consecutive capture
+	 * request.
+	 *
+	 * @ref syncpoint_info::threshold must be set to the initial
+	 * value of the hardware syncpoint on channel setup.
+	 **/
+	struct syncpoint_info progress_sp;
+	/**
+	 * Embedded data syncpoint information. The embedded data syncpoint
+	 * is incremented whenever the sensor embedded data for a captured
+	 * frame has been written to memory. The embedded data syncpoint
+	 * is optional and need not be specified if embedded data is not
+	 * being captured (see @ref vi_channel_config::embdata_enable).
+	 * The same embedded data syncpoint will keep incrementing for every
+	 * consecutive capture request.
+	 *
+	 * @ref syncpoint_info::threshold must be set to the initial
+	 * value of the hardware syncpoint on channel setup.
+	 **/
+	struct syncpoint_info embdata_sp;
+	/**
+	 * VI line timer syncpoint info. The line timer syncpoint is
+	 * incremented whenever the frame readout reaches a specified
+	 * line (see @ref vi_channel_config::line_timer,
+	 * @ref vi_channel_config::line_timer_first, and
+	 * @ref vi_channel_config::line_timer_periodic). The line timer
+	 * syncpoint is optional and need not be specified if line timer
+	 * is not enabled (see @ref vi_channel_config::line_timer_enable).
+	 * The same line timer syncpoint will keep incrementing for every
+	 * consecutive capture request.
+	 *
+	 * @ref syncpoint_info::threshold must be set to the initial
+	 * value of the hardware syncpoint on channel setup.
+	 **/
+	struct syncpoint_info linetimer_sp;
+	/**
+	 * Error mask for suppressing uncorrected safety errors (see @ref
+	 * CaptureChannelErrMask "VI error numbers"). If the mask is set to
+	 * zero, all VI errors will be reported as uncorrected safety errors.
+	 * If a specific error is masked by setting the corresponding bit
+	 * (1 << <em>error number</em>) in the error mask, the error will not
+	 * be reported as uncorrected. Note that the error may still be
+	 * reported as a corrected error unless it is also masked in
+	 * @ref error_mask_correctable.
+	 *
+	 * An uncorrected error will be interpreted by System Error Handler
+	 * as an indication that a camera is off-line and cannot continue
+	 * the capture.
+	 *
+	 * @ref CAPTURE_CHANNEL_FLAG_ENABLE_HSM_ERROR_MASKS must be set in
+	 * @ref channel_flags for this setting to take effect. Otherwise,
+	 * a default error mask will be used.
 	 */
 	uint32_t error_mask_uncorrectable;
 	/**
-	 * Error mask for "errors with threshold".
+	 * This error mask applies only to errors that are masked in @ref
-	 * See @ref CaptureChannelErrMask "Channel Error bitmask".
+	 * error_mask_uncorrectable. By default, all such errors are reported
-	 * These map to the corrected error line in HSM */
+	 * to System Error Handler as corrected. If a specific error is masked
+	 * in both this mask and in @ref error_mask_uncorrectable, by setting
+	 * the corresponding bit (1 << <em>error number</em>) in the error mask
+	 * (see @ref CaptureChannelErrMask "VI error numbers"), the error
+	 * will not be reported to System Error Handler at all.
+	 *
+	 * A corrected safety error will be interpreted by System Error Handler
+	 * as an indication that a single frame has been corrupted or dropped.
+	 *
+	 * @ref CAPTURE_CHANNEL_FLAG_ENABLE_HSM_ERROR_MASKS must be set in
+	 * @ref channel_flags for this setting to take effect. Otherwise,
+	 * a default error mask will be used.
+	 */
 	uint32_t error_mask_correctable;
-
 	/**
-	 * Capture will stop for errors selected in this bit masks.
+	 * When a capture error is detected, the capture channel will
-	 * Bit definitions are same as in CAPTURE_STATUS_NOTIFY_BIT_* macros.
+	 * enter an error state if the corresponding error bit
+	 * (1 << <em>error number</em>) is set in this bit mask
+	 * (see @ref ViNotifyErrorTag "Extended VI error numbers"
+	 * for the bit definitions).
+	 *
+	 * When the channel is in error state it will not accept any new
+	 * capture requests.
 	 */
 	uint64_t stop_on_error_notify_bits;
 
@@ -1066,8 +1128,7 @@ struct capture_status {
 	uint64_t notify_bits;
 
 	/**
-	 * @defgroup ViNotifyErrorTag
+	 * @defgroup ViNotifyErrorTag Extended VI error bits for the @ref notify_bits field
-	 * Error bit definitions for the @ref notify_bits field
 	 */
 	/** @{ */
 	/** Reserved */
@@ -1459,14 +1520,44 @@ struct event_inject_msg {
 	uint32_t data_ext;
 };
 
+/**
+ * @defgroup ViChanselErrMask VI CHANSEL error numbers
+ * @{
+ */
 #define VI_HSM_CHANSEL_ERROR_MASK_BIT_NOMATCH MK_U32(1)
+/** @} */
+
 /**
  * @brief VI EC/HSM global CHANSEL error masking
  */
 struct vi_hsm_chansel_error_mask_config {
-	/** "Errors with threshold" bit mask */
+	/**
+	 * This error mask applies only to errors that are masked in @ref
+	 * chansel_uncorrectable_mask. By default, all such errors are reported
+	 * to System Error Handler as corrected. If a specific error is masked
+	 * in both this mask and in @ref error_mask_uncorrectable, by setting
+	 * the corresponding bit (1 << <em>error number</em>) in the error mask
+	 * (see @ref ViChanselErrMask "VI CHANSEL error numbers"), the error
+	 * will not be reported to System Error Handler at all.
+	 *
+	 * A corrected safety error will be interpreted by System Error Handler
+	 * as an indication that a single frame has been corrupted or dropped.
+	 */
 	uint32_t chansel_correctable_mask;
-	/** "Uncorrected error" bit mask */
+	/**
+	 * Error mask for suppressing uncorrected safety errors (see @ref
+	 * ViChanselErrMask "VI CHANSEL error numbers"). If the mask is set
+	 * to zero, VI CHANSEL errors will be reported as uncorrected safety
+	 * errors. If a specific error is masked by setting the corresponding
+	 * bit (1 << <em>error number</em>) in the error mask, the error will
+	 * not be reported as uncorrected. Note that the error may still be
+	 * reported as a corrected error unless it is also masked in
+	 * @ref chansel_correctable_mask.
+	 *
+	 * An uncorrected error will be interpreted by System Error Handler
+	 * as an indication that a camera is off-line and cannot continue
+	 * the capture.
+	 */
 	uint32_t chansel_uncorrectable_mask;
 } CAPTURE_IVC_ALIGN;
 
@@ -1489,14 +1580,23 @@ struct vi_hsm_chansel_error_mask_config {
  * @defgroup NvCsiPort NvCSI Port
  * @{
  */
+/** Port A maps to @ref NVCSI_STREAM_0 */
 #define NVCSI_PORT_A		MK_U32(0x0)
+/** Port B maps to @ref NVCSI_STREAM_1 */
 #define NVCSI_PORT_B		MK_U32(0x1)
+/** Port C maps to @ref NVCSI_STREAM_2 */
 #define NVCSI_PORT_C		MK_U32(0x2)
+/** Port D maps to @ref NVCSI_STREAM_3 */
 #define NVCSI_PORT_D		MK_U32(0x3)
+/** Port E maps to @ref NVCSI_STREAM_4 */
 #define NVCSI_PORT_E		MK_U32(0x4)
+/** Port F maps to @ref NVCSI_STREAM_4 with a custom lane swizzle configuration */
 #define NVCSI_PORT_F		MK_U32(0x5)
+/** Port G maps to @ref NVCSI_STREAM_5 */
 #define NVCSI_PORT_G		MK_U32(0x6)
+/** Port H maps to @ref NVCSI_STREAM_5 with a custom lane swizzle configuration */
 #define NVCSI_PORT_H		MK_U32(0x7)
+/** Port not specified. */
 #define NVCSI_PORT_UNSPECIFIED	MK_U32(0xFFFFFFFF)
 /**@}*/