1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 * Video4Linux2 generic ISP parameters and statistics support 4 * 5 * Copyright (C) 2025 Ideas On Board Oy 6 * Author: Jacopo Mondi <jacopo.mondi@ideasonboard.com> 7 */ 8 9 #ifndef _V4L2_ISP_H_ 10 #define _V4L2_ISP_H_ 11 12 #include <linux/media/v4l2-isp.h> 13 14 struct device; 15 struct vb2_buffer; 16 17 /** 18 * v4l2_isp_buffer_size - Calculate size of v4l2_isp_buffer 19 * @max_size: The total size of the ISP configuration or statistics blocks 20 * 21 * Users of v4l2-isp will have differing sized data arrays for parameters and 22 * statistics, depending on their specific blocks. Drivers need to be able to 23 * calculate the appropriate size of the buffer to accommodate all ISP blocks 24 * supported by the platform. This macro provides a convenient tool for the 25 * calculation. 26 * 27 * The intended users of this function are drivers initializing the size 28 * of their metadata (parameters and statistics) buffers. 29 * 30 */ 31 #define v4l2_isp_buffer_size(max_size) \ 32 (offsetof(struct v4l2_isp_buffer, data) + (max_size)) 33 34 /** 35 * v4l2_isp_params_validate_buffer_size - Validate a V4L2 ISP buffer sizes 36 * @dev: the driver's device pointer 37 * @vb: the videobuf2 buffer 38 * @max_size: the maximum allowed buffer size 39 * 40 * This function performs validation of the size of a V4L2 ISP parameters buffer 41 * before the driver can access the actual data buffer content. 42 * 43 * After the sizes validation, drivers should copy the buffer content to a 44 * kernel-only memory area to prevent userspace from modifying it, 45 * before completing validation using v4l2_isp_params_validate_buffer(). 46 * 47 * The @vb buffer as received from the vb2 .buf_prepare() operation is checked 48 * against @max_size and it's validated to be large enough to accommodate at 49 * least one ISP configuration block. 50 */ 51 int v4l2_isp_params_validate_buffer_size(struct device *dev, 52 struct vb2_buffer *vb, 53 size_t max_size); 54 55 /** 56 * struct v4l2_isp_params_block_type_info - V4L2 ISP params per-block-type info 57 * @size: the block type expected size 58 * @block_validate: driver's callback to implement per-block validation 59 * 60 * The v4l2_isp_params_block_type_info collects information of the ISP 61 * configuration block types for validation purposes. It contains the expected 62 * block type size and a function pointer where drivers can register a callback 63 * for additional per-block validation purposes. The validation function is 64 * expected to return 0 on success or a negative error number for errors. 65 * 66 * Drivers shall prepare a list of block type info, indexed by block type, one 67 * for each supported ISP block type and correctly populate them with the 68 * expected block type size and the optional callback. 69 */ 70 struct v4l2_isp_params_block_type_info { 71 size_t size; 72 int (*block_validate)(struct device *dev, 73 const struct v4l2_isp_block_header *block); 74 }; 75 76 /** 77 * v4l2_isp_params_validate_buffer - Validate a V4L2 ISP parameters buffer 78 * @dev: the driver's device pointer 79 * @vb: the videobuf2 buffer 80 * @buffer: the V4L2 ISP parameters buffer 81 * @type_info: the array of per-block-type validation info 82 * @num_block_types: the number of block types in the type_info array 83 * 84 * This function completes the validation of a V4L2 ISP parameters buffer, 85 * verifying each configuration block correctness before the driver can use 86 * them to program the hardware. 87 * 88 * Drivers should use this function after having validated the correctness of 89 * the vb2 buffer sizes by using the v4l2_isp_params_validate_buffer_size() 90 * helper first. Once the buffer size has been validated, drivers should 91 * perform a copy of the user provided buffer into a kernel-only memory buffer 92 * to prevent userspace from modifying its content after it has been submitted 93 * to the driver, and then call this function to complete validation. 94 */ 95 int v4l2_isp_params_validate_buffer(struct device *dev, struct vb2_buffer *vb, 96 const struct v4l2_isp_params_buffer *buffer, 97 const struct v4l2_isp_params_block_type_info *type_info, 98 size_t num_block_types); 99 100 /** 101 * struct v4l2_isp_stats_block_type_info - V4L2 ISP stats per-block-type info 102 * @size: the block type expected size 103 * 104 * The v4l2_isp_stats_block_type_info collects information of the ISP 105 * statistics block types for validation purposes. It currently only contains 106 * the expected block size. 107 * 108 * Drivers shall prepare a list of statistics block type info, indexed by block 109 * type, one for each supported ISP statistics block type and correctly populate 110 * them with the expected block size. 111 */ 112 struct v4l2_isp_stats_block_type_info { 113 size_t size; 114 }; 115 116 /** 117 * v4l2_isp_stats_init_buffer - Initialize a statistics buffer 118 * 119 * Initialize a buffer of statistics. Only set the 'version' field and reset 120 * 'data_size' to 0. 121 * 122 * @buf: the v4l2_isp_buffer to initialize 123 * @version: the v4l2-isp serialization format version used by the driver 124 */ 125 void v4l2_isp_stats_init_buffer(struct v4l2_isp_buffer *buf, 126 enum v4l2_isp_version version); 127 128 /** 129 * v4l2_isp_stats_init_block - Create and initialize a new block in a statistics 130 * buffer 131 * @dev: the driver's device pointer 132 * @buf: the v4l2_isp_buffer where statistics are serialized 133 * @type_info: the array of per-block-type validation info 134 * @num_block_types: the number of block types in the type_info array 135 * @block_type: the type of the statistics block to initialize 136 * @max_size: the maximum size of the data[] member of @buf 137 * 138 * This function locates and initialize a new statistics block in @buf for the 139 * driver to populate its content. The function checks that enough space for the 140 * requested @block_type is available in @buf and increments the 'data_size' 141 * member of @buf. The newly created statistics block's header is initialized 142 * with the size and type information provided by the caller in @type_info. 143 * 144 * Drivers should call this function before populating a new statistics block 145 * content. 146 * 147 * Returns a pointer to the next available location in @buf, or an error pointer 148 * if the requested @block_size is not available in @buf or @block_type is not 149 * valid. 150 */ 151 struct v4l2_isp_block_header * 152 v4l2_isp_stats_init_block(struct device *dev, struct v4l2_isp_buffer *buf, 153 const struct v4l2_isp_stats_block_type_info *type_info, 154 size_t num_block_types, unsigned int block_type, 155 size_t max_size); 156 157 #endif /* _V4L2_ISP_H_ */ 158