From 1eb3b03e5fee5704fe3dcb98f7daf55a7c790b92 Mon Sep 17 00:00:00 2001 From: Mika Liljeberg Date: Mon, 11 Sep 2023 11:15:35 +0300 Subject: [PATCH] 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 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 Reviewed-by: Matti Ryttylainen Reviewed-by: Viktor Horsmanheimo --- include/soc/tegra/camrtc-capture-messages.h | 470 ++++++++++++++++---- include/soc/tegra/camrtc-capture.h | 292 ++++++++---- 2 files changed, 588 insertions(+), 174 deletions(-) diff --git a/include/soc/tegra/camrtc-capture-messages.h b/include/soc/tegra/camrtc-capture-messages.h index c8891c7e..6e21fd43 100644 --- a/include/soc/tegra/camrtc-capture-messages.h +++ b/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" = unique ID + * + * @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) /** @} */ -/** - * @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. - */ +/** 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; -/** - * @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. - */ +/** Message data for @ref CAPTURE_CHANNEL_SETUP_RESP message */ 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) /** @} */ -/** - * @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. - */ +/** Message data for @ref CAPTURE_CHANNEL_RESET_REQ message */ 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; -/** - * @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. - */ +/** Message data for @ref CAPTURE_CHANNEL_RESET_RESP message */ 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; -/** - * @brief Release a VI capture channel and all the associated resources. - * - * Halt the associated VI channel and release the channel context. - */ +/** Message data for @ref CAPTURE_CHANNEL_RELEASE_REQ message */ 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; -/** - * @brief Capture channel release response message. - * - * The release is acknowledged after the channel cleanup is complete - * and all resources have been freed on RCE. - */ +/** Message data for @ref CAPTURE_CHANNEL_RELEASE_RESP message */ 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" = unique ID + * + * @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 * @{ */ -/** - * @brief Set CHANSEL error mask from HSM reporting message - */ +/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_REQ 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; -/** - * @brief Acknowledge CHANEL error mask request - */ +/** Message data for @ref CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP message */ 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; diff --git a/include/soc/tegra/camrtc-capture.h b/include/soc/tegra/camrtc-capture.h index 0a7e1fab..e1c99579 100644 --- a/include/soc/tegra/camrtc-capture.h +++ b/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 - * Bitmask for masking "Uncorrected errors" and "Errors with threshold". + * @defgroup CaptureChannelErrMask VI error numbers */ /**@{*/ /** 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. - * - * 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). + * channel until it is released with @ref CAPTURE_CHANNEL_RELEASE_REQ. * * 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. - * This allows the client to enforce allocation of HW VI channel in particular range for its own - * purpose. + * A bitmask indicating which VI hardware channels to consider for + * allocation [0, 0xFFFFFFFFF]. LSB is VI channel 0. * - * 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 - * 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. + * This control is provided for special use cases and for testing. */ uint64_t vi_channel_mask; /** - * A bitmask indicating which VI2 channels to consider for allocation. LSB is VI2 channel 0. - * This allows the client to enforce allocation of HW VI channel in particular range for its own - * purpose. + * A bitmask indicating which VI2 hardware channels to consider for + * allocation [0, 0xFFFFFFFFF]. LSB is VI2 channel 0. * - * 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 - * 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. + * This control is provided for special use cases and for testing. */ 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. - * The size of the buffer is queue_depth * request_size + * Base address of the @ref capture_descriptor ring buffer. + * 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 - * information. - * The size of the buffer is queue_depth * request_memoryinfo_size + * Base address of a memory mapped ring buffer containing capture + * requests buffer information. The size of the buffer is @ref + * 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. - * Determines the size of the ring buffer. + * Maximum number of capture requests in the requests queue [1, 240]. + * 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 - * active channels. For subsequent channels we check that - * the channel configuration matches with the active - * configuration. - * - * Number of Grid of Semaphores (GOS) tables + * Number of elements in @ref vi_gos_tables array + * [0, @ref VI_NUM_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, - * otherwise default HSM reporting policy is used. - * - * 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. + * GoS table configuration, if present, must be the same on all + * active channels. The IOVA addresses must be a multiple of 256. */ + iova_t vi_gos_tables[VI_NUM_GOS_TABLES]; /** - * Error mask for "uncorrected" errors. See @ref CaptureChannelErrMask "Channel Error bitmask". - * There map to the uncorrected error line in HSM + * Capture progress syncpoint information. The progress syncpoint + * 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 << error number) 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". - * See @ref CaptureChannelErrMask "Channel Error bitmask". - * These map to the corrected error line in HSM */ + * This error mask applies only to errors that are masked in @ref + * error_mask_uncorrectable. 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 << error number) 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. - * Bit definitions are same as in CAPTURE_STATUS_NOTIFY_BIT_* macros. + * 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). + * + * 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 - * Error bit definitions for the @ref notify_bits field + * @defgroup ViNotifyErrorTag Extended VI error bits 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 << error number) 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 << error number) 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) /**@}*/