1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _v4l2-isp: 4 5************************ 6Generic V4L2 ISP formats 7************************ 8 9Generic ISP formats are metadata formats that define a mechanism to pass ISP 10parameters and statistics between userspace and drivers in V4L2 buffers. They 11are designed to allow extending them in a backward-compatible way. 12 13ISP parameters 14============== 15 16The generic ISP configuration parameters format is realized by a defining a 17single C structure that contains a header, followed by a binary buffer where 18userspace programs a variable number of ISP configuration data block, one for 19each supported ISP feature. 20 21The :c:type:`v4l2_isp_buffer` structure defines the buffer header which is 22followed by a binary buffer of ISP configuration data. Userspace shall correctly 23populate the buffer header with the serialization format version and with the 24size (in bytes) of the binary data buffer where it will store the ISP blocks 25configuration. 26 27Each *ISP configuration block* is preceded by a header implemented by the 28:c:type:`v4l2_isp_block_header` structure, followed by the configuration 29parameters for that specific block, defined by the ISP driver specific data 30types. 31 32Userspace applications are responsible for correctly populating each block's 33header fields (type, flags and size) and the block-specific parameters. 34 35ISP parameters block enabling, disabling and configuration 36---------------------------------------------------------- 37 38When userspace wants to configure and enable an ISP block it shall fully 39populate the block configuration and set the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE 40bit in the block header's `flags` field. 41 42When userspace simply wants to disable an ISP block the 43V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bit should be set in block header's `flags` 44field. Drivers accept a configuration parameters block with no additional 45data after the header in this case. 46 47If the configuration of an already active ISP block has to be updated, 48userspace shall fully populate the ISP block parameters and omit setting the 49V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the 50header's `flags` field. 51 52Setting both the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and 53V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the flags field is not allowed and 54returns an error. 55 56Extension to the parameters format can be implemented by adding new blocks 57definition without invalidating the existing ones. 58 59ISP statistics 60============== 61 62The generic ISP statistics format is identical to the generic ISP configuration 63parameters format. It is realized by defining a C structure that contains a 64header, followed by binary buffer where the ISP driver copies a variable number 65of ISP statistics blocks. 66 67Extensible statistics buffers have :c:type:`v4l2_isp_buffer` header followed by 68a binary buffer of ISP statistics data. ISP drivers populate the buffer header 69with the serialization format version and with the size (in bytes) of the binary 70data buffer where ISP statistics data are serialized. Applications shall 71validate that the serialization format version matches the expected one and that 72the buffer size doesn't exceed the maximum size for a statistics buffer as 73declared by the driver's uAPI header. 74 75Each *ISP statistics block* is preceded by a header implemented by the 76:c:type:`v4l2_isp_block_header` structure, followed by the statistics data for 77that specific block. The driver might optionally report platform-specific flags 78associated with each statistics block. 79 80Applications inspect the statistics block type as reported in the header and 81validates the reported size matches the block's expected size before accessing 82the ISP statistics data. 83 84Extension to the statistics format can be implemented by adding new blocks 85definition without invalidating the existing ones. 86 87V4L2 ISP uAPI data types 88======================== 89 90.. kernel-doc:: include/uapi/linux/media/v4l2-isp.h 91