From 1d58216b05ea2ae8af77a8e47a44000ee197cdbb Mon Sep 17 00:00:00 2001 From: Mika Liljeberg Date: Thu, 21 Sep 2023 11:34:06 +0300 Subject: [PATCH] firmware-api: capture message documentation Updated documentation for VI capture channel messages and associated structures and definitions. Added preconditions to all control channel response messages and clarified the descriptions a bit. Added @brief tag to message descriptions. Jira CAMERASW-14052 Change-Id: I40ae468b3317eee22ac08d577460e263fecc3c92 Reviewed-on: https://git-master.nvidia.com/r/c/tegra/camera/firmware-api/+/2984899 Signed-off-by: Mika Liljeberg Reviewed-on: https://git-master.nvidia.com/r/c/linux-nv-oot/+/2993569 Reviewed-on: https://git-master.nvidia.com/r/c/linux-nv-oot/+/3000506 Reviewed-by: Pekka Pessi GVS: Gerrit_Virtual_Submit --- include/soc/tegra/camrtc-capture-messages.h | 256 +++- include/soc/tegra/camrtc-capture.h | 1449 ++++++++++++++----- 2 files changed, 1295 insertions(+), 410 deletions(-) diff --git a/include/soc/tegra/camrtc-capture-messages.h b/include/soc/tegra/camrtc-capture-messages.h index 9dcb1fdf..e3d21959 100644 --- a/include/soc/tegra/camrtc-capture-messages.h +++ b/include/soc/tegra/camrtc-capture-messages.h @@ -121,9 +121,11 @@ struct CAPTURE_MSG_HEADER { /** * @brief VI capture channel setup response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_CHANNEL_SETUP_REQ message. * + * @pre A @ref CAPTURE_CHANNEL_SETUP_REQ message has been sent. + * * @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 @@ -172,9 +174,12 @@ struct CAPTURE_MSG_HEADER { /** * @brief VI capture channel reset response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_CHANNEL_RESET_REQ message. * + * @pre A @ref CAPTURE_CHANNEL_RESET_REQ message has been sent to the + * logical channel. + * * @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 @@ -213,9 +218,12 @@ struct CAPTURE_MSG_HEADER { /** * @brief VI capture channel release response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_CHANNEL_RELEASE_REQ message. * + * @pre A @ref CAPTURE_CHANNEL_RELEASE_REQ message has been sent to the + * logical channel. + * * @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 @@ -272,9 +280,11 @@ struct CAPTURE_MSG_HEADER { /** * @brief ISP capture channel setup response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_CHANNEL_ISP_SETUP_REQ message. * + * @pre A @ref CAPTURE_CHANNEL_ISP_SETUP_REQ message has been sent. + * * @par Header * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header" * - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_ISP_SETUP_RESP @@ -323,9 +333,12 @@ struct CAPTURE_MSG_HEADER { /** * @brief ISP capture channel reset response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_CHANNEL_ISP_RESET_REQ message. * + * @pre A @ref CAPTURE_CHANNEL_ISP_RESET_REQ message has been sent + * to the logical channel. + * * @par Header * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header" * - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_ISP_RESET_RESP @@ -363,9 +376,12 @@ struct CAPTURE_MSG_HEADER { /** * @brief ISP capture channel release response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ message. * + * @pre A @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ message has been sent + * to the logical channel. + * * @par Header * - @ref CAPTURE_CONTROL_MSG@b::@ref CAPTURE_MSG_HEADER "header" * - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP @@ -377,13 +393,148 @@ struct CAPTURE_MSG_HEADER { */ #define CAPTURE_CHANNEL_ISP_RELEASE_RESP MK_U32(0x25) /** @} */ +/** @} */ /** - * @defgroup ViCapMsgType Message types for capture channel IVC messages. + * @defgroup CapMsgType Message types for capture channel IVC messages. + * + * The capture IVC channel is established during boot using the + * @ref CAMRTC_HSP_CH_SETUP command. The IVC channel is bi-directional + * but the usage is asynchronous. The channel is used for sending + * capture requests, ISP requests, and ISP program requests to RCE FW. + * RCE FW in turn will send asynchronous status indications when the + * requests complete. Multiple requests can be in progress in parallel. + * + * The overall message structure is defined by @ref CAPTURE_MSG and the + * structure is the same for both requests and indications. Each 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 on the same logical channel will be executed in the order they + * were submitted and status indications will be sent back in the same order. + * Request ordering is not guaranteed between different logical channels. + * Requests and indications 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. + * * @{ */ + +/** + * @defgroup ViCapMsgType Message types for VI capture request messages and indications. + * + * Capture channel messages are used to submit capture requests and to + * receive status indications pertaining to submitted requests. + * + * @{ + */ + +/** + * @brief Submit a new capture request on a VI capture channel. + * + * This is a @ref CapMsgType "capture channel message" to + * submit a VI capture request. The capture request provides + * a reference to a @ref capture_descriptor in shared memory, + * containing the detailed parameters for the capture. + * + * Capture completion is indicated to downstream engines by + * incrementing the progress syncpoint (see @ref + * capture_channel_config::progress_sp) a pre-calculated number of + * times (2 + number of sub-frames). The first increment + * occurs at @em start-of-frame and the last increment occurs at + * @em end-of-frame. In between, the syncpoint is incremented once + * for each completed @em subframe. The number of @em subframes + * used in the capture is chosen by the client and is implemented + * by programming flush points for the output buffer (see + * @ref vi_channel_config::flush_enable, + * @ref vi_channel_config::flush_periodic, + * @ref vi_channel_config::flush, and + * @ref vi_channel_config::flush_first. When the @em end-of-frame + * increment occurs, the optional @ref capture_descriptor::engine_status + * record is guaranteed to be populated if a buffer for it was + * provided by the client. + * + * If @ref CAPTURE_FLAG_STATUS_REPORT_ENABLE + * is set in @ref capture_descriptor::capture_flags, RCE will store + * the capture status into @ref capture_descriptor::status. RCE will + * also send a @ref CAPTURE_STATUS_IND message to indicate that the + * capture was completed. The capture status record contains information + * about the capture, such as CSI frame number, start-of-frame and + * end-of-frame timestamps, a general success or fail status, + * as well as a detailed record of any errors detected. + * + * If @ref CAPTURE_FLAG_ERROR_REPORT_ENABLE is set in + * @ref capture_descriptor::capture_flags, RCE will send a + * @ref CAPTURE_STATUS_IND message upon an error, even if + * @ref CAPTURE_FLAG_STATUS_REPORT_ENABLE is not set. + * + * @pre A VI capture channel has been set up with + * @ref CAPTURE_CHANNEL_SETUP_REQ. + * + * @par Header + * - @ref CAPTURE_MSG@b::@ref CAPTURE_MSG_HEADER "header" + * - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_REQUEST_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_REQUEST_REQ_MSG + * + * @par Response + * - @ref CAPTURE_STATUS_IND (asynchronous) + */ #define CAPTURE_REQUEST_REQ MK_U32(0x01) + +/** + * @brief Capture status indication. + * + * This is a @ref CapMsgType "capture channel message" + * received in response to a @ref CAPTURE_REQUEST_REQ message + * when the capture request has been completed and the + * capture status record has been written into + * @ref capture_descriptor::status. + * + * @pre A @ref CAPTURE_REQUEST_REQ has been sent with + * @ref CAPTURE_FLAG_STATUS_REPORT_ENABLE or + * @ref CAPTURE_FLAG_ERROR_REPORT_ENABLE set in + * @ref capture_descriptor::capture_flags. + * + * @par Header + * - @ref CAPTURE_MSG@b::@ref CAPTURE_MSG_HEADER "header" + * - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_STATUS_IND + * - @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_STATUS_IND_MSG + */ #define CAPTURE_STATUS_IND MK_U32(0x02) + +/** + * @brief VI capture channel reset barrier indication. + * + * This is a @ref CapMsgType "capture channel message" sent on + * the @em capture IVC channel in conjuncation with a + * @ref CAPTURE_CHANNEL_RESET_REQ message sent on the + * capture-control IVC channel to reset a VI capture channel. + * This indication defines a boundary between capture requests + * submitted before the reset request and capture requests submitted + * after it. Capture requests submitted after the reset request are + * not affected by the reset operation. + * + * @pre A VI capture channel has been set up with a + * @ref CAPTURE_CHANNEL_SETUP_REQ and a + * @ref CAPTURE_CHANNEL_RESET_REQ + * has been sent to the channel. + * + * @par Header + * - @ref CAPTURE_MSG@b::@ref CAPTURE_MSG_HEADER "header" + * - @ref CAPTURE_MSG_HEADER::msg_id "msg_id" = @ref CAPTURE_RESET_BARRIER_IND + * - @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" + */ #define CAPTURE_RESET_BARRIER_IND MK_U32(0x03) /** @} */ @@ -438,13 +589,13 @@ typedef uint32_t capture_result; #define CAPTURE_ERROR_INVALID_STATE MK_U32(9) /** @} */ -/** Message data for @ref CAPTURE_CHANNEL_SETUP_REQ message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_SETUP_REQ message */ 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 Message data for @ref CAPTURE_CHANNEL_SETUP_RESP message */ struct CAPTURE_CHANNEL_SETUP_RESP_MSG { /** Request result code. See @ref CapErrorCodes "result codes". */ capture_result result; @@ -464,7 +615,7 @@ struct CAPTURE_CHANNEL_SETUP_RESP_MSG { #define CAPTURE_CHANNEL_RESET_FLAG_IMMEDIATE MK_U32(0x01) /** @} */ -/** Message data for @ref CAPTURE_CHANNEL_RESET_REQ message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_RESET_REQ message */ struct CAPTURE_CHANNEL_RESET_REQ_MSG { /** See @ref CapResetFlags "reset flags". */ uint32_t reset_flags; @@ -472,14 +623,14 @@ struct CAPTURE_CHANNEL_RESET_REQ_MSG { uint32_t pad__; } CAPTURE_IVC_ALIGN; -/** Message data for @ref CAPTURE_CHANNEL_RESET_RESP message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_RESET_RESP message */ struct CAPTURE_CHANNEL_RESET_RESP_MSG { /** 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 Message data for @ref CAPTURE_CHANNEL_RELEASE_REQ message */ struct CAPTURE_CHANNEL_RELEASE_REQ_MSG { /** Unused */ uint32_t reset_flags; @@ -487,7 +638,7 @@ struct CAPTURE_CHANNEL_RELEASE_REQ_MSG { uint32_t pad__; } CAPTURE_IVC_ALIGN; -/** Message data for @ref CAPTURE_CHANNEL_RELEASE_RESP message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_RELEASE_RESP message */ struct CAPTURE_CHANNEL_RELEASE_RESP_MSG { /** Request result code. See @ref CapErrorCodes "result codes". */ capture_result result; @@ -992,6 +1143,9 @@ struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG { * override the default VI CHANSEL safety error masks on all * active VI units. * + * @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_HSM_CHANSEL_ERROR_MASK_REQ @@ -1008,9 +1162,11 @@ struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG { /** * @brief Override VI CHANSEL safety error masks response. * - * This is a @ref CapCtrlMsgType "capture control message" sent as a + * This is a @ref CapCtrlMsgType "capture control message" received in * response to a @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message. * + * @pre A @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message has been sent. + * * @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 @@ -1028,13 +1184,13 @@ struct CAPTURE_CHANNEL_EI_RESET_RESP_MSG { * @addtogroup ViCapCtrlMsgs * @{ */ -/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message */ +/** @brief Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ message */ struct CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ_MSG { /** 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 Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP message */ struct CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP_MSG { /** Request result. See @ref CapErrorCodes "result codes". */ capture_result result; @@ -1043,13 +1199,13 @@ struct CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP_MSG { } CAPTURE_IVC_ALIGN; /** @} */ -/** Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_REQ message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_REQ message */ struct CAPTURE_CHANNEL_ISP_SETUP_REQ_MSG { /** ISP channel configuration. */ struct capture_channel_isp_config channel_config; } CAPTURE_IVC_ALIGN; -/** Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_RESP message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_RESP message */ struct CAPTURE_CHANNEL_ISP_SETUP_RESP_MSG { /** Request result code. See @ref CapErrorCodes "result codes". */ capture_result result; @@ -1066,7 +1222,7 @@ typedef struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG typedef struct CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG; -/** Message data for @ref CAPTURE_CHANNEL_ISP_RESET_REQ message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_ISP_RESET_REQ message */ struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG { /** Unused */ uint32_t reset_flags; @@ -1074,7 +1230,7 @@ struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG { uint32_t pad__; } CAPTURE_IVC_ALIGN; -/** Message data for @ref CAPTURE_CHANNEL_ISP_RESET_RESP message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_ISP_RESET_RESP message */ struct CAPTURE_CHANNEL_ISP_RESET_RESP_MSG { /** Request result code. See @ref CapErrorCodes "result codes". */ capture_result result; @@ -1082,7 +1238,7 @@ struct CAPTURE_CHANNEL_ISP_RESET_RESP_MSG { uint32_t pad__; } CAPTURE_IVC_ALIGN; -/** Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ message */ struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG { /** Unused */ uint32_t reset_flags; @@ -1090,7 +1246,7 @@ struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG { uint32_t pad__; } CAPTURE_IVC_ALIGN; -/** Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP message */ +/** @brief Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP message */ struct CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG { /** Request result code. See @ref CapErrorCodes "result codes". */ capture_result result; @@ -1273,55 +1429,27 @@ struct CAPTURE_CONTROL_MSG { }; } CAPTURE_IVC_ALIGN; -/** - * @brief Enqueue a new capture request on a capture channel. - * - * The request contains channel identifier and the capture sequence - * number, which are required to schedule the capture request. The - * actual capture programming is stored in the capture descriptor, - * stored in a DRAM ring buffer set up with CAPTURE_CHANNEL_SETUP_REQ. - * - * The capture request descriptor with buffer_index=N can be located - * within the ring buffer as follows: - * - * struct capture_descriptor *desc = requests + buffer_index * request_size; - * - * The capture request message is asynchronous. Capture completion is - * indicated by incrementing the progress syncpoint a pre-calculated - * number of times = 1 + . The first increment - * occurs at start-of-frame and the last increment occurs at - * end-of-frame. The progress-syncpoint is used to synchronize with - * down-stream engines. This model assumes that the capture client - * knows the number of subframes used in the capture and has - * programmed the VI accordingly. - * - * If the flag CAPTURE_FLAG_STATUS_REPORT_ENABLE is set in the capture - * descriptor, RCE will store the capture status into status field - * of the descriptor. RCE will also send a CAPTURE_STATUS_IND - * message to indicate that capture has completed. The capture status - * record contains information about the capture, such as CSI frame - * number, start-of-frame and end-of-frame timestamps, as well as - * error status. - * - * If the flag CAPTURE_FLAG_ERROR_REPORT_ENABLE is set, RCE will send a - * CAPTURE_STATUS_IND upon an error, even if - * CAPTURE_FLAG_STATUS_REPORT_ENABLE is not set. - */ +/** @brief Message data for @ref CAPTURE_REQUEST_REQ message. */ struct CAPTURE_REQUEST_REQ_MSG { - /** Buffer index identifying capture descriptor. */ + /** + * Buffer index identifying the location of a capture descriptor: + * struct @ref capture_descriptor *desc = + * @ref capture_channel_config::requests "requests" + + * buffer_index * @ref capture_channel_config::request_size "request_size"; + */ uint32_t buffer_index; /** Reserved */ uint32_t pad__; } CAPTURE_IVC_ALIGN; -/** - * @brief Capture status indication. - * - * The message is sent after the capture status record has been - * written into the capture request descriptor. - */ +/** @brief Message data for @ref CAPTURE_STATUS_IND message. */ struct CAPTURE_STATUS_IND_MSG { - /** Buffer index identifying capture descriptor. */ + /** + * Buffer index identifying the location of a capture descriptor: + * struct @ref capture_descriptor *desc = + * @ref capture_channel_config::requests "requests" + + * buffer_index * @ref capture_channel_config::request_size "request_size"; + */ uint32_t buffer_index; /** Reserved */ uint32_t pad__; diff --git a/include/soc/tegra/camrtc-capture.h b/include/soc/tegra/camrtc-capture.h index 43f20fba..2ebda3c4 100644 --- a/include/soc/tegra/camrtc-capture.h +++ b/include/soc/tegra/camrtc-capture.h @@ -337,28 +337,28 @@ typedef struct syncpoint_info { * @{ */ /** Output surface plane 0 */ -#define VI_ATOMP_SURFACE0 0U +#define VI_ATOMP_SURFACE0 0U /** Output surface plane 1 */ -#define VI_ATOMP_SURFACE1 1U +#define VI_ATOMP_SURFACE1 1U /** Output surface plane 2 */ -#define VI_ATOMP_SURFACE2 2U +#define VI_ATOMP_SURFACE2 2U /** Sensor embedded data */ #define VI_ATOMP_SURFACE_EMBEDDED 3 /** RAW pixels */ -#define VI_ATOMP_SURFACE_MAIN VI_ATOMP_SURFACE0 +#define VI_ATOMP_SURFACE_MAIN VI_ATOMP_SURFACE0 /** PDAF pixels */ -#define VI_ATOMP_SURFACE_PDAF VI_ATOMP_SURFACE1 +#define VI_ATOMP_SURFACE_PDAF VI_ATOMP_SURFACE1 /** YUV - Luma plane */ -#define VI_ATOMP_SURFACE_Y VI_ATOMP_SURFACE0 +#define VI_ATOMP_SURFACE_Y VI_ATOMP_SURFACE0 /** Semi-planar - UV plane */ -#define VI_ATOMP_SURFACE_UV VI_ATOMP_SURFACE1 +#define VI_ATOMP_SURFACE_UV VI_ATOMP_SURFACE1 /** Planar - U plane */ -#define VI_ATOMP_SURFACE_U VI_ATOMP_SURFACE1 +#define VI_ATOMP_SURFACE_U VI_ATOMP_SURFACE1 /** Planar - V plane */ -#define VI_ATOMP_SURFACE_V VI_ATOMP_SURFACE2 +#define VI_ATOMP_SURFACE_V VI_ATOMP_SURFACE2 /** @} */ @@ -366,101 +366,149 @@ typedef struct syncpoint_info { #define SLVSEC_STREAM_DISABLED MK_U8(0xFF) /** - * @defgroup VICaptureChannelFlags - * VI Capture channel specific flags + * @defgroup VICaptureChannelFlags VI Capture channel specific flags */ /**@{*/ /** Channel takes input from Video Interface (VI) */ -#define CAPTURE_CHANNEL_FLAG_VIDEO MK_U32(0x0001) +#define CAPTURE_CHANNEL_FLAG_VIDEO MK_U32(0x0001) + /** Channel supports RAW Bayer output */ -#define CAPTURE_CHANNEL_FLAG_RAW MK_U32(0x0002) +#define CAPTURE_CHANNEL_FLAG_RAW MK_U32(0x0002) + /** Channel supports planar YUV output */ -#define CAPTURE_CHANNEL_FLAG_PLANAR MK_U32(0x0004) +#define CAPTURE_CHANNEL_FLAG_PLANAR MK_U32(0x0004) + /** Channel supports semi-planar YUV output */ -#define CAPTURE_CHANNEL_FLAG_SEMI_PLANAR MK_U32(0x0008) +#define CAPTURE_CHANNEL_FLAG_SEMI_PLANAR MK_U32(0x0008) + /** Channel supports phase-detection auto-focus (non-safety) */ -#define CAPTURE_CHANNEL_FLAG_PDAF MK_U32(0x0010) +#define CAPTURE_CHANNEL_FLAG_PDAF MK_U32(0x0010) + /** Channel outputs sensor embedded data */ -#define CAPTURE_CHANNEL_FLAG_EMBDATA MK_U32(0x0040) +#define CAPTURE_CHANNEL_FLAG_EMBDATA MK_U32(0x0040) + /** Channel outputs to ISPA (deprecated, non-safety) */ -#define CAPTURE_CHANNEL_FLAG_ISPA MK_U32(0x0080) +#define CAPTURE_CHANNEL_FLAG_ISPA MK_U32(0x0080) + /** Channel outputs to ISPB (deprecated, non-safety) */ -#define CAPTURE_CHANNEL_FLAG_ISPB MK_U32(0x0100) -/** Channel outputs directly to selected ISP (ISO mode) (deprecated, non-safety) */ -#define CAPTURE_CHANNEL_FLAG_ISP_DIRECT MK_U32(0x0200) +#define CAPTURE_CHANNEL_FLAG_ISPB MK_U32(0x0100) + +/** + * 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 (non-safety)*/ -#define CAPTURE_CHANNEL_FLAG_RESET_ON_ERROR MK_U32(0x0800) +#define CAPTURE_CHANNEL_FLAG_ISPSW MK_U32(0x0400) +/** + * 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) +#define CAPTURE_CHANNEL_FLAG_LINETIMER MK_U32(0x1000) + /** Channel supports SLVSEC sensors (non-safety) */ -#define CAPTURE_CHANNEL_FLAG_SLVSEC MK_U32(0x2000) +#define CAPTURE_CHANNEL_FLAG_SLVSEC MK_U32(0x2000) + /** * 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 (deprecated) */ -#define CAPTURE_CHANNEL_FLAG_ENABLE_VI_PFSD MK_U32(0x8000) + +/** + * Enable Permanent Fault Software diagnostics (PFSD) for this VI channel. + * VI will insert a test pattern into a specified part of the frame, to + * be checked after frame capture. A correct test pattern will verify + * that VI internal pipeline is functioning normally. + */ +#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) +#define CAPTURE_CHANNEL_FLAG_CSI MK_U32(0x10000) /**@}*/ /** * @defgroup CaptureChannelErrMask VI error numbers */ /**@{*/ + /** VI Frame start error timeout */ #define CAPTURE_CHANNEL_ERROR_VI_FRAME_START_TIMEOUT MK_BIT32(23) + /** VI Permanent Fault SW Diagnostics (PFSD) error */ #define CAPTURE_CHANNEL_ERROR_VI_PFSD_FAULT MK_BIT32(22) + /** Embedded data incomplete */ #define CAPTURE_CHANNEL_ERROR_ERROR_EMBED_INCOMPLETE MK_BIT32(21) + /** Pixel frame is incomplete */ #define CAPTURE_CHANNEL_ERROR_INCOMPLETE MK_BIT32(20) -/** A Frame End appears from NVCSI before the normal number of pixels has appeared*/ +/** + * A Frame End appears from NVCSI before the normal number of pixels + * has appeared + */ #define CAPTURE_CHANNEL_ERROR_STALE_FRAME MK_BIT32(19) + /** A start-of-frame matches a channel that is already in frame */ #define CAPTURE_CHANNEL_ERROR_COLLISION MK_BIT32(18) + /** Frame end was forced by channel reset */ #define CAPTURE_CHANNEL_ERROR_FORCE_FE MK_BIT32(17) -/** A LOAD command is received for a channel while that channel is currently in a frame.*/ + +/** + * A LOAD command is received for a channel while that channel is + * currently in a frame. + */ #define CAPTURE_CHANNEL_ERROR_LOAD_FRAMED MK_BIT32(16) + /** The pixel datatype changed in the middle of the line */ #define CAPTURE_CHANNEL_ERROR_DTYPE_MISMATCH MK_BIT32(15) + /** Unexpected embedded data in frame */ #define CAPTURE_CHANNEL_ERROR_EMBED_INFRINGE MK_BIT32(14) + /** Extra embedded bytes on line */ #define CAPTURE_CHANNEL_ERROR_EMBED_LONG_LINE MK_BIT32(13) + /** Embedded bytes found between line start and line end*/ #define CAPTURE_CHANNEL_ERROR_EMBED_SPURIOUS MK_BIT32(12) + /** Too many embeded lines in frame */ #define CAPTURE_CHANNEL_ERROR_EMBED_RUNAWAY MK_BIT32(11) + /** Two embedded line starts without a line end in between */ #define CAPTURE_CHANNEL_ERROR_EMBED_MISSING_LE MK_BIT32(10) + /** A line has fewer pixels than expected width */ #define CAPTURE_CHANNEL_ERROR_PIXEL_SHORT_LINE MK_BIT32(9) + /** A line has more pixels than expected width, pixels dropped */ #define CAPTURE_CHANNEL_ERROR_PIXEL_LONG_LINE MK_BIT32(8) + /** A pixel found between line end and line start markers, dropped */ #define CAPTURE_CHANNEL_ERROR_PIXEL_SPURIOUS MK_BIT32(7) + /** Too many pixel lines in frame, extra lines dropped */ #define CAPTURE_CHANNEL_ERROR_PIXEL_RUNAWAY MK_BIT32(6) + /** Two lines starts without a line end in between */ #define CAPTURE_CHANNEL_ERROR_PIXEL_MISSING_LE MK_BIT32(5) + /**@}*/ /** - * @defgroup VIUnitIds - * VI Unit Identifiers + * @defgroup VIUnitIds VI Unit Identifiers */ /**@{*/ /** VI unit 0 */ -#define VI_UNIT_VI MK_U32(0x0000) +#define VI_UNIT_VI MK_U32(0x0000) /** VI unit 1 */ -#define VI_UNIT_VI2 MK_U32(0x0001) +#define VI_UNIT_VI2 MK_U32(0x0001) /**@}*/ /** @@ -678,8 +726,7 @@ struct capture_channel_config { * When a capture error is detected, the capture channel will * enter an error state if the corresponding error bit * (1 << error number) is set in this bit mask - * (see @ref ViNotifyErrorTag "Extended VI error numbers" - * for the bit definitions). + * (see @ref ViNotifyErrorTag "VI errors" for the bit definitions). * * When the channel is in error state it will not accept any new * capture requests. @@ -688,190 +735,583 @@ struct capture_channel_config { } CAPTURE_IVC_ALIGN; +/** + * @defgroup ViDpcmModes VI DPCM Modes (non-safety) + */ +/**@{*/ + +/** T186-style RAW10 format */ +#define VI_DPCM_RAW10 MK_U8(0) + +/** T186-style RAW12 format */ +#define VI_DPCM_RAW12 MK_U8(1) + +/** Run-length-encoded RAW10 format */ +#define VI_DPCM_RLE_RAW10 MK_U8(2) + +/** Run-length-encoded RAW12 format */ +#define VI_DPCM_RLE_RAW12 MK_U8(3) + +/** RAW16 format for logarithmic data */ +#define VI_DPCM_RAW16 MK_U8(4) + +/** RAW20 format */ +#define VI_DPCM_RAW20 MK_U8(5) + +/**@}*/ + +/** + * @defgroup ViPixFmt VI Output Pixel Formats + */ +/**@{*/ +/** NvColorFormat_R5G6B5 */ +#define VI_PIXFMT_FORMAT_T_R5G6B5 MK_U8(1) + +/** NvColorFormat_B5G6R5 */ +#define VI_PIXFMT_FORMAT_T_B5G6R5 MK_U8(2) + +/** NvColorFormat_R8 */ +#define VI_PIXFMT_FORMAT_T_R8 MK_U8(5) + +/** NvColorFormat_A8B8G8R8 */ +#define VI_PIXFMT_FORMAT_T_A8B8G8R8 MK_U8(8) + +/** NvColorFormat_A8R8G8B8 */ +#define VI_PIXFMT_FORMAT_T_A8R8G8B8 MK_U8(9) + +/** NvColorFormat_B8G8R8A8 */ +#define VI_PIXFMT_FORMAT_T_B8G8R8A8 MK_U8(10) + +/** NvColorFormat_R8G8B8A8 */ +#define VI_PIXFMT_FORMAT_T_R8G8B8A8 MK_U8(11) + +/** NvColorFormat_Y8_U8__Y8_V8 or NvColorFormat_YUYV */ +#define VI_PIXFMT_FORMAT_T_Y8_U8__Y8_V8 MK_U8(16) + +/** NvColorFormat_Y8_V8__Y8_U8 or NvColorFormat_YVYU */ +#define VI_PIXFMT_FORMAT_T_Y8_V8__Y8_U8 MK_U8(17) + +/** NvColorFormat_V8_Y8__U8_Y8 or NvColorFormat_VYUY */ +#define VI_PIXFMT_FORMAT_T_V8_Y8__U8_Y8 MK_U8(18) + +/** NvColorFormat_U8_Y8__V8_Y8 or NvColorFormat_UYVY */ +#define VI_PIXFMT_FORMAT_T_U8_Y8__V8_Y8 MK_U8(19) + +/** NV21 format (YUV420 semi-planar: Y8,U8V8) */ +#define VI_PIXFMT_FORMAT_T_Y8__U8V8_N420 MK_U8(34) + +/** NV12 format (YUV420 semi-planar: Y8,V8U8) */ +#define VI_PIXFMT_FORMAT_T_Y8__V8U8_N420 MK_U8(35) + +/** NvColorFormat_B5G5R5A1 */ +#define VI_PIXFMT_FORMAT_T_B5G5R5A1 MK_U8(42) + +/** NvColorFormat_R5G5B5A1 */ +#define VI_PIXFMT_FORMAT_T_R5G5B5A1 MK_U8(43) + +/** NV61 format (YUV422 semi-planar: Y8,U8V8) */ +#define VI_PIXFMT_FORMAT_T_Y8__U8V8_N422 MK_U8(44) + +/** NV16 format (YUV422 semi-planar: Y8,V8U8) */ +#define VI_PIXFMT_FORMAT_T_Y8__V8U8_N422 MK_U8(45) + +/** YV16 format (YUV422 full planar: Y8,U8,V8) */ +#define VI_PIXFMT_FORMAT_T_Y8__U8__V8_N422 MK_U8(46) + +/** YV12 format (YUV420 full planar: Y8,U8,V8) */ +#define VI_PIXFMT_FORMAT_T_Y8__U8__V8_N420 MK_U8(47) + +/** RLE compressed format for RAW10 data */ +#define VI_PIXFMT_FORMAT_T_DPCM_RAW10 MK_U8(64) + +/** NvColorFormat_A2B10G10R10 */ +#define VI_PIXFMT_FORMAT_T_A2B10G10R10 MK_U8(68) + +/** NvColorFormat_A2R10G10B10 */ +#define VI_PIXFMT_FORMAT_T_A2R10G10B10 MK_U8(69) + +/** NvColorFormat_B10G10R10A2 */ +#define VI_PIXFMT_FORMAT_T_B10G10R10A2 MK_U8(70) + +/** NvColorFormat_R10G10B10A2 */ +#define VI_PIXFMT_FORMAT_T_R10G10B10A2 MK_U8(71) + +/** NvColorFormat_A4B4G4R4 */ +#define VI_PIXFMT_FORMAT_T_A4B4G4R4 MK_U8(80) + +/** NvColorFormat_A4R4G4B4 */ +#define VI_PIXFMT_FORMAT_T_A4R4G4B4 MK_U8(81) + +/** NvColorFormat_B4G4R4A4 */ +#define VI_PIXFMT_FORMAT_T_B4G4R4A4 MK_U8(82) + +/** NvColorFormat_R4G4B4A4 */ +#define VI_PIXFMT_FORMAT_T_R4G4B4A4 MK_U8(83) + +/** NvColorFormat_A1B5G5R5 */ +#define VI_PIXFMT_FORMAT_T_A1B5G5R5 MK_U8(84) + +/** NvColorFormat_A1R5G5B5 */ +#define VI_PIXFMT_FORMAT_T_A1R5G5B5 MK_U8(85) + +/** NV12 format (YUV420 semi-planar: Y10,V10U10) */ +#define VI_PIXFMT_FORMAT_T_Y10__V10U10_N420 MK_U8(98) + +/** NV21 format (YUV420 semi-planar: Y10,U10V10) */ +#define VI_PIXFMT_FORMAT_T_Y10__U10V10_N420 MK_U8(99) + +/** YV12 format (YUV420 full planar: Y10,U10,V10) */ +#define VI_PIXFMT_FORMAT_T_Y10__U10__V10_N420 MK_U8(100) + +/** NV16 format (YUV422 semi-planar: Y10,V10U10) */ +#define VI_PIXFMT_FORMAT_T_Y10__V10U10_N422 MK_U8(101) + +/** NV61 format (YUV422 semi-planar: Y10,U10V10) */ +#define VI_PIXFMT_FORMAT_T_Y10__U10V10_N422 MK_U8(102) + +/** YV16 format (YUV422 full planar: Y10,U10,V10) */ +#define VI_PIXFMT_FORMAT_T_Y10__U10__V10_N422 MK_U8(103) + +/** RLE compressed format for RAW12 data */ +#define VI_PIXFMT_FORMAT_T_DPCM_RAW12 K_U32(128) + +/** RAW ISP encoded float, 20-bit fixed */ +#define VI_PIXFMT_FORMAT_T_R16_X_ISP20 MK_U8(194) + +/** Alias for @ref VI_PIXFMT_FORMAT_T_R16_X_ISP20 */ +#define VI_PIXFMT_FORMAT_T_R16_ISP VI_PIXFMT_FORMAT_T_R16_X_ISP20 + +/** NvColorFormat_Float_R16 */ +#define VI_PIXFMT_FORMAT_T_R16_F MK_U8(195) + +/** NvColorFormat_R16 */ +#define VI_PIXFMT_FORMAT_T_R16 MK_U8(196) + +/** NvColorFormat_Int_R16 */ +#define VI_PIXFMT_FORMAT_T_R16_I MK_U8(197) + +/** NvColorFormat_R16_X_ISP24 (RAW ISP encoded float, 24-bit fixed) */ +#define VI_PIXFMT_FORMAT_T_R16_X_ISP24 MK_U8(198) + +/** NvColorFormat_R24 */ +#define VI_PIXFMT_FORMAT_T_R24 MK_U8(210) + +/** NvColorFormat_R32 */ +#define VI_PIXFMT_FORMAT_T_R32 MK_U8(230) + +/** NvColorFormat_Float_R32 */ +#define VI_PIXFMT_FORMAT_T_R32_F MK_U8(232) + +/** RLE compressed format for RAW16 data */ +#define VI_PIXFMT_FORMAT_T_DPCM_RAW16 MK_U8(254) + +/** RLE compressed format for RAW20 data */ +#define VI_PIXFMT_FORMAT_T_DPCM_RAW20 MK_U8(255) +/**@}*/ + + /** * @brief VI Channel configuration * - * VI unit register programming for capturing a frame. + * Parameters for VI unit register programming to capture a frame. */ struct vi_channel_config { - /** DT override enabled flag */ + /** Enable CSI datatype override (1=enable, 0=disable). */ unsigned dt_enable:1; - /** Embedded data enabled flag */ + + /** Enable reception of sensor embedded data (1=enable, 0=disable). */ unsigned embdata_enable:1; - /** Flush notice enabled flag */ + + /** Enable memory flush function (1=enable, 0=disable). */ unsigned flush_enable:1; - /** Periodic flush notice enabled flag */ + + /** Enable periodic (subframe) memory flushes (1=enable, 0=disable). */ unsigned flush_periodic:1; - /** Line timer enabled flag */ + + /** Enable line timer function (1=enable, 0=disable). */ unsigned line_timer_enable:1; - /** Periodic line timer notice enabled flag */ + + /** Periodic line timer notice enabled flag (1=enable, 0=disable). */ unsigned line_timer_periodic:1; - /** Enable PIXFMT writing pixels flag */ + + /** Enable PIXFMT writing pixels flag (1=enable, 0=disable). */ unsigned pixfmt_enable:1; - /** Flag to enable merging adjacent RAW8/RAW10 pixels */ + + /** + * Enable merging of adjacent RAW8, RAW10, or RAW12 pixel values + * into a single wide pixel (1=enable, 0=disable). + */ unsigned pixfmt_wide_enable:1; - /** Flag to enable big or little endian. 0 - Big Endian, 1 - Little Endian */ + + /** Set wide pixel endianness (0 = big endian, 1 = little endian). */ unsigned pixfmt_wide_endian:1; - /** Flag to enable Phase Detection Auto Focus (PDAF) pixel replacement */ + + /** + * Enable Phase Detection Auto Focus (PDAF) pixel replacement + * (1=enable, 0=disable). (non-safety) + */ unsigned pixfmt_pdaf_replace_enable:1; - /** ISPA buffer enabled */ + + /** ISPA buffer enabled (1=enable, 0=disable). (deprecated, non-safety) */ unsigned ispbufa_enable:1; - /** ISPB buffer enabled. Not valid for T186 & T194 */ + + /** ISPB buffer enabled (1=enable, 0=disable). (deprecated, non-safety) */ unsigned ispbufb_enable:1; - /** VI Companding module enable flag */ + + /** Enable pixel companding (1=enable, 0=disable). (non-safety) */ unsigned compand_enable:1; + /** Reserved bits */ unsigned pad_flags__:19; - /* VI channel selector */ struct match_rec { - /** Datatype to be sent to the channel */ + /** + * @ref NvCsiDataType "CSI datatype" value to match. + */ uint8_t datatype; - /** Bits of datatype to match on */ + + /** + * Bitmask for bits of @ref datatype to compare [0, UINT8_MAX]. + * Normally set to UINT8_MAX to not restrict the comparison. + */ uint8_t datatype_mask; - /** CSIMUX source to send to this channel */ + + /** + * 1-hot encoded @ref NvCsiStream "NVCSI stream" to match + * (1 << @ref NvCsiStream "stream"). + */ uint8_t stream; - /** Bits of STREAM to match on. */ + + /** + * Bitmask for bits of @ref stream to compare [0, 0x3F]. + * Normally set to 0x3F to not restrict the comparison. + */ uint8_t stream_mask; - /** Virtual channel to be sent to this channel */ + + /** + * 1-hot encoded @ref NvCsiVirtualChannel "CSI Virtual Channel" + * to match (1 << @ref NvCsiVirtualChannel "VC"). + */ uint16_t vc; - /** Bits of VIRTUAL_CHANNEL_MASK to match on */ + + /** + * Bitmask for bits of @ref vc to compare [0, UINT16_MAX]. + * Normally set to UINT16_MAX to not restrict the comparison. + */ uint16_t vc_mask; - /** Frame id to be sent to this channel */ + + /** CSI frame number to match. */ uint16_t frameid; - /** Bits of FRAME_ID to match on. */ + + /** + * Bitmask for bits of @ref frameid to compare [0, UINT16_MAX]. + * Normally set to 0 to disable frame matching. + */ uint16_t frameid_mask; - /** Data in the first pixel of a line to match on */ + + /** + * For Sony sensors with Digital Overlap mode: + * data in the DOL header to match [0, UINT16_MAX]. + */ uint16_t dol; - /** Bits of DOL to match on */ + + /** + * Bitmask for bits of @ref dol to compare [0, UINT16_MAX]. + * Normally set to 0 to disable DOL matching. + */ uint16_t dol_mask; } match; + /**< + * VI channel match parameters. Used to select incoming frames + * for this VI channel. + */ - /** DOL header select */ + /** + * For Sony sensors with Digital Overlap mode: DOL header select [0, 3]. + * Configures which pixel in the first pixel packet will carry the + * DOL header used for channel matching (see @ref match::dol). + */ uint8_t dol_header_sel; - /** Data type override */ + + /** + * @ref NvCsiDataType "Datatype" override value. If @ref dt_enable is + * set this value overrides the incoming pixel datatype from the sensor. + * This setting can be used to capture user defined datatypes, for + * example. + */ uint8_t dt_override; - /** DPCM mode to be used. Currently DPCM is not used */ + + /** @ref ViDpcmModes "VI DPCM Mode". (non-safety) */ uint8_t dpcm_mode; + /** Reserved */ uint8_t pad_dol_dt_dpcm__; struct vi_frame_config { - /** Pixel width of frame before cropping */ + /** + * Frame width (pixels) before cropping [0, UINT16_MAX]. + * 0 is interpreted as 65536. + */ uint16_t frame_x; - /** Line height of frame */ + + /** + * Frame height (lines) before cropping [0, UINT16_MAX]. + * 0 is interpreted as 65536. + */ uint16_t frame_y; - /** Maximum number of embedded data bytes on a line */ + + /** Number of embedded data bytes on a line [0, 131071]. */ uint32_t embed_x; - /** Number of embedded lines in frame */ + + /** Number of embedded data lines in a frame [0, 65535]. */ uint32_t embed_y; + struct skip_rec { /** - * Number of packets to skip on output at start of line. - * Counted in groups of 8 pixels + * Left edge of the crop region, counted in groups + * of 8 pixels [0, MIN(@ref frame_x - 1, + * @ref crop_rec::x - 1) / 8]. Left crop is disabled + * if the value is 0. */ uint16_t x; - /** Number of lines to skip at top of the frame */ + /** + * Top edge of crop region counted in lines + * [0, MIN(@ref frame_y - 1, @ref crop_rec::y - 1)]. + * Top crop is disabled if the value is 0. + */ uint16_t y; - } skip; - struct crop_rec { - /** Line width in pixels after which no packets will be transmitted */ - uint16_t x; - /** Height in lines after which no lines will be transmitted */ - uint16_t y; - } crop; - } frame; + } skip; /**< Top left corner of crop region */ - /** Pixel line count at which a flush notice is sent out */ + struct crop_rec { + /** + * Right edge of crop region counted in pixels + * [0, UINT16_MAX]. 0 is interpreted as 65536. Right + * crop is disabled if the crop region reaches beyond + * the right edge of the frame (>= @ref frame_x). + */ + uint16_t x; + + /** + * Bottom edge of crop region counted in lines + * [0, UINT16_MAX]. Bottom crop is disabled if the crop + * region reaches beyond the bottom edge of the frame + * (>= @ref frame_y). + */ + uint16_t y; + } crop; /**< Bottom right corner of crop region */ + } frame; + /**< + * Frame configuration (frame resolution, crop region, + * number of embedded data lines) + */ + + /** + * Flush to memory after @em flush pixel lines [0, UINT16_MAX]. + * 0 is interpreted as 65536. @ref flush_enable must be set for this + * setting to take effect. @ref flush_periodic must be set in order to + * repeat the memory flush every @em flush lines. + */ uint16_t flush; - /** Line count at which to trip the first flush event */ + + /** + * Number of pixel lines before first memory flush [0, UINT16_MAX]. + * Can be used to trigger the first memory flush on a line different + * from @ref flush. 0 disables this setting. + */ uint16_t flush_first; - /** Pixel line count at which a notification is sent out*/ + /** + * Pixel line count between memory line timer events [0, UINT16_MAX]. + * 0 is interpreted as 65536. @ref flush_enable must be set + * for this setting to take effect. + */ uint16_t line_timer; + /** Line count at which to trip the first line timer event */ uint16_t line_timer_first; - /* Pixel formatter */ struct pixfmt_rec { - /** Pixel memory format for the VI channel */ + /** @ref ViPixFmt "VI Output Pixel Format". */ uint16_t format; - /** Zero padding control for RAW8/10/12/14->T_R16 and RAW20/24->T_R32 */ + + /** + * Zero padding control for RAW8/10/12/14->T_R16 and + * RAW20/24->T_R32. 0 = disable, 1 = right alined MSB padded, + * 2 = left aligned LSB padded. + */ uint8_t pad0_en; + /** Reserved */ uint8_t pad__; + struct pdaf_rec { - /** Within a line, X pixel position at which PDAF separation begins */ + /** + * Within a line, X pixel position at which PDAF + * separation begins [0, UINT16_MAX]. + */ uint16_t crop_left; - /** Within a line, X pixel position at which PDAF separation ends*/ + + /** + * Within a line, X pixel position at which PDAF + * separation ends [0, UINT16_MAX]. + */ uint16_t crop_right; - /** Line at which PDAF separation begins */ + + /** + * Line at which PDAF separation begins + * [0, UINT16_MAX]. + */ uint16_t crop_top; - /** line at which PDAF separation ends */ + + /** + * line at which PDAF separation ends + * [0, UINT16_MAX]. + */ uint16_t crop_bottom; - /** Within a line, X pixel position at which PDAF replacement begins*/ + + /** + * Within a line, X pixel position at which PDAF + * replacement begins [0, UINT16_MAX]. + */ uint16_t replace_crop_left; - /** Within a line, X pixel position at which PDAF replacement ends*/ + + /** + * Within a line, X pixel position at which PDAF + * replacement ends [0, UINT16_MAX]. + */ uint16_t replace_crop_right; - /** Line at which PDAF replacement begins */ + + /** + * Line at which PDAF replacement begins + * [0, UINT16_MAX]. + */ uint16_t replace_crop_top; - /** Line at which PDAF repalcement ends */ + + /** + * Line at which PDAF repalcement ends + * [0, UINT16_MAX]. + */ uint16_t replace_crop_bottom; - /** X coordinate of last PDAF pixel within the PDAF crop window */ + + /** + * X coordinate of last PDAF pixel within the PDAF + * crop window [0, UINT16_MAX]. */ uint16_t last_pixel_x; - /** Y coordinate of last PDAF pixel within the PDAF crop window */ + + /** + * Y coordinate of last PDAF pixel within the PDAF + * crop window [0, UINT16_MAX]. + */ uint16_t last_pixel_y; + /** Value to replace PDAF pixel with */ uint16_t replace_value; - /** Memory format in which the PDAF pixels will be written in */ + + /** + * Memory format for writing PDAF pixels. Only + * T_R16_X_ISP20, T_R16_F, T_R16, T_R32, and T_R32_F + * formats are supported (see @ref ViPixFmt + * "VI Output Pixel Formats" for values). + */ uint8_t format; + /** Reserved */ uint8_t pad_pdaf__; } pdaf; - } pixfmt; + /**< + * Configuration for Phase Detection Auto-Focus pixels. + * (non-safety) + */ + + } pixfmt; /**< Pixel format configuration */ - /* Pixel DPCM */ struct dpcm_rec { - /** Number of pixels in the strip */ + /** + * Number of pixels in the strip [0, UINT16_MAX] (@deprecated). + * */ uint16_t strip_width; - /** Number of packets in overfetch region */ + + /** + * Number of pixel packets in overfetch region [0, UINT16_MAX]. + * 0 disables overfetch. + */ uint16_t strip_overfetch; - /** Not for T186 or earlier */ - /** Number of packets in first generated chunk (no OVERFETCH region in first chunk) */ - uint16_t chunk_first; - /** Number of packets in “body” chunks (including OVERFETCH region, if enabled) */ - uint16_t chunk_body; - /** Number of “body” chunks to emit */ - uint16_t chunk_body_count; /** - * Number of packets in chunk immediately after “body” chunks (including OVERFETCH - * region, if enabled) + * Number of pixel packets in first generated chunk + * (no OVERFETCH region) [0, UINT16_MAX]. + * */ + uint16_t chunk_first; + + /** + * Number of pixel packets in “body” chunks (including + * possible overfetch) [0, UINT16_MAX]. + */ + uint16_t chunk_body; + + /** Number of “body” chunks to emit [0, UINT16_MAX]. */ + uint16_t chunk_body_count; + + /** + * Number of pixel packets in chunk immediately after “body” + * chunks (including possible overfecth) [0, UINT16_MAX]., */ uint16_t chunk_penultimate; - /** Number of packets in final generated chunk (including OVERFETCH region, if enabled) */ + + /** + * Number of pixel packets in the final generated chunk + * (including possible overfetch) [0, UINT16_MAX]. + */ uint16_t chunk_last; + /** Reserved */ uint16_t pad__; - /** Maximum value to truncate input data to */ - uint32_t clamp_high; - /** Minimum value to truncate input data to */ - uint32_t clamp_low; - } dpcm; - /* Atom packer */ + /** Maximum value to truncate input data to [0, 0xFFFFF]. */ + uint32_t clamp_high; + + /** Minimum value to truncate input data to [0, 0xFFFFF]. */ + uint32_t clamp_low; + + } dpcm; /**< Configuration for DPCM compression. (non-safety) */ + struct atomp_rec { struct surface_rec { - /** Offset within memory buffer */ + /** + * Undefined in RCE-FW interface. + * + * In the UMD-KMD shared memory interface this carries + * an offset into the memory buffer identified by + * a memory handle stored in @ref offset_hi. + */ uint32_t offset; - /** Memory handle of the buffer. Must be valid handle or 0 */ + + /** + * Undefined in RCE-FW interface. + * + * In the UMD-KMD interface this carries a memory + * handle for the output buffer. See KMD documentation + * for the constraints. + */ uint32_t offset_hi; + } surface[VI_NUM_ATOMP_SURFACES]; - /** Line stride of the surface in bytes */ + /**< + * Memory buffers for output surfaces. Currently only defined + * for the shared memory interface between UMD and KMD. The + * content is undefined for the RCE-FW interface. + */ + + /** Line stride of the surface in bytes [0, 0xFFFFF]. */ uint32_t surface_stride[VI_NUM_ATOMP_SURFACES]; - /** DPCM chunk stride (distance from start of chunk to end of chunk) */ + + /** + * DPCM chunk stride (distance from start of chunk to end of + * chunk) [0, 0xFFFFF]. + * */ uint32_t dpcm_chunk_stride; } atomp; + /**< Memory output configuration. */ /** Reserved */ uint16_t pad__[2]; @@ -879,12 +1319,28 @@ struct vi_channel_config { } CAPTURE_IVC_ALIGN; /** - * @brief Engine status buffer base address. + * @brief Memory buffer for engine status. + * + * This structure is used to between UMD and KMD to share a buffer + * for writing VI or ISP engine status. */ struct engine_status_surface { - /** Offset within memory buffer */ + /** + * Undefined in RCE-FW interface. + * + * In the UMD-KMD interface this carries an Offset into a memory + * buffer identified by the buffer handle stored in @ref offset_hi. + * + * Valid only in UMD-KMD interface. + */ uint32_t offset; - /** Memory handle of the buffer. Must be valid handle or 0 */ + + /** + * Undefined in RCE-FW interface. + * + * In the UMD-KMD inteface this carries a memory handle for the + * engine stauts buffer. Must be a valid buffer handle or 0. + */ uint32_t offset_hi; } CAPTURE_IVC_ALIGN; @@ -901,218 +1357,374 @@ struct watermark_mem_offset { /** * @brief NVCSI error status * - * Represents error reported from CSI source used by capture descriptor. + * Detailed error information reported by the CSI interface. + * + * This information is provided for logging and triage of any capture + * issues. The information is queried from the CSI interface whenever + * a capture request completes. However, it should be noted that the + * information is not frame accurate or even channel accurate in some + * cases. + * + * Any error reported here must not be construed to mean + * that the captured frame is good or bad. Please refer to + * @ref capture_status::status for making that judgement. * */ struct nvcsi_error_status { /** - * NVCSI @ref NvCsiStreamErrors "errors" reported for stream used by capture descriptor + * NVCSI @ref NvCsiStreamErrors "stream errors" map to a CSI port + * and affect all capture channels sharing that port via the use + * of CSI virtual channels. * - * Stream error affects multiple virtual channel. - * It will be is reported only once, for the first capture channel - * which retrieved the error report. + * The errors will only be reported only once, on the capture channel + * which happened to retrieve the error report first, not on all + * capture channels sharing the CSI port. * - * This error cause data packet drops and should trigger VI errors in - * affected virtual channels. + * Note that these errors will cause VI to independently detect + * errors on all affected channels and the error reporting done + * by VI is frame accurate, unlike CSI, so the client need not + * consider these errors for normal operation. */ uint32_t nvcsi_stream_bits; /** - * @defgroup NvCsiStreamErrors - * NVCSI Stream error bits + * @defgroup NvCsiStreamErrors NVCSI Stream error bits */ /** @{ */ + + /** + * Both CRC values in a CPHY CSI packet header have a mismatch. + * The packet header is corrupted. + */ #define NVCSI_STREAM_ERR_STAT_PH_BOTH_CRC_ERR MK_BIT32(1) + + /** + * Multiple bit errors detected by in DPHY CSI packet header by ECC. + * The packet header is corrupted. + */ #define NVCSI_STREAM_ERR_STAT_PH_ECC_MULTI_BIT_ERR MK_BIT32(0) /** @} */ /** - * NVCSI @ref NvcsiVirtualChannelErrors "errors" reported for stream virtual channel used by capture descriptor - * These errors are expected to be forwarded to VI and also reported by VI as CSIMUX Frame CSI_FAULT errors + * NVCSI @ref NvcsiVirtualChannelErrors "virtual channel errors" map + * to a single CSI virtual channel carried over a CSI port. These + * errors are also forwarded to VI with each frame-end packet and + * reported to the client with each affected capture request as + * part of @ref notify_bits. */ uint32_t nvcsi_virtual_channel_bits; /** - * @defgroup NvCsiVirtualChannelErrors - * NVCSI Virtual Channel error bits + * @defgroup NvCsiVirtualChannelErrors NVCSI Virtual Channel error bits */ /** @{ */ -#define NVCSI_VC_ERR_INTR_STAT_PH_SINGLE_CRC_ERR_VC0 MK_BIT32(4) -#define NVCSI_VC_ERR_INTR_STAT_PD_WC_SHORT_ERR_VC0 MK_BIT32(3) -#define NVCSI_VC_ERR_INTR_STAT_PD_CRC_ERR_VC0 MK_BIT32(2) -#define NVCSI_VC_ERR_INTR_STAT_PH_ECC_SINGLE_BIT_ERR_VC0 MK_BIT32(1) -#define NVCSI_VC_ERR_INTR_STAT_PPFSM_TIMEOUT_VC0 MK_BIT32(0) + + /** + * CSI embedded data line CRC error. The sensor embedded data + * is corrupted. + */ +#define NVCSI_VC_ERR_INTR_STAT_EMBEDDED_LINE_CRC_ERR MK_BIT32(5) + + /** + * One out of two CRCs for the CPHY CSI packet header mismatches. + * The CRC value itself is corrupted. This error does not + * cause frame corruption. + */ +#define NVCSI_VC_ERR_INTR_STAT_PH_SINGLE_CRC_ERR MK_BIT32(4) + + /** + * CSI payload data word count short error. The received data line + * was incomplete. + */ +#define NVCSI_VC_ERR_INTR_STAT_PD_WC_SHORT_ERR MK_BIT32(3) + + /** + * A CRC mismatch was detected in CSI packet payload data. + * The payload is corrupted. + */ +#define NVCSI_VC_ERR_INTR_STAT_PD_CRC_ERR MK_BIT32(2) + + /** + * A single bit error was corrected by ECC in the DPHY CSI + * packet header. + */ +#define NVCSI_VC_ERR_INTR_STAT_PH_ECC_SINGLE_BIT_ERR MK_BIT32(1) + + /** + * CSI pixel parser finite state machine timeout. + * A line of data was not received in time + * (see @ref CAPTURE_CSI_STREAM_SET_PARAM_REQ_MSG::watchdog_config). + */ +#define NVCSI_VC_ERR_INTR_STAT_PPFSM_TIMEOUT MK_BIT32(0) /** @} */ /** - * NVCSI errors reported for CIL interface used by capture descriptor + * NVCSI @ref NvCsiCilErrors "common interface logic errors" + * reported by partition A of the CSI brick (CIL A). */ - /** NVCSI CIL A @ref NvCsiCilErrors "errors" */ uint32_t cil_a_error_bits; - /** NVCSI CIL B @ref NvCsiCilErrors "errors" */ + + /** + * NVCSI @ref NvCsiCilErrors "common interface logic errors" + * reported by partition B of the CSI brick (CIL B). + */ uint32_t cil_b_error_bits; /** - * @defgroup NvCsiCilErrors - * NVCSI CIL error bits + * @defgroup NvCsiCilErrors NVCSI CIL error bits */ /** @{ */ -#define NVCSI_ERR_CIL_DATA_LANE_SOT_2LSB_ERR1 MK_BIT32(16) -#define NVCSI_ERR_CIL_DATA_LANE_SOT_2LSB_ERR0 MK_BIT32(15) + + /** Escape mode sync error on lane 1. */ #define NVCSI_ERR_CIL_DATA_LANE_ESC_MODE_SYNC_ERR1 MK_BIT32(14) + + /** Escape mode sync error on lane 0. */ #define NVCSI_ERR_CIL_DATA_LANE_ESC_MODE_SYNC_ERR0 MK_BIT32(13) + + /** + * Lane alignment error. Some lanes detected a sync word while + * other lanes did not. + */ #define NVCSI_ERR_DPHY_CIL_LANE_ALIGN_ERR MK_BIT32(12) + + /** + * DPHY skew calibration did not complete while sweeping the + * clock lane trimmer. This will happen if the calibration + * sequence is not long enough. + */ #define NVCSI_ERR_DPHY_CIL_DESKEW_CALIB_ERR_CTRL MK_BIT32(11) + + /** + * DPHY skew calibration did not complete while sweeping the + * data lane 1 trimmer. This will happen if the calibration + * sequence is not long enough. + */ #define NVCSI_ERR_DPHY_CIL_DESKEW_CALIB_ERR_LANE1 MK_BIT32(10) + + /** + * DPHY skew calibration did not complete while sweeping the + * data lane 0 trimmer. This will happen if the calibration + * sequence is not long enough. + */ #define NVCSI_ERR_DPHY_CIL_DESKEW_CALIB_ERR_LANE0 MK_BIT32(9) + + /** Data lane 1 receive FIFO overflow. */ #define NVCSI_ERR_CIL_DATA_LANE_RXFIFO_FULL_ERR1 MK_BIT32(8) + + /** LP sequence error detected on DATA lane 1. */ #define NVCSI_ERR_CIL_DATA_LANE_CTRL_ERR1 MK_BIT32(7) + + /** Multiple bit errors detected in the data lane 1 sync word. */ #define NVCSI_ERR_CIL_DATA_LANE_SOT_MB_ERR1 MK_BIT32(6) + + /** Single bit error detected in the lane 1 sync word. */ #define NVCSI_ERR_CIL_DATA_LANE_SOT_SB_ERR1 MK_BIT32(5) + + /** Data lane 0 receive FIFO overflow. */ #define NVCSI_ERR_CIL_DATA_LANE_RXFIFO_FULL_ERR0 MK_BIT32(4) + + /** LP sequence error detected on DATA lane 0. */ #define NVCSI_ERR_CIL_DATA_LANE_CTRL_ERR0 MK_BIT32(3) + + /** Multiple bit errors detected in the data lane 0 sync word */ #define NVCSI_ERR_CIL_DATA_LANE_SOT_MB_ERR0 MK_BIT32(2) + + /** Single bit error detected in the lane 0 sync word. */ #define NVCSI_ERR_CIL_DATA_LANE_SOT_SB_ERR0 MK_BIT32(1) + + /** DPHY clock lane control error */ #define NVCSI_ERR_DPHY_CIL_CLK_LANE_CTRL_ERR MK_BIT32(0) /** @} */ }; /** * @brief Frame capture status record + * + * The capture status is part of @ref capture_descriptor and is populated + * by RCE-FW when the capture request is completed. The status record + * is guaranteed to be up-to-date before RCE-FW sends the @ref + * CAPTURE_STATUS_IND message to the client in order to signal request + * completion. */ struct capture_status { - /** CSI stream number */ + /** @ref NvCsiStream "CSI Stream Number". */ uint8_t src_stream; - /** CSI virtual channel number */ + + /** @ref NvCsiVirtualChannel "CSI virtual channel number". */ uint8_t virtual_channel; - /** Frame sequence number */ + + /** Frame number from sensor. Value range depends on the sensor. */ uint16_t frame_id; - /** Capture status. See @ref CaptureStatusCodes "codes". */ + + /** @ref CaptureStatusCodes "Capture status code". */ uint32_t status; /** - * @defgroup CaptureStatusCodes - * Capture status codes + * @defgroup CaptureStatusCodes Capture status codes */ + /** @{ */ -/** Capture status unknown. - * Value of @ref err_data "err_data" is undefined. +/** + * Capture status unknown. This usually means that the capture request + * is not yet executed or is still in progress. The values of other + * fields in the capture status record are undefined. */ #define CAPTURE_STATUS_UNKNOWN MK_U32(0) -/** Capture status success. - * Value of @ref err_data "err_data" is undefined. + +/** + * Capture status success. + * + * Value of @ref notify_bits may be checked for any + * non frame-corrupting errors detected during capture. */ #define CAPTURE_STATUS_SUCCESS MK_U32(1) -/** CSIMUX frame error. + +/** + * CSIMUX frame error. Maps to VI CSIMUX_FRAME notify event. * - * Maps to VI CSIMUX_FRAME event. + * This signals an error detected by VI at frame boundary or + * a CSI error received with FE packet from NVCSI. * - * See @ref err_data "err_data" with the VI event payload. - * - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + * Refer to @ref notify_bits for error details. */ #define CAPTURE_STATUS_CSIMUX_FRAME MK_U32(2) -/** CSIMUX stream error. + +/** + * CSIMUX stream error. Maps to VI CSIMUX_STREAM notify event. * - * Maps to VI CSIMUX_STREAM event. + * An error was detected in the VI CSIMUX stream interface. * - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + * + * Refer to @ref notify_bits for error details. */ #define CAPTURE_STATUS_CSIMUX_STREAM MK_U32(3) -/** Data-specific fault in a channel. - * Maps to VI CHANSEL_FAULT event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Unused. @deprecated + * + * CHANSEL_FAULT errors are reported with @ref + * CAPTURE_STATUS_FALCON_ERROR. */ #define CAPTURE_STATUS_CHANSEL_FAULT MK_U32(4) -/** Data-specific fault in a channel. - * FE packet was force inserted. Maps to VI CHANSEL_FAULT_FE event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Unused. @deprecated + * + * CHANSEL_FAULT_FE errors are reported with @ref + * CAPTURE_STATUS_FALCON_ERROR. */ #define CAPTURE_STATUS_CHANSEL_FAULT_FE MK_U32(5) -/** SOF matches a channel that is already in a frame. - * Maps to VI CHANSEL_COLLISION event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Channel collision error. Maps to VI CHANSEL_COLLISION + * notify event. + * + * A received start-of-frame packet matches a VI channel that + * is already receiving a frame. This is typically caused by + * a mistake in programming the + * (@ref capture_descriptor::match "channel match rules") + * so that they match more than one sensor stream. + * + * This error sets @ref CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_COLLISION + * in @ref notify_bits. */ #define CAPTURE_STATUS_CHANSEL_COLLISION MK_U32(6) -/** Frame End appears from NVCSI before the normal number of pixels. - * Maps to VI CHANSEL_SHORT_FRAME event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Unused. @deprecated. + * + * CHANSEL_SHORT_FRAME errors are reported with @ref + * CAPTURE_STATUS_FALCON_ERROR. */ #define CAPTURE_STATUS_CHANSEL_SHORT_FRAME MK_U32(7) -/** Single surface packer has overflowed. - * Maps to VI ATOMP_PACKER_OVERFLOW event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Single ATOMP surface packer has overflowed. Maps to VI + * ATOMP_PACKER_OVERFLOW notify event. This is an internal + * error that should not happen in normal use. + * + * This error sets @ref CAPTURE_STATUS_NOTIFY_BIT_ATOMP_PACKER_OVERFLOW + * in @ref notify_bits. */ #define CAPTURE_STATUS_ATOMP_PACKER_OVERFLOW MK_U32(8) -/** Frame interrupted mid-frame. - * Maps to VI ATOMP_FRAME_TRUNCATED event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Frame truncated writing to system memory. Maps to VI + * ATOMP_FRAME_TRUNCATED event. This error typically indicates + * memory back-pressure due to insufficient memory bandwidth + * or an excessive memory access latency. + * + * This error sets @ref CAPTURE_STATUS_NOTIFY_BIT_ATOMP_FRAME_TRUNCATED + * in @ref notify_bits. */ #define CAPTURE_STATUS_ATOMP_FRAME_TRUNCATED MK_U32(9) -/** Frame interrupted without writing any data out. - * Maps to VI ATOMP_FRAME_TOSSED event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Frame discarded writing to system memory. Maps to VI + * ATOMP_FRAME_TOSSED event. This error typically indicates + * memory back-pressure due to insufficient memory bandwidth + * or an excessive memory access latency. + * + * This error sets @ref CAPTURE_STATUS_NOTIFY_BIT_ATOMP_FRAME_TOSSED + * in @ref notify_bits. */ #define CAPTURE_STATUS_ATOMP_FRAME_TOSSED MK_U32(10) -/** ISP buffer FIFO overflowed. - * Maps to VI CSIMUX_FRAME event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + +/** + * Unused. @deprecated + * + * ISPBUF FIFO interfaces are not used. */ #define CAPTURE_STATUS_ISPBUF_FIFO_OVERFLOW MK_U32(11) -/** Capture status out of sync. - * Value of @ref err_data "err_data" is undefined. + +/** + * Capture status out of sync. A stale error from a past frame was + * detected and logged. An unknown number of frames may have been lost + * due to, for example, a longer break in the sensor connection. */ #define CAPTURE_STATUS_SYNC_FAILURE MK_U32(12) -/** VI notifier backend down. - * Value of @ref err_data "err_data" is undefined. + +/** + * Unused. @deprecated */ #define CAPTURE_STATUS_NOTIFIER_BACKEND_DOWN MK_U32(13) -/** Falcon error. - * Value of @ref err_data "err_data" is defined in - " VI Microcode IAS v0.5.13, section 2.3.3". + +/** + * Capture error reported by VI falcon. See @ref notify_bits + * for detailed @ref ViFalconErrorBits "errors". */ #define CAPTURE_STATUS_FALCON_ERROR MK_U32(14) -/** Data does not match any active channel. + +/** + * Incoming frame does not match any active channel. * Maps to VI CHANSEL_NOMATCH event. - * See @ref err_data "err_data" with the VI event payload. - * Please refer to T19x Video Input (“VI5”) Application Note: - * Programming NOTIFY v0.0.0" for details. + * + * This typically means that the client has either not configured + * a capture channel for the sensor or has been unable to supply + * capture requests quickly enough, causing a request queue + * underflow. Each CHANSEL_NOMATCH error implies that a frame + * has been dropped. */ #define CAPTURE_STATUS_CHANSEL_NOMATCH MK_U32(15) /** - * Invalid VI capture settings. - * Value of @ref err_data "err_data" is undefined. + * Invalid VI capture settings. Parameter validation error from + * VI driver. */ #define CAPTURE_STATUS_INVALID_CAP_SETTINGS MK_U32(16) + /** @} */ - /** Start of Frame (SOF) timestamp (ns) */ + /** TSC based start-of-frame (SOF) timestamp (ns) */ uint64_t sof_timestamp; - /** End of Frame (EOF) timestamp (ns) */ + + /** TSC based end-of-frame (EOF) timestamp (ns) */ uint64_t eof_timestamp; + /** - * Extended error data. The content depends on the value in @ref status. - * See @ref CaptureStatusCodes for references. + * @deprecated + * + * See @ref notify_bits for error details. */ uint32_t err_data; @@ -1128,156 +1740,237 @@ struct capture_status { uint32_t flags; /** - * VI error notifications logged in capture channel since previous capture. - * See @ref ViNotifyErrorTag "VI notify error bitmask" - * - * Please refer to "[1] VI Microcode IAS v0.5.13" and - * "[2] T19x Video Input (“VI5”) Application Note: Programming NOTIFY v0.0.0" - * for more information on the meaning of individual error bits. + * @ref ViNotifyErrorTag "VI errors" logged in capture channel since + * previous capture. */ uint64_t notify_bits; /** - * @defgroup ViNotifyErrorTag Extended VI error bits for the @ref notify_bits field + * @defgroup ViNotifyErrorTag VI errors + * + * VI error bits for the @ref notify_bits field. */ /** @{ */ - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESEVED_0 MK_BIT64(1) - /** Frame start fault */ + + /** + * Frame start fault. A FS packet was received while already + * in frame indicating that a FE packet was lost. + * + * This is not a frame corrupting error, unless pixel data was + * lost as well, and may also be present in the capture status + * of a successful request. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_FS_FAULT MK_BIT64(2) - /** Frame end forced by CSIMUX stream reset or stream timeout */ + + /** FE forced by CSIMUX stream reset or stream timeout. */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_FORCE_FE_FAULT MK_BIT64(3) - /** Frame ID fault in frame end packet */ + + /** Frame ID of the FE packet does not match the Frame ID of the FS packet. */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_FE_FRAME_ID_FAULT MK_BIT64(4) - /** Pixel enable fault in pixel packet header */ + + /** An illegal pixel enable encoding was detected in a long packet. */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_PXL_ENABLE_FAULT MK_BIT64(5) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_1 MK_BIT64(6) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_2 MK_BIT64(7) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_3 MK_BIT64(8) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_4 MK_BIT64(9) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_5 MK_BIT64(10) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_6 MK_BIT64(11) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_7 MK_BIT64(12) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_8 MK_BIT64(13) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_RESERVED_9 MK_BIT64(14) - - /** CSI pixel parser finite state machine timeout */ + /** + * CSI pixel parser finite state machine timeout. + * A line of data was not received in time + * (see @ref CAPTURE_CSI_STREAM_SET_PARAM_REQ_MSG::watchdog_config). + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_CSI_FAULT_PPFSM_TIMEOUT MK_BIT64(15) - /** CSI single bit error corrected in packet header by ECC */ + + /** + * A single bit error was corrected by ECC in the DPHY CSI + * packet header. + * + * This is not a frame corrupting error and may also be present + * in the capture status of a successful request. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_CSI_FAULT_PH_ECC_SINGLE_BIT_ERR MK_BIT64(16) - /** CSI CRC Error in payload data */ + + /** + * A CRC mismatch was detected in CSI packet payload data. + * The payload is corrupted. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_CSI_FAULT_PD_CRC_ERR MK_BIT64(17) - /** CSI payload data word count short error */ + + /** + * CSI payload data word count short error. The received data line + * was incomplete. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_CSI_FAULT_PD_WC_SHORT_ERR MK_BIT64(18) - /** CSI packet header single CRC error */ + + /** + * One out of two CRCs for the CPHY CSI packet header mismatches. + * The CRC value itself is corrupted. This error does not cause + * frame corruption. + * + * This is not a frame corrupting error and may also be present + * in the capture status of a successful request. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_CSI_FAULT_PH_SINGLE_CRC_ERR MK_BIT64(19) - /** CSI embedded data line CRC error */ + + /** + * CSI embedded data line CRC error. The sensor embedded data + * is corrupted. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_FRAME_CSI_FAULT_EMBEDDED_LINE_CRC_ERR MK_BIT64(20) /** * Spurious data detected between valid frames or before first frame. - * This can be a badly corrupted frame or some random bits. - * This error doesn't have an effect on the captured frame. + * This can be a badly corrupted frame or some random bits. This error + * doesn't have an effect on the next captured frame. Spurious data + * before the first captured frame is often caused by receiving the + * tail part of a partial frame in the beginning. Spurious errors + * detected before first full frame will be suppressed. + * + * This is not a frame corrupting error and may also be present + * in the capture status of a subsequent successful request. */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_STREAM_SPURIOUS_DATA MK_BIT64(21) - /** Stream FIFO overflow. This error is unrecoverable. */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_STREAM_FIFO_OVERFLOW MK_BIT64(22) - /** Stream loss of frame error. This error is unrecoverable. */ - #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_STREAM_FIFO_LOF MK_BIT64(23) + /** - * Illegal data packet was encountered and dropped by CSIMUX. - * This error may have no effect on capture result or trigger - * other errors if frame got corrupted. + * Stream FIFO overflow. This error is unrecoverable. The FIFO + * overflow error usually implies incorrect configuration of + * VI and ISP core clock rates. This error should not happen + * during normal use. + */ + #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_STREAM_FIFO_OVERFLOW MK_BIT64(22) + + /** + * Stream loss of frame error. A FS packet was lost due a stream + * FIFO overflow. This error is unrecoverable. The FIFO + * overflow error usually implies incorrect configuration of + * VI and ISP core clock rates. This error should not happen + * during normal use. + */ + #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_STREAM_FIFO_LOF MK_BIT64(23) + + /** + * An illegal data packet was encountered and dropped by CSIMUX. + * This error may have no effect on capture result or may trigger + * other errors if the frame got corrupted. */ #define CAPTURE_STATUS_NOTIFY_BIT_CSIMUX_STREAM_FIFO_BADPKT MK_BIT64(24) /** - * Timeout from frame descriptor activation to frame start. - * See also frame_start_timeout in struct capture_descriptor + * Start of frame capture timed out. The timeout is measured + * from VI falcon task activation to frame start (see + * @ref capture_descriptor::frame_start_timeout). */ #define CAPTURE_STATUS_NOTIFY_BIT_FRAME_START_TIMEOUT MK_BIT64(25) /** - * Timeout from frame start to frame completion. - * See also frame_completion_timeout in struct capture_descriptor + * Frame capture timed out. The timeout is measured from frame start + * to frame completion (see @ref capture_descriptor::frame_timeout). */ #define CAPTURE_STATUS_NOTIFY_BIT_FRAME_COMPLETION_TIMEOUT MK_BIT64(26) - /** Missing line end packet in pixel data line */ + /** Missing line-end packet in pixel data line */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_PIXEL_MISSING_LE MK_BIT64(30) + /** Frame has too many lines */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_PIXEL_RUNAWAY MK_BIT64(31) - /** Pixel data received without line start packet */ + + /** Pixel data received without line-start packet */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_PIXEL_SPURIOUS MK_BIT64(32) - /** Pixel data line is too long */ + + /** Pixel line is too long */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_PIXEL_LONG_LINE MK_BIT64(33) - /** Pixel data line is too short */ + + /** Pixel line is too short */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_PIXEL_SHORT_LINE MK_BIT64(34) - /** Missing line end packet in embedded data line */ + + /** Missing line-end packet in embedded data line */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMBED_MISSING_LE MK_BIT64(35) + /** Frame has too many lines of embedded data */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMBED_RUNAWAY MK_BIT64(36) - /** Embedded data received without line start packet */ + + /** Embedded data received without line-start packet */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMBED_SPURIOUS MK_BIT64(37) + /** Embedded data line is too long */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMBED_LONG_LINE MK_BIT64(38) - /** Embedded data received when not expected */ - #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMBED_INFRINGE MK_BIT64(39) - /** Invalid pixel data type in pixel packet or line start packet */ - #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_DTYPE_MISMATCH MK_BIT64(40) - /** Reserved */ - #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_RESERVED_0 MK_BIT64(41) - /** Frame to short - too few pixel data lines */ + /** + * Embedded data received when not expected. Sensor has been + * programmed to send embedded data but the capture has + * not been programmed to expect it. + */ + #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMBED_INFRINGE MK_BIT64(39) + + /** Invalid pixel datatype in pixel packet or line-start packet */ + #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_DTYPE_MISMATCH MK_BIT64(40) + + /** Short frame: frame has too few pixel lines */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_PIX_SHORT MK_BIT64(42) - /** Frame to short - too few embedded data lines */ + /** Short frame: frame has too few embedded data lines */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_EMB_SHORT MK_BIT64(43) - /** VI hardware failure detected by Permanent Fault Software Diagnostics (PFSD) */ + /** + * VI hardware failure detected by + * (@ref CAPTURE_CHANNEL_FLAG_ENABLE_VI_PFSD). + */ #define CAPTURE_STATUS_NOTIFY_BIT_PFSD_FAULT MK_BIT64(44) - /** Frame end forced by channel reset */ + /** + * Frame was truncated due to a frame timeout, or + * a channel reset or channel release operation. + */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_FAULT_FE MK_BIT64(45) /** - * Incoming frame not matched by any VI channel. - * This error is usually caused by not having a pending - * capture request ready to catch the incoming frame. - * The frame will be dropped. + * Incoming frame was not matched by any VI channel.This error is + * usually caused by not having a pending capture request ready to + * catch the incoming frame. The frame will be dropped. This often + * indicates a request starvation condition that may be caused by + * performance issues on the client side. + * + * This is not a frame corrupting error and may also be present + * in the capture status of a subsequent successful request. */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_NO_MATCH MK_BIT64(46) /** * More than one VI channel match the same incoming frame. - * Two or more channels have been configured for the same - * sensor. Only one of the channels will capture the frame. + * Two or more channels have been configured to catch frames + * from the same source. Only one of the channels will capture + * the frame and the other one will report this error for the + * conflicting capture request. */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_COLLISION MK_BIT64(47) - /** Channel reconfigured while in frame */ + /** + * Channel reconfigured while in frame. This is not an error and + * this status should not been seen in practice. @deprecated + */ #define CAPTURE_STATUS_NOTIFY_BIT_CHANSEL_LOAD_FRAMED MK_BIT64(48) - /** Internal overflow in ATOMP packer. Should not happen. */ + /** + * Internal overflow in ATOMP packer. This is Internal + * hardware error that should not occur in normal use. + */ #define CAPTURE_STATUS_NOTIFY_BIT_ATOMP_PACKER_OVERFLOW MK_BIT64(49) - /** Frame truncated while writing to system memory. Indicates memory back-pressure. */ + /** + * Frame truncated while writing to system memory. + * Indicates memory back-pressure due to insufficient memory + * bandwidth or an excessive memory access latency. + */ #define CAPTURE_STATUS_NOTIFY_BIT_ATOMP_FRAME_TRUNCATED MK_BIT64(50) - /** Frame dropped while writing to system memory. Indicates memory back-pressure. */ + /** + * Frame dropped while writing to system memory. + * Indicates memory back-pressure due to insufficient memory + * bandwidth or an excessive memory access latency. + */ #define CAPTURE_STATUS_NOTIFY_BIT_ATOMP_FRAME_TOSSED MK_BIT64(51) - /** Non-classified error */ + /** Unclassified error. Should not happen. */ + #define CAPTURE_STATUS_NOTIFY_BIT_UNCLASSIFIED_ERROR MK_BIT64(63) + + /** Unclassified error. Should not happen. @deprecated */ #define CAPTURE_STATUS_NOTIFY_BIT_NON_CLASSIFIED_0 MK_BIT64(63) /** @} */ @@ -1371,65 +2064,95 @@ struct vi_syncgen_config { uint32_t pad2__; } CAPTURE_IVC_ALIGN; - /** * @brief VI PFSD Configuration. * - * PDAF replacement function is used in PFSD mode. Pixels within ROI are replaced - * by test pattern, and output pixels from the ROI are compared against expected - * values. + * The PDAF replacement function is used in PFSD mode. Pixels within a + * designated region are replaced by a test pattern, and output pixels + * from the region are compared against expected values after a capture. */ struct vi_pfsd_config { /** - * @brief Area in which the pixels are replaced with test pattern - * - * Note that all coordinates are inclusive. + * Region within which the pixels are replaced with a test pattern. */ struct replace_roi_rec { - /** left pixel column of the replacement ROI */ + /** + * left pixel column of the replacement region [0, UINT16_MAX]. + */ uint16_t left; - /** right pixel column of the replacement ROI (inclusive) */ - uint16_t right; - /** top pixel row of the replacement ROI */ - uint16_t top; - /** bottom pixel row of the replacement ROI (inclusive) */ - uint16_t bottom; - } replace_roi; - /** test pattern used to replace pixels within the ROI */ + /** + * right pixel column of the replacement region (inclusive) + * [0, UINT16_MAX]. + */ + uint16_t right; + + /** top pixel row of the replacement region [0, UINT16_MAX]. */ + uint16_t top; + + /** + * bottom pixel row of the replacement region (inclusive) + * [0, UINT16_MAX]. + */ + uint16_t bottom; + + } replace_roi; /**< Pixel replacement region. */ + + /** + * The test pattern used to replace pixels within the region + * [0, 0xFFFFF]. The value is defined in the nvcsi2vi pixel + * bus format. The actual value range depends on the + * @ref NvCsiDataType "CSI datatype". + */ uint32_t replace_value; /** - * Count of items in the @ref expected array. - * If zero, PFSD will not be performed for this frame + * Count of items in the @ref expected array + * [0, VI_NUM_VI_PFSD_SURFACES]. If zero, PFSD + * will not be performed for this frame */ uint32_t expected_count; /** - * Array of area definitions in output surfaces that shall be verified. - * For YUV422 semi-planar, [0] is Y surface and [1] is UV surface. + * Array of area definitions for output surfaces that will be + * verified. For YUV422 semi-planar, [0] is the Y surface and + * [1] ist the UV surface. */ struct { - /** Byte offset for the roi from beginning of the surface */ + /** + * Byte offset for the roi from beginning of the surface + * [0, UINT32_MAX]. + */ uint32_t offset; - /** Number of bytes that need to be read from the output surface */ + + /** + * Number of bytes that need to be read from the output + * surface [0, 255]. + */ uint32_t len; - /** Expected value. The 4 byte pattern is repeated until @ref len - * bytes have been compared + + /** + * Sequence of expected values [0, UINT8_MAX]. The 4 byte + * pattern is repeated until @ref len bytes have been + * compared. */ uint8_t value[4]; - } expected[VI_NUM_VI_PFSD_SURFACES]; + } expected[VI_NUM_VI_PFSD_SURFACES]; /**< Expected PFSD values. */ } CAPTURE_IVC_ALIGN; /** - * @defgroup CaptureFrameFlags - * Capture frame specific flags + * @defgroup CaptureRequestFlags Capture request flags */ /** @{ */ -/** Enables capture status reporting for the channel */ + +/** Enable capture status and error reporting for the channel. */ #define CAPTURE_FLAG_STATUS_REPORT_ENABLE MK_BIT32(0) -/** Enables error reporting for the channel */ + +/** + * Enable error reporting only for the channel. No effect if + * @ref CAPTURE_FLAG_STATUS_REPORT_ENABLE is set. + */ #define CAPTURE_FLAG_ERROR_REPORT_ENABLE MK_BIT32(1) /** @} */ @@ -1438,10 +2161,11 @@ struct vi_pfsd_config { */ struct memoryinfo_surface { /** - * Surface iova address. Must be a multiple of 16. + * Surface IOVA address. Must be a multiple of 16. * Must be non-zero if @ref size > 0. */ uint64_t base_address; + /** Surface size. Must be a multiple of 16. */ uint64_t size; }; @@ -1455,14 +2179,25 @@ struct memoryinfo_surface { * application. */ struct capture_descriptor_memoryinfo { + /** VI output surfaces */ struct memoryinfo_surface surface[VI_NUM_ATOMP_SURFACES]; - /** Base address of engine status surface */ + + /** + * Base IOVA of engine status surface. Must be a multiple of 16. + * Must be non-zero if @ref engine_status_surface_size > 0. + */ uint64_t engine_status_surface_base_address; - /** Size of engine status surface */ + + /** + * Size of engine status surface. + * Must be >= @ref NV_ENGINE_STATUS_SURFACE_SIZE. + */ uint64_t engine_status_surface_size; + /** Memory surface for watermark ring buffer written by VI FW */ struct memoryinfo_surface watermark_surface; - /** pad for alignment */ + + /** Reserved */ uint32_t reserved32[8]; } CAPTURE_DESCRIPTOR_ALIGN; @@ -1470,13 +2205,22 @@ struct capture_descriptor_memoryinfo { * @brief VI frame capture context. */ struct capture_descriptor { - /** VI frame sequence number*/ + /** Capture request sequence number [0, UINT32_MAX]. */ uint32_t sequence; - /** See @ref CaptureFrameFlags "Capture frame specific flags" */ + + /** See @ref CaptureRequestFlags "capture request flags". */ uint32_t capture_flags; - /** Task descriptor frame start timeout in milliseconds */ + + /** + * Task descriptor frame start timeout in milliseconds + * [0, UINT16_MAX]. + */ uint16_t frame_start_timeout; - /** Task descriptor frame complete timeout in milliseconds */ + + /** + * Task descriptor frame completion timeout in milliseconds + * [0, UINT16_MAX]. + */ uint16_t frame_completion_timeout; #define CAPTURE_PREFENCE_ARRAY_SIZE 2 @@ -1486,16 +2230,29 @@ struct capture_descriptor { /** @deprecated */ struct syncpoint_info prefence[CAPTURE_PREFENCE_ARRAY_SIZE] CAMRTC_DEPRECATED; - /** VI Channel configuration */ + /** VI Channel configuration. */ struct vi_channel_config ch_cfg; - /** VI PFSD Configuration */ + /** + * VI PFSD Configuration. + * The @ref CAPTURE_CHANNEL_FLAG_ENABLE_VI_PFSD is set in + * @ref channel_flags for this setting to take effect. + */ struct vi_pfsd_config pfsd_cfg; - /** Engine result record – written by Falcon */ + /** + * Engine status surface for downstream synchronization. + * Engine status is written by VI when a frame is complete. + * + * This is only valid in the UMD-KMD interface. + * The content is undefined in the RCE FW interface. + */ struct engine_status_surface engine_status; - /** Capture result record – written by RCE */ + /** + * Capture status record. Written by RCE when the capture + * request is completed. + */ struct capture_status status; /** Unique ID for the output buffer used for watermarking */