2.13.16. Generic V4L2 ISP formats

Generic ISP formats are metadata formats that define a mechanism to pass ISP parameters and statistics between userspace and drivers in V4L2 buffers. They are designed to allow extending them in a backward-compatible way.

2.13.16.1. ISP parameters

The generic ISP configuration parameters format is realized by a defining a single C structure that contains a header, followed by a binary buffer where userspace programs a variable number of ISP configuration data block, one for each supported ISP feature.

The v4l2_isp_buffer structure defines the buffer header which is followed by a binary buffer of ISP configuration data. Userspace shall correctly populate the buffer header with the serialization format version and with the size (in bytes) of the binary data buffer where it will store the ISP blocks configuration.

Each ISP configuration block is preceded by a header implemented by the v4l2_isp_block_header structure, followed by the configuration parameters for that specific block, defined by the ISP driver specific data types.

Userspace applications are responsible for correctly populating each block’s header fields (type, flags and size) and the block-specific parameters.

2.13.16.1.1. ISP parameters block enabling, disabling and configuration

When userspace wants to configure and enable an ISP block it shall fully populate the block configuration and set the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE bit in the block header’s flags field.

When userspace simply wants to disable an ISP block the V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bit should be set in block header’s flags field. Drivers accept a configuration parameters block with no additional data after the header in this case.

If the configuration of an already active ISP block has to be updated, userspace shall fully populate the ISP block parameters and omit setting the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the header’s flags field.

Setting both the V4L2_ISP_PARAMS_FL_BLOCK_ENABLE and V4L2_ISP_PARAMS_FL_BLOCK_DISABLE bits in the flags field is not allowed and returns an error.

Extension to the parameters format can be implemented by adding new blocks definition without invalidating the existing ones.

2.13.16.2. ISP statistics

The generic ISP statistics format is identical to the generic ISP configuration parameters format. It is realized by defining a C structure that contains a header, followed by binary buffer where the ISP driver copies a variable number of ISP statistics blocks.

Extensible statistics buffers have v4l2_isp_buffer header followed by a binary buffer of ISP statistics data. ISP drivers populate the buffer header with the serialization format version and with the size (in bytes) of the binary data buffer where ISP statistics data are serialized. Applications shall validate that the serialization format version matches the expected one and that the buffer size doesn’t exceed the maximum size for a statistics buffer as declared by the driver’s uAPI header.

Each ISP statistics block is preceded by a header implemented by the v4l2_isp_block_header structure, followed by the statistics data for that specific block. The driver might optionally report platform-specific flags associated with each statistics block.

Applications inspect the statistics block type as reported in the header and validates the reported size matches the block’s expected size before accessing the ISP statistics data.

Extension to the statistics format can be implemented by adding new blocks definition without invalidating the existing ones.

2.13.16.3. V4L2 ISP uAPI data types

enum v4l2_isp_version

V4L2 ISP serialization format versioning

Constants

V4L2_ISP_VERSION_V0

First version of the V4L2 ISP serialization format (for compatibility)

V4L2_ISP_VERSION_V1

First version of the V4L2 ISP serialization format

Description

V0 and V1 are identical in order to support drivers compatible with the V4L2 ISP format already upstreamed which use either 0 or 1 as their versioning identifier. Both V0 and V1 refers to the first version of the V4L2 ISP serialization format.

Future revisions of the V4L2 ISP serialization format should start from the value of 2.

struct v4l2_isp_block_header

V4L2 extensible block header

Definition:

struct v4l2_isp_block_header {
    __u16 type;
    __u16 flags;
    __u32 size;
};

Members

type

The parameters or statistics block type (driver-specific)

flags

A bitmask of block flags (driver-specific)

size

Size (in bytes) of the block, including this header

Description

This structure represents the common part of all the ISP configuration or statistic blocks. Each block shall embed an instance of this structure type as its first member, followed by the block-specific configuration or statistic data.

The type field is an ISP driver-specific value that identifies the block type. The size field specifies the size of the block, including this header.

The flags field is a bitmask of per-block flags. If a block is used for configuration parameters this field can be a combination of V4L2_ISP_PARAMS_FL_* and driver-specific flags. If a block is used for statistics this fields is used to report optional driver-specific flags, if any.

v4l2_isp_params_block_header

v4l2_isp_params_block_header

V4L2 extensible parameters block header

Description

Compatibility with existing users of v4l2_isp_params_block_header which pre-date the introduction of v4l2_isp_block_header.

struct v4l2_isp_buffer

V4L2 extensible buffer

Definition:

struct v4l2_isp_buffer {
    __u32 version;
    __u32 data_size;
    __u8 data[];
};

Members

version

The extensible buffer version (driver-specific)

data_size

The data effective size, excluding this header

data

The configuration or statistics data

Description

This structure contains ISP configuration parameters or ISP hardware statistics serialized into a data buffer. Each block is represented by a block-specific structure which contains a v4l2_isp_block_header entry as first member.

When used for ISP parameters, userspace populates the data buffer with configuration parameters for the blocks that it intends to configure. As a consequence, the data buffer effective size changes according to the number of ISP blocks that userspace intends to configure.

When used to report ISP statistics, the driver populates the data buffer with statistics for each supported measurement block.

The buffer is versioned by the version field to allow modifying and extending its definition. The writer shall populate the version field to inform the reader about the version it intends to use. The reader will parse and handle the data buffer according to the data layout specific to the indicated version and return an error if the desired version is not supported.

For each ISP block, a block-specific structure is appended to the data buffer, one after the other without gaps in between. The writer shall populate the data_size field with the effective size, in bytes, of the data buffer.

v4l2_isp_params_buffer

v4l2_isp_params_buffer

V4L2 extensible parameters compatibility

Description

Compatibility with existing users of v4l2_isp_params_buffer which pre-date the introduction of v4l2_isp_buffer.