diff --git a/include/soc/tegra/camrtc-capture-messages.h b/include/soc/tegra/camrtc-capture-messages.h index 6e21fd43..ec8debef 100644 --- a/include/soc/tegra/camrtc-capture-messages.h +++ b/include/soc/tegra/camrtc-capture-messages.h @@ -246,11 +246,135 @@ struct CAPTURE_MSG_HEADER { * @defgroup IspCapCtrlMsgType Message types for ISP capture-control IVC channel messages. * @{ */ + +/** + * @brief ISP capture channel setup request. + * + * This is a @ref CapCtrlMsgType "capture control message" to + * allocate an ISP 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_ISP_SETUP_REQ + * - @ref CAPTURE_MSG_HEADER::transaction "transaction" = unique ID + * + * @par Payload + * - @ref CAPTURE_CHANNEL_ISP_SETUP_REQ_MSG + * + * @par Response + * - @ref CAPTURE_CHANNEL_ISP_SETUP_RESP + */ #define CAPTURE_CHANNEL_ISP_SETUP_REQ MK_U32(0x20) + +/** + * @brief ISP capture channel setup response. + * + * This is a @ref CapCtrlMsgType "capture control message" sent as a + * response to a @ref CAPTURE_CHANNEL_ISP_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_ISP_SETUP_RESP + * - @ref CAPTURE_MSG_HEADER::transaction "transaction" = + * @ref CAPTURE_CHANNEL_ISP_SETUP_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::transaction "transaction" + * + * @par Payload + * - @ref CAPTURE_CHANNEL_SETUP_ISP_RESP_MSG + */ #define CAPTURE_CHANNEL_ISP_SETUP_RESP MK_U32(0x21) + +/** + * @brief ISP capture channel reset request. + * + * This is a @ref CapCtrlMsgType "capture control message" to + * reset an ISP capture channel. The client must also send a @ref + * CAPTURE_ISP_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_ISP_RESET_REQ message, + * it will cancel all requests in the channel queue upto the @ref + * CAPTURE_ISP_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 An ISP capture channel has been set up with + * @ref CAPTURE_CHANNEL_ISP_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_ISP_RESET_REQ + * - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" = + * @ref CAPTURE_CHANNEL_ISP_SETUP_RESP_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id" + * + * @par Payload + * - @ref CAPTURE_CHANNEL_ISP_RESET_REQ_MSG + * + * @par Response + * - @ref CAPTURE_CHANNEL_ISP_RESET_RESP + */ #define CAPTURE_CHANNEL_ISP_RESET_REQ MK_U32(0x22) + +/** + * @brief ISP capture channel reset response. + * + * This is a @ref CapCtrlMsgType "capture control message" sent as a + * response to a @ref CAPTURE_CHANNEL_ISP_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_ISP_RESET_RESP + * - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" = + * @ref CAPTURE_CHANNEL_ISP_RESET_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id" + * + * @par Payload + * - @ref CAPTURE_CHANNEL_ISP_RESET_RESP_MSG + */ #define CAPTURE_CHANNEL_ISP_RESET_RESP MK_U32(0x23) + +/** + * @brief ISP capture channel release request. + * + * This is a @ref CapCtrlMsgType "capture control message" to + * release an ISP capture channel. Cancels all pending requests. + * + * @pre An ISP capture channel has been set up with + * @ref CAPTURE_CHANNEL_ISP_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_ISP_RELEASE_REQ + * - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" = + * @ref CAPTURE_CHANNEL_ISP_SETUP_RESP_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id" + * + * @par Payload + * - @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG + * + * @par Response + * - @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP + */ #define CAPTURE_CHANNEL_ISP_RELEASE_REQ MK_U32(0x24) + +/** + * @brief ISP capture channel release response. + * + * This is a @ref CapCtrlMsgType "capture control message" sent as a + * response to a @ref CAPTURE_CHANNEL_ISP_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_ISP_RELEASE_RESP + * - @ref CAPTURE_MSG_HEADER::channel_id "channel_id" = + * @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG@b::@ref CAPTURE_MSG_HEADER "header"@b::@ref CAPTURE_MSG_HEADER::channel_id "channel_id" + * + * @par Payload + * - @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP_MSG + */ #define CAPTURE_CHANNEL_ISP_RELEASE_RESP MK_U32(0x25) /** @} */ @@ -919,31 +1043,17 @@ struct CAPTURE_HSM_CHANSEL_ERROR_MASK_RESP_MSG { } CAPTURE_IVC_ALIGN; /** @} */ -/** - * @brief Set up RCE side resources for ISP capture pipe-line. - * - * The client shall use the transaction id field in the - * standard message header to associate request and response. - */ +/** Message data for @ref CAPTURE_CHANNEL_ISP_SETUP_REQ message */ struct CAPTURE_CHANNEL_ISP_SETUP_REQ_MSG { - /** ISP process channel configuration. */ + /** ISP channel configuration. */ struct capture_channel_isp_config channel_config; } CAPTURE_IVC_ALIGN; -/** - * @brief Acknowledge isp capture channel setup request. - * - * 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_ISP_SETUP_RESP message */ struct CAPTURE_CHANNEL_ISP_SETUP_RESP_MSG { - /** ISP process channel setup request status. See @ref CapErrorCodes "Return values". */ + /** Request result code. See @ref CapErrorCodes "result codes". */ capture_result result; - /** ISP process channel identifier for the new channel. */ + /** ISP channel identifier for the new channel [0, UINT32_MAX]. */ uint32_t channel_id; } CAPTURE_IVC_ALIGN; @@ -956,13 +1066,7 @@ typedef struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_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. - */ +/** Message data for @ref CAPTURE_CHANNEL_ISP_RESET_REQ message */ struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG { /** Unused */ uint32_t reset_flags; @@ -970,40 +1074,27 @@ struct CAPTURE_CHANNEL_ISP_RESET_REQ_MSG { 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. - */ +/** Message data for @ref CAPTURE_CHANNEL_ISP_RESET_RESP message */ struct CAPTURE_CHANNEL_ISP_RESET_RESP_MSG { - /** Reset 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; -/** - * @brief Release ISP channel and all the associated resources. - * - * Halt the associated ISP channel and release the channel context. - */ +/** Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_REQ message */ struct CAPTURE_CHANNEL_ISP_RELEASE_REQ_MSG { - /** Reset flags. Currently not used in release request. */ + /** Unused */ uint32_t reset_flags; + /** Reserved */ 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. - */ +/** Message data for @ref CAPTURE_CHANNEL_ISP_RELEASE_RESP message */ struct CAPTURE_CHANNEL_ISP_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; diff --git a/include/soc/tegra/camrtc-capture.h b/include/soc/tegra/camrtc-capture.h index e1c99579..4771c3ab 100644 --- a/include/soc/tegra/camrtc-capture.h +++ b/include/soc/tegra/camrtc-capture.h @@ -1427,9 +1427,12 @@ struct vi_pfsd_config { * @brief Memory surface specs passed from KMD to RCE */ struct memoryinfo_surface { - /** Surface iova address */ + /** + * Surface iova address. Must be a multiple of 16. + * Must be non-zero if @ref size > 0. + */ uint64_t base_address; - /** Surface size */ + /** Surface size. Must be a multiple of 16. */ uint64_t size; }; @@ -2381,80 +2384,130 @@ struct nvcsi_tpg_rate_config { * @defgroup ISPProcessChannelFlags ISP process channel specific flags */ /**@{*/ -/** Channel reset on error */ -#define CAPTURE_ISP_CHANNEL_FLAG_RESET_ON_ERROR MK_U32(0x0001) +/** Channel reset on error. Not implemented. */ +#define CAPTURE_ISP_CHANNEL_FLAG_RESET_ON_ERROR MK_U32(0x0001) /**@}*/ /** * @brief Describes RTCPU side resources for a ISP capture pipe-line. - * - * Following structure defines ISP channel specific configuration; */ struct capture_channel_isp_config { - /** Unique ISP process channel ID */ + /** Unused. @deprecated */ uint8_t channel_id; + /** Reserved */ uint8_t pad_chan__[3]; - /** See ISP process channel specific @ref ISPProcessChannelFlags "flags" */ + + /** See ISP process channel specific @ref ISPProcessChannelFlags "flags". */ uint32_t channel_flags; + /** - * Base address of ISP capture descriptor ring buffer. - * The size of the buffer is request_queue_depth * request_size + * Base address of the @ref isp_capture_descriptor ring buffer. + * The size of the buffer is @ref request_queue_depth * + * @ref request_size. The value must be non-zero and a multiple + * of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES. */ iova_t requests; - /** Number of ISP process requests in the ring buffer */ + + /** + * Maximum number of ISP requests in the queue [1, 240]. Determines the + * size of the @ref isp_capture_descriptor ring buffer (@ref requests). + */ uint32_t request_queue_depth; - /** Size of each ISP process request (@ref isp_capture_descriptor) */ + + /** + * Size of the buffer reserved for each ISP capture descriptor. + * Must be >= sizeof(@ref isp_capture_descriptor) and a multiple + * of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES. + */ uint32_t request_size; /** * Base address of ISP program descriptor ring buffer. - * The size of the buffer is program_queue_depth * program_size + * The size of the buffer is @ref program_queue_depth * + * @ref program_size. The value must be non-zero and a multiple + * of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES. */ iova_t programs; + /** - * Maximum number of ISP program requests in the program queue. - * Determines the size of the ISP program ring buffer. + * Maximum number of ISP program requests in the program queue [1, 32]. + * Determines the size of the ISP program ring buffer (@ref programs). */ uint32_t program_queue_depth; - /** Size of each ISP process request (@ref isp_program_descriptor) */ + + /** Size of each ISP process request (@ref isp_program_descriptor). */ uint32_t program_size; - /** ISP Process output buffer syncpoint info */ + + /** + * ISP progress syncpoint information. The progress syncpoint + * is incremented whenever a slice of pixel data has been written + * to memory and once more when the status of the ISP task 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; - /** Statistics buffer syncpoint info */ + + /** + * ISP statistics syncpoint information. The statistics syncpoint + * is incremented once for every set of statistics specifed in + * @ref isp_progam::stats_aidx_flag. The same stats syncpoint will + * keep incrementing for every consecutive ISP request. + * + * @ref syncpoint_info::threshold must be set to the initial + * value of the hardware syncpoint on channel setup. + **/ struct syncpoint_info stats_progress_sp; /** - * Base address of a memory mapped ring buffer containing ISP requests - * buffer information. - * The size of the buffer is queue_depth * request_memoryinfo_size + * Base address of a memory mapped ring buffer containing ISP request + * buffer memory information. The size of the buffer is @ref + * request_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; /** * Base address of a memory mapped ring buffer containing ISP program - * buffer information. + * push buffer memory surfaces. The size of the ring buffer is @ref + * program_queue_depth * @ref program_memoryinfo_size. The value must + * be non-zero and a multiple of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES. */ iova_t programs_memoryinfo; - /** Size of the memoryinfo buffer reserved for each capture request. */ + /** + * Size of the memoryinfo buffer reserved for each ISP request. + * Must be >= sizeof(@ref isp_capture_descriptor_memoryinfo) and + * a multiple of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES. + */ uint32_t request_memoryinfo_size; - /** Size of the memoryinfo buffer reserved for each program request. */ + /** + * Size of the memoryinfo buffer reserved for each ISP program push + * buffer surface. Must be >= sizeof(@ref memoryinfo_surface) and + * a multiple of @ref CAPTURE_DESCRIPTOR_ALIGN_BYTES. + */ uint32_t program_memoryinfo_size; /** ISP unit ID. See @ref ISPUnitIds "ISP Unit Identifiers". */ uint32_t isp_unit_id; #define HAVE_ISP_GOS_TABLES - /** Number of active ISP GOS tables in isp_gos_tables[] */ + /** + * Number of elements in @ref isp_gos_tables array + * [0, @ref ISP_NUM_GOS_TABLES]. + */ uint32_t num_isp_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. + * Array of IOVA pointers to ISP Grid-of-Semaphores (GoS) tables + * (non-safety). + * + * GoS table configuration, if present, must be the same on all + * active channels. The IOVA addresses must be a multiple of 256. */ iova_t isp_gos_tables[ISP_NUM_GOS_TABLES]; } CAPTURE_IVC_ALIGN;