diff options
Diffstat (limited to 'include/media/v4l2-isp.h')
| -rw-r--r-- | include/media/v4l2-isp.h | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/include/media/v4l2-isp.h b/include/media/v4l2-isp.h new file mode 100644 index 000000000..7a54cf98c --- /dev/null +++ b/include/media/v4l2-isp.h @@ -0,0 +1,157 @@ +/* SPDX-License-Identifier: GPL-2.0-or-later */ +/* + * 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/media/v4l2-isp.h> + +struct device; +struct vb2_buffer; + +/** + * v4l2_isp_buffer_size - Calculate size of v4l2_isp_buffer + * @max_size: The total size of the ISP configuration or statistics blocks + * + * 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. + * + */ +#define v4l2_isp_buffer_size(max_size) \ + (offsetof(struct v4l2_isp_buffer, data) + (max_size)) + +/** + * v4l2_isp_params_validate_buffer_size - Validate a V4L2 ISP buffer sizes + * @dev: the driver's device pointer + * @vb: the videobuf2 buffer + * @max_size: the maximum allowed buffer size + * + * 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. + */ +int v4l2_isp_params_validate_buffer_size(struct device *dev, + struct vb2_buffer *vb, + size_t max_size); + +/** + * struct v4l2_isp_params_block_type_info - V4L2 ISP params per-block-type info + * @size: the block type expected size + * @block_validate: driver's callback to implement per-block validation + * + * 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. + */ +struct v4l2_isp_params_block_type_info { + size_t size; + int (*block_validate)(struct device *dev, + const struct v4l2_isp_block_header *block); +}; + +/** + * v4l2_isp_params_validate_buffer - Validate a V4L2 ISP parameters buffer + * @dev: the driver's device pointer + * @vb: the videobuf2 buffer + * @buffer: the V4L2 ISP parameters buffer + * @type_info: the array of per-block-type validation info + * @num_block_types: the number of block types in the type_info array + * + * 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. + */ +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); + +/** + * struct v4l2_isp_stats_block_type_info - V4L2 ISP stats per-block-type info + * @size: the block type expected size + * + * 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. + */ +struct v4l2_isp_stats_block_type_info { + size_t size; +}; + +/** + * v4l2_isp_stats_init_buffer - Initialize a statistics buffer + * + * Initialize a buffer of statistics. Only set the 'version' field and reset + * 'data_size' to 0. + * + * @buf: the v4l2_isp_buffer to initialize + * @version: the v4l2-isp serialization format version used by the driver + */ +void v4l2_isp_stats_init_buffer(struct v4l2_isp_buffer *buf, + enum v4l2_isp_version version); + +/** + * v4l2_isp_stats_init_block - Create and initialize a new block in a statistics + * buffer + * @dev: the driver's device pointer + * @buf: the v4l2_isp_buffer where statistics are serialized + * @type_info: the array of per-block-type validation info + * @num_block_types: the number of block types in the type_info array + * @block_type: the type of the statistics block to initialize + * @max_size: the maximum size of the data[] member of @buf + * + * 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. + */ +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); + +#endif /* _V4L2_ISP_H_ */ |