3.30. V4L2 generic ISP parameters and statistics support

3.30.1. Design rationale

ISP configuration parameters and statistics are processed and collected by drivers and exchanged with userspace through data types that usually reflect the ISP peripheral registers layout.

Each ISP driver defines its own metadata output format for parameters and a metadata capture format for statistics. The buffer layout is realized by a set of C structures that reflects the registers layout. The number and types of C structures is fixed by the format definition and becomes part of the Linux kernel uAPI/uABI interface.

Because of the hard requirement of backward compatibility when extending the user API/ABI interface, modifying an ISP driver capture or output metadata format 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 ISP driver the buffers layout need to be modified, either to support new hardware blocks, to fix bugs or to support different revisions of the hardware.

Each of these situations would require defining a new metadata format, making it really hard to maintain and extend drivers and requiring userspace to use the correct format depending on the kernel revision in use.

3.30.2. V4L2 ISP configuration parameters

For these reasons, Video4Linux2 defines generic types for ISP configuration parameters and statistics. Drivers are still expected to define their own formats for their metadata output and capture nodes, but the buffers layout can be defined using the extensible and versioned types defined by include/uapi/linux/media/v4l2-isp.h.

Drivers are expected to provide the definitions of their supported ISP blocks and the expected maximum size of a buffer.

For driver developers a set of helper functions to assist them with validation of the buffer received from userspace is available in drivers/media/v4l2-core/v4l2-isp.c

3.30.3. V4L2 ISP support driver documentation

v4l2_isp_buffer_size

v4l2_isp_buffer_size (max_size)

Calculate size of v4l2_isp_buffer

Parameters

max_size

The total size of the ISP configuration or statistics blocks

Description

Users of v4l2-isp will have differing sized data arrays for parameters and statistics, depending on their specific blocks. Drivers need to be able to calculate the appropriate size of the buffer to accommodate all ISP blocks supported by the platform. This macro provides a convenient tool for the calculation.

The intended users of this function are drivers initializing the size of their metadata (parameters and statistics) buffers.

int v4l2_isp_params_validate_buffer_size(struct device *dev, struct vb2_buffer *vb, size_t max_size)

Validate a V4L2 ISP buffer sizes

Parameters

struct device *dev

the driver’s device pointer

struct vb2_buffer *vb

the videobuf2 buffer

size_t max_size

the maximum allowed buffer size

Description

This function performs validation of the size of a V4L2 ISP parameters buffer before the driver can access the actual data buffer content.

After the sizes validation, drivers should copy the buffer content to a kernel-only memory area to prevent userspace from modifying it, before completing validation using v4l2_isp_params_validate_buffer().

The vb buffer as received from the vb2 .buf_prepare() operation is checked against max_size and it’s validated to be large enough to accommodate at least one ISP configuration block.

struct v4l2_isp_params_block_type_info

V4L2 ISP params per-block-type info

Definition:

struct v4l2_isp_params_block_type_info {
      size_t size;
      int (*block_validate)(struct device *dev, const struct v4l2_isp_block_header *block);
};

Members

size

the block type expected size

block_validate

driver’s callback to implement per-block validation

Description

The v4l2_isp_params_block_type_info collects information of the ISP configuration block types for validation purposes. It contains the expected block type size and a function pointer where drivers can register a callback for additional per-block validation purposes. The validation function is expected to return 0 on success or a negative error number for errors.

Drivers shall prepare a list of block type info, indexed by block type, one for each supported ISP block type and correctly populate them with the expected block type size and the optional callback.

int v4l2_isp_params_validate_buffer(struct device *dev, struct vb2_buffer *vb, const struct v4l2_isp_params_buffer *buffer, const struct v4l2_isp_params_block_type_info *type_info, size_t num_block_types)

Validate a V4L2 ISP parameters buffer

Parameters

struct device *dev

the driver’s device pointer

struct vb2_buffer *vb

the videobuf2 buffer

const struct v4l2_isp_params_buffer *buffer

the V4L2 ISP parameters buffer

const struct v4l2_isp_params_block_type_info *type_info

the array of per-block-type validation info

size_t num_block_types

the 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 use them to program the hardware.

Drivers should use this function after having validated the correctness of the vb2 buffer sizes by using the v4l2_isp_params_validate_buffer_size() helper first. Once the buffer size has been validated, drivers should perform a copy of the user provided buffer into a kernel-only memory buffer to prevent userspace from modifying its content after it has been submitted to the driver, and then call this function to complete validation.

struct v4l2_isp_stats_block_type_info

V4L2 ISP stats per-block-type info

Definition:

struct v4l2_isp_stats_block_type_info {
      size_t size;
};

Members

size

the block type expected size

Description

The v4l2_isp_stats_block_type_info collects information of the ISP statistics block types for validation purposes. It currently only contains the expected block size.

Drivers shall prepare a list of statistics block type info, indexed by block type, one for each supported ISP statistics block type and correctly populate them with the expected block size.

void v4l2_isp_stats_init_buffer(struct v4l2_isp_buffer *buf, enum v4l2_isp_version version)

Initialize a statistics buffer

Parameters

struct v4l2_isp_buffer *buf

the v4l2_isp_buffer to initialize

enum v4l2_isp_version version

the v4l2-isp serialization format version used by the driver

Description

Initialize a buffer of statistics. Only set the ‘version’ field and reset ‘data_size’ to 0.

struct v4l2_isp_block_header *v4l2_isp_stats_init_block(struct device *dev, struct v4l2_isp_buffer *buf, const struct v4l2_isp_stats_block_type_info *type_info, size_t num_block_types, unsigned int block_type, size_t max_size)

Create and initialize a new block in a statistics buffer

Parameters

struct device *dev

the driver’s device pointer

struct v4l2_isp_buffer *buf

the v4l2_isp_buffer where statistics are serialized

const struct v4l2_isp_stats_block_type_info *type_info

the array of per-block-type validation info

size_t num_block_types

the number of block types in the type_info array

unsigned int block_type

the type of the statistics block to initialize

size_t max_size

the maximum size of the data[] member of buf

Description

This function locates and initialize a new statistics block in buf for the driver to populate its content. The function checks that enough space for the requested block_type is available in buf and increments the ‘data_size’ member of buf. The newly created statistics block’s header is initialized with the size and type information provided by the caller in type_info.

Drivers should call this function before populating a new statistics block content.

Returns a pointer to the next available location in buf, or an error pointer if the requested block_size is not available in buf or block_type is not valid.