/* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
/*
* Video4Linux2 generic ISP parameters and statistics support
*
* Copyright (C) 2025 Ideas On Board Oy
* Author: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
*/
#ifndef _V4L2_ISP_H_
#define _V4L2_ISP_H_
#include <linux/stddef.h>
#include <linux/types.h>
/**
* enum v4l2_isp_version - V4L2 ISP serialization format versioning
*
* @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
*
* 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.
*/
enum v4l2_isp_version {
V4L2_ISP_VERSION_V0 = 0,
V4L2_ISP_VERSION_V1
};
/*
* Compatibility with existing users of v4l2_isp_params which pre-date the
* introduction of v4l2_isp_stats.
*/
#define v4l2_isp_params_version v4l2_isp_version
#define V4L2_ISP_PARAMS_VERSION_V0 V4L2_ISP_VERSION_V0
#define V4L2_ISP_PARAMS_VERSION_V1 V4L2_ISP_VERSION_V1
#define V4L2_ISP_PARAMS_FL_BLOCK_DISABLE (1U << 0)
#define V4L2_ISP_PARAMS_FL_BLOCK_ENABLE (1U << 1)
/*
* Reserve the first 8 bits for V4L2_ISP_PARAMS_FL_* flag.
*
* Driver-specific flags should be defined as:
* #define DRIVER_SPECIFIC_FLAG0 ((1U << V4L2_ISP_FL_DRIVER_FLAGS(0))
* #define DRIVER_SPECIFIC_FLAG1 ((1U << V4L2_ISP_FL_DRIVER_FLAGS(1))
*/
#define V4L2_ISP_FL_DRIVER_FLAGS(n) ((n) + 8)
/**
* struct v4l2_isp_block_header - V4L2 extensible block header
* @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
*
* 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.
*/
struct v4l2_isp_block_header {
__u16 type;
__u16 flags;
__u32 size;
} __attribute__((aligned(8)));
/**
* v4l2_isp_params_block_header - V4L2 extensible parameters block header
*
* Compatibility with existing users of v4l2_isp_params_block_header
* which pre-date the introduction of v4l2_isp_block_header.
*/
#define v4l2_isp_params_block_header v4l2_isp_block_header
/**
* struct v4l2_isp_buffer - V4L2 extensible buffer
* @version: The extensible buffer version (driver-specific)
* @data_size: The data effective size, excluding this header
* @data: The configuration or statistics data
*
* 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 :c:type:`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.
*/
struct v4l2_isp_buffer {
__u32 version;
__u32 data_size;
__u8 data[] __counted_by(data_size);
};
/**
* v4l2_isp_params_buffer - V4L2 extensible parameters compatibility
*
* Compatibility with existing users of v4l2_isp_params_buffer which
* pre-date the introduction of v4l2_isp_buffer.
*/
#define v4l2_isp_params_buffer v4l2_isp_buffer
#endif /* _V4L2_ISP_H_ */