2.30.V4L2 generic ISP parameters and statistics support¶
2.30.1.Design rationale¶
ISP configuration parameters and statistics are processed and collected bydrivers and exchanged with userspace through data types that usuallyreflect the ISP peripheral registers layout.
Each ISP driver defines its own metadata output format for parameters anda metadata capture format for statistics. The buffer layout is realized by aset of C structures that reflects the registers layout. The number and typesof C structures is fixed by the format definition and becomes part of the Linuxkernel uAPI/uABI interface.
Because of the hard requirement of backward compatibility when extending theuser API/ABI interface, modifying an ISP driver capture or output metadataformat after it has been accepted by mainline is very hard if not impossible.
It generally happens, in fact, that after the first accepted revision of an ISPdriver the buffers layout need to be modified, either to support new hardwareblocks, to fix bugs or to support different revisions of the hardware.
Each of these situations would require defining a new metadata format, making itreally hard to maintain and extend drivers and requiring userspace to usethe correct format depending on the kernel revision in use.
2.30.2.V4L2 ISP configuration parameters¶
For these reasons, Video4Linux2 defines generic types for ISP configurationparameters and statistics. Drivers are still expected to define their ownformats for their metadata output and capture nodes, but the buffers layout canbe defined using the extensible and versioned types defined byinclude/uapi/linux/media/v4l2-isp.h.
Drivers are expected to provide the definitions of their supported ISP blocksand the expected maximum size of a buffer.
For driver developers a set of helper functions to assist them with validationof the buffer received from userspace is available indrivers/media/v4l2-core/v4l2-isp.c
2.30.3.V4L2 ISP support driver documentation¶
- v4l2_isp_params_buffer_size¶
v4l2_isp_params_buffer_size(max_params_size)
Calculate size of v4l2_isp_params_buffer
Parameters
max_params_sizeThe total size of the ISP configuration blocks
Description
Users of the v4l2 extensible parameters will have differing sized data arraysdepending on their specific parameter buffers. Drivers and userspace willneed to be able to calculate the appropriate size of thestructtoaccommodate all ISP configuration blocks provided by the platform.This macro provides a convenient tool for the calculation.
- intv4l2_isp_params_validate_buffer_size(structdevice*dev,structvb2_buffer*vb,size_tmax_size)¶
Validate a V4L2 ISP buffer sizes
Parameters
structdevice*devthe driver’s device pointer
structvb2_buffer*vbthe videobuf2 buffer
size_tmax_sizethe maximum allowed buffer size
Description
This function performs validation of the size of a V4L2 ISP parameters bufferbefore the driver can access the actual data buffer content.
After the sizes validation, drivers should copy the buffer content to akernel-only memory area to prevent userspace from modifying it,before completing validation usingv4l2_isp_params_validate_buffer().
Thevb buffer as received from the vb2 .buf_prepare() operation is checkedagainstmax_size and it’s validated to be large enough to accommodate atleast one ISP configuration block.
- structv4l2_isp_params_block_type_info¶
V4L2 ISP per-block-type info
Definition:
struct v4l2_isp_params_block_type_info { size_t size;};Members
sizethe block type expected size
Description
The v4l2_isp_params_block_type_info collects information of the ISPconfiguration block types for validation purposes. It currently only containsthe expected block type size.
Drivers shall prepare a list of block type info, indexed by block type, onefor each supported ISP block type and correctly populate them with theexpected block type size.
- intv4l2_isp_params_validate_buffer(structdevice*dev,structvb2_buffer*vb,conststructv4l2_isp_params_buffer*buffer,conststructv4l2_isp_params_block_type_info*type_info,size_tnum_block_types)¶
Validate a V4L2 ISP parameters buffer
Parameters
structdevice*devthe driver’s device pointer
structvb2_buffer*vbthe videobuf2 buffer
conststructv4l2_isp_params_buffer*bufferthe V4L2 ISP parameters buffer
conststructv4l2_isp_params_block_type_info*type_infothe array of per-block-type validation info
size_tnum_block_typesthe number of block types in the type_info array
Description
This function completes the validation of a V4L2 ISP parameters buffer,verifying each configuration block correctness before the driver can usethem to program the hardware.
Drivers should use this function after having validated the correctness ofthe vb2 buffer sizes by using thev4l2_isp_params_validate_buffer_size()helper first. Once the buffer size has been validated, drivers shouldperform a copy of the user provided buffer into a kernel-only memory bufferto prevent userspace from modifying its content after it has been submittedto the driver, and then call this function to complete validation.