Open Menu / include / media / v4l2-isp.h 
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
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_ */