c3-isp-config.h

  1/* SPDX-License-Identifier: GPL-2.0-only WITH Linux-syscall-note */
  2/*
  3 * Copyright (C) 2024 Amlogic, Inc. All rights reserved
  4 */
  5
  6#ifndef _UAPI_C3_ISP_CONFIG_H_
  7#define _UAPI_C3_ISP_CONFIG_H_
  8
  9#ifdef __KERNEL__
 10#include <linux/build_bug.h>
 11#endif /* __KERNEL__ */
 12#include <linux/types.h>
 13
 14#include <linux/media/v4l2-isp.h>
 15
 16/*
 17 * Frames are split into zones of almost equal width and height - a zone is a
 18 * rectangular tile of a frame. The metering blocks within the ISP collect
 19 * aggregated statistics per zone.
 20 */
 21#define C3_ISP_AE_MAX_ZONES (17 * 15)
 22#define C3_ISP_AF_MAX_ZONES (17 * 15)
 23#define C3_ISP_AWB_MAX_ZONES (32 * 24)
 24
 25/* The maximum number of point on the diagonal of the frame for statistics */
 26#define C3_ISP_AE_MAX_PT_NUM 18
 27#define C3_ISP_AF_MAX_PT_NUM 18
 28#define C3_ISP_AWB_MAX_PT_NUM 33
 29
 30/**
 31 * struct c3_isp_awb_zone_stats - AWB statistics of a zone
 32 *
 33 * AWB zone stats is aligned with 8 bytes
 34 *
 35 * @rg: the ratio of R / G in a zone
 36 * @bg: the ratio of B / G in a zone
 37 * @pixel_sum: the total number of pixels used in a zone
 38 */
 39struct c3_isp_awb_zone_stats {
 40	__u16 rg;
 41	__u16 bg;
 42	__u32 pixel_sum;
 43};
 44
 45/**
 46 * struct c3_isp_awb_stats - Auto white balance statistics information.
 47 *
 48 * AWB statistical information of all zones.
 49 *
 50 * @stats: array of auto white balance statistics
 51 */
 52struct c3_isp_awb_stats {
 53	struct c3_isp_awb_zone_stats stats[C3_ISP_AWB_MAX_ZONES];
 54} __attribute__((aligned(16)));
 55
 56/**
 57 * struct c3_isp_ae_zone_stats - AE statistics of a zone
 58 *
 59 * AE zone stats is aligned with 8 bytes.
 60 * This is a 5-bin histogram and the total sum is normalized to 0xffff.
 61 * So hist2 = 0xffff - (hist0 + hist1 + hist3 + hist4)
 62 *
 63 * @hist0: the global normalized pixel count for bin 0
 64 * @hist1: the global normalized pixel count for bin 1
 65 * @hist3: the global normalized pixel count for bin 3
 66 * @hist4: the global normalized pixel count for bin 4
 67 */
 68struct c3_isp_ae_zone_stats {
 69	__u16 hist0;
 70	__u16 hist1;
 71	__u16 hist3;
 72	__u16 hist4;
 73};
 74
 75/**
 76 * struct c3_isp_ae_stats - Exposure statistics information
 77 *
 78 * AE statistical information consists of all blocks information and a 1024-bin
 79 * histogram.
 80 *
 81 * @stats: array of auto exposure block statistics
 82 * @reserved: undefined buffer space
 83 * @hist: a 1024-bin histogram for the entire image
 84 */
 85struct c3_isp_ae_stats {
 86	struct c3_isp_ae_zone_stats stats[C3_ISP_AE_MAX_ZONES];
 87	__u32 reserved[2];
 88	__u32 hist[1024];
 89} __attribute__((aligned(16)));
 90
 91/**
 92 * struct c3_isp_af_zone_stats - AF statistics of a zone
 93 *
 94 * AF zone stats is aligned with 8 bytes.
 95 * The zonal accumulated contrast metrics are stored in floating point format
 96 * with 16 bits mantissa and 5 or 6 bits exponent. Apart from contrast metrics
 97 * we accumulate squared image and quartic image data over the zone.
 98 *
 99 * @i2_mat: the mantissa of zonal squared image pixel sum
100 * @i4_mat: the mantissa of zonal quartic image pixel sum
101 * @e4_mat: the mantissa of zonal multi-directional quartic edge sum
102 * @e4_exp: the exponent of zonal multi-directional quartic edge sum
103 * @i2_exp: the exponent of zonal squared image pixel sum
104 * @i4_exp: the exponent of zonal quartic image pixel sum
105 */
106struct c3_isp_af_zone_stats {
107	__u16 i2_mat;
108	__u16 i4_mat;
109	__u16 e4_mat;
110	__u16 e4_exp : 5;
111	__u16 i2_exp : 5;
112	__u16 i4_exp : 6;
113};
114
115/**
116 * struct c3_isp_af_stats - Auto Focus statistics information
117 *
118 * AF statistical information of each zone
119 *
120 * @stats: array of auto focus block statistics
121 * @reserved: undefined buffer space
122 */
123struct c3_isp_af_stats {
124	struct c3_isp_af_zone_stats stats[C3_ISP_AF_MAX_ZONES];
125	__u32 reserved[2];
126} __attribute__((aligned(16)));
127
128/**
129 * struct c3_isp_stats_info - V4L2_META_FMT_C3ISP_STATS
130 *
131 * Contains ISP statistics
132 *
133 * @awb: auto white balance stats
134 * @ae: auto exposure stats
135 * @af: auto focus stats
136 */
137struct c3_isp_stats_info {
138	struct c3_isp_awb_stats awb;
139	struct c3_isp_ae_stats ae;
140	struct c3_isp_af_stats af;
141};
142
143/**
144 * enum c3_isp_params_buffer_version -  C3 ISP parameters block versioning
145 *
146 * @C3_ISP_PARAMS_BUFFER_V0: First version of C3 ISP parameters block
147 */
148enum c3_isp_params_buffer_version {
149	C3_ISP_PARAMS_BUFFER_V0 = V4L2_ISP_PARAMS_VERSION_V0,
150};
151
152/**
153 * enum c3_isp_params_block_type - Enumeration of C3 ISP parameter blocks
154 *
155 * Each block configures a specific processing block of the C3 ISP.
156 * The block type allows the driver to correctly interpret the parameters block
157 * data.
158 *
159 * @C3_ISP_PARAMS_BLOCK_AWB_GAINS: White balance gains
160 * @C3_ISP_PARAMS_BLOCK_AWB_CONFIG: AWB statistic format configuration for all
161 *                                  blocks that control how stats are generated
162 * @C3_ISP_PARAMS_BLOCK_AE_CONFIG: AE statistic format configuration for all
163 *                                 blocks that control how stats are generated
164 * @C3_ISP_PARAMS_BLOCK_AF_CONFIG: AF statistic format configuration for all
165 *                                 blocks that control how stats are generated
166 * @C3_ISP_PARAMS_BLOCK_PST_GAMMA: post gamma parameters
167 * @C3_ISP_PARAMS_BLOCK_CCM: Color correction matrix parameters
168 * @C3_ISP_PARAMS_BLOCK_CSC: Color space conversion parameters
169 * @C3_ISP_PARAMS_BLOCK_BLC: Black level correction parameters
170 * @C3_ISP_PARAMS_BLOCK_SENTINEL: First non-valid block index
171 */
172enum c3_isp_params_block_type {
173	C3_ISP_PARAMS_BLOCK_AWB_GAINS,
174	C3_ISP_PARAMS_BLOCK_AWB_CONFIG,
175	C3_ISP_PARAMS_BLOCK_AE_CONFIG,
176	C3_ISP_PARAMS_BLOCK_AF_CONFIG,
177	C3_ISP_PARAMS_BLOCK_PST_GAMMA,
178	C3_ISP_PARAMS_BLOCK_CCM,
179	C3_ISP_PARAMS_BLOCK_CSC,
180	C3_ISP_PARAMS_BLOCK_BLC,
181	C3_ISP_PARAMS_BLOCK_SENTINEL
182};
183
184/* For backward compatibility */
185#define C3_ISP_PARAMS_BLOCK_FL_DISABLE	V4L2_ISP_PARAMS_FL_BLOCK_DISABLE
186#define C3_ISP_PARAMS_BLOCK_FL_ENABLE	V4L2_ISP_PARAMS_FL_BLOCK_ENABLE
187
188/**
189 * c3_isp_params_block_header - C3 ISP parameter block header
190 *
191 * This structure represents the common part of all the ISP configuration
192 * blocks and is identical to :c:type:`v4l2_isp_params_block_header`.
193 *
194 * The type field is one of the values enumerated by
195 * :c:type:`c3_isp_params_block_type` and specifies how the data should be
196 * interpreted by the driver.
197 *
198 * The flags field is a bitmask of per-block flags C3_ISP_PARAMS_FL_*.
199 */
200#define c3_isp_params_block_header v4l2_isp_params_block_header
201
202/**
203 * struct c3_isp_params_awb_gains - Gains for auto-white balance
204 *
205 * This struct allows users to configure the gains for white balance.
206 * There are four gain settings corresponding to each colour channel in
207 * the bayer domain. All of the gains are stored in Q4.8 format.
208 *
209 * header.type should be set to C3_ISP_PARAMS_BLOCK_AWB_GAINS
210 * from :c:type:`c3_isp_params_block_type`
211 *
212 * @header: The C3 ISP parameters block header
213 * @gr_gain: Multiplier for Gr channel (Q4.8 format)
214 * @r_gain: Multiplier for R channel (Q4.8 format)
215 * @b_gain: Multiplier for B channel (Q4.8 format)
216 * @gb_gain: Multiplier for Gb channel (Q4.8 format)
217 */
218struct c3_isp_params_awb_gains {
219	struct c3_isp_params_block_header header;
220	__u16 gr_gain;
221	__u16 r_gain;
222	__u16 b_gain;
223	__u16 gb_gain;
224} __attribute__((aligned(8)));
225
226/**
227 * enum c3_isp_params_awb_tap_points - Tap points for the AWB statistics
228 * @C3_ISP_AWB_STATS_TAP_OFE: immediately after the optical frontend block
229 * @C3_ISP_AWB_STATS_TAP_GE: immediately after the green equal block
230 * @C3_ISP_AWB_STATS_TAP_BEFORE_WB: immediately before the white balance block
231 * @C3_ISP_AWB_STATS_TAP_AFTER_WB: immediately after the white balance block
232 */
233enum c3_isp_params_awb_tap_points {
234	C3_ISP_AWB_STATS_TAP_OFE = 0,
235	C3_ISP_AWB_STATS_TAP_GE,
236	C3_ISP_AWB_STATS_TAP_BEFORE_WB,
237	C3_ISP_AWB_STATS_TAP_AFTER_WB,
238};
239
240/**
241 * struct c3_isp_params_awb_config - Stats settings for auto-white balance
242 *
243 * This struct allows the configuration of the statistics generated for auto
244 * white balance.
245 *
246 * header.type should be set to C3_ISP_PARAMS_BLOCK_AWB_CONFIG
247 * from :c:type:`c3_isp_params_block_type`
248 *
249 * @header: the C3 ISP parameters block header
250 * @tap_point: the tap point from enum c3_isp_params_awb_tap_point
251 * @satur_vald: AWB statistic over saturation control
252 *		value: 0: disable, 1: enable
253 * @horiz_zones_num: active number of hotizontal zones [0..32]
254 * @vert_zones_num: active number of vertical zones [0..24]
255 * @rg_min: minimum R/G ratio (Q4.8 format)
256 * @rg_max: maximum R/G ratio (Q4.8 format)
257 * @bg_min: minimum B/G ratio (Q4.8 format)
258 * @bg_max: maximum B/G ratio (Q4.8 format)
259 * @rg_low: R/G ratio trim low (Q4.8 format)
260 * @rg_high: R/G ratio trim hight (Q4.8 format)
261 * @bg_low: B/G ratio trim low (Q4.8 format)
262 * @bg_high: B/G ratio trim high (Q4.8 format)
263 * @zone_weight: array of weights for AWB statistics zones [0..15]
264 * @horiz_coord: the horizontal coordinate of points on the diagonal [0..2888]
265 * @vert_coord: the vertical coordinate of points on the diagonal [0..2240]
266 */
267struct c3_isp_params_awb_config {
268	struct c3_isp_params_block_header header;
269	__u8 tap_point;
270	__u8 satur_vald;
271	__u8 horiz_zones_num;
272	__u8 vert_zones_num;
273	__u16 rg_min;
274	__u16 rg_max;
275	__u16 bg_min;
276	__u16 bg_max;
277	__u16 rg_low;
278	__u16 rg_high;
279	__u16 bg_low;
280	__u16 bg_high;
281	__u8 zone_weight[C3_ISP_AWB_MAX_ZONES];
282	__u16 horiz_coord[C3_ISP_AWB_MAX_PT_NUM];
283	__u16 vert_coord[C3_ISP_AWB_MAX_PT_NUM];
284} __attribute__((aligned(8)));
285
286/**
287 * enum c3_isp_params_ae_tap_points - Tap points for the AE statistics
288 * @C3_ISP_AE_STATS_TAP_GE: immediately after the green equal block
289 * @C3_ISP_AE_STATS_TAP_MLS: immediately after the mesh lens shading block
290 */
291enum c3_isp_params_ae_tap_points {
292	C3_ISP_AE_STATS_TAP_GE = 0,
293	C3_ISP_AE_STATS_TAP_MLS,
294};
295
296/**
297 * struct c3_isp_params_ae_config - Stats settings for auto-exposure
298 *
299 * This struct allows the configuration of the statistics generated for
300 * auto exposure.
301 *
302 * header.type should be set to C3_ISP_PARAMS_BLOCK_AE_CONFIG
303 * from :c:type:`c3_isp_params_block_type`
304 *
305 * @header: the C3 ISP parameters block header
306 * @horiz_zones_num: active number of horizontal zones [0..17]
307 * @vert_zones_num: active number of vertical zones [0..15]
308 * @tap_point: the tap point from enum c3_isp_params_ae_tap_point
309 * @zone_weight: array of weights for AE statistics zones [0..15]
310 * @horiz_coord: the horizontal coordinate of points on the diagonal [0..2888]
311 * @vert_coord: the vertical coordinate of points on the diagonal [0..2240]
312 * @reserved: applications must zero this array
313 */
314struct c3_isp_params_ae_config {
315	struct c3_isp_params_block_header header;
316	__u8 tap_point;
317	__u8 horiz_zones_num;
318	__u8 vert_zones_num;
319	__u8 zone_weight[C3_ISP_AE_MAX_ZONES];
320	__u16 horiz_coord[C3_ISP_AE_MAX_PT_NUM];
321	__u16 vert_coord[C3_ISP_AE_MAX_PT_NUM];
322	__u16 reserved[3];
323} __attribute__((aligned(8)));
324
325/**
326 * enum c3_isp_params_af_tap_points - Tap points for the AF statistics
327 * @C3_ISP_AF_STATS_TAP_SNR: immediately after the spatial noise reduce block
328 * @C3_ISP_AF_STATS_TAP_DMS: immediately after the demosaic block
329 */
330enum c3_isp_params_af_tap_points {
331	C3_ISP_AF_STATS_TAP_SNR = 0,
332	C3_ISP_AF_STATS_TAP_DMS,
333};
334
335/**
336 * struct c3_isp_params_af_config - Stats settings for auto-focus
337 *
338 * This struct allows the configuration of the statistics generated for
339 * auto focus.
340 *
341 * header.type should be set to C3_ISP_PARAMS_BLOCK_AF_CONFIG
342 * from :c:type:`c3_isp_params_block_type`
343 *
344 * @header: the C3 ISP parameters block header
345 * @tap_point: the tap point from enum c3_isp_params_af_tap_point
346 * @horiz_zones_num: active number of hotizontal zones [0..17]
347 * @vert_zones_num: active number of vertical zones [0..15]
348 * @reserved: applications must zero this array
349 * @horiz_coord: the horizontal coordinate of points on the diagonal [0..2888]
350 * @vert_coord: the vertical coordinate of points on the diagonal [0..2240]
351 */
352struct c3_isp_params_af_config {
353	struct c3_isp_params_block_header header;
354	__u8 tap_point;
355	__u8 horiz_zones_num;
356	__u8 vert_zones_num;
357	__u8 reserved[5];
358	__u16 horiz_coord[C3_ISP_AF_MAX_PT_NUM];
359	__u16 vert_coord[C3_ISP_AF_MAX_PT_NUM];
360} __attribute__((aligned(8)));
361
362/**
363 * struct c3_isp_params_pst_gamma - Post gamma configuration
364 *
365 * This struct allows the configuration of the look up table for
366 * post gamma. The gamma curve consists of 129 points, so need to
367 * set lut[129].
368 *
369 * header.type should be set to C3_ISP_PARAMS_BLOCK_PST_GAMMA
370 * from :c:type:`c3_isp_params_block_type`
371 *
372 * @header: the C3 ISP parameters block header
373 * @lut: lookup table for P-Stitch gamma [0..1023]
374 * @reserved: applications must zero this array
375 */
376struct c3_isp_params_pst_gamma {
377	struct c3_isp_params_block_header header;
378	__u16 lut[129];
379	__u16 reserved[3];
380} __attribute__((aligned(8)));
381
382/**
383 * struct c3_isp_params_ccm - ISP CCM configuration
384 *
385 * This struct allows the configuration of the matrix for
386 * color correction. The matrix consists of 3 x 3 points,
387 * so need to set matrix[3][3].
388 *
389 * header.type should be set to C3_ISP_PARAMS_BLOCK_CCM
390 * from :c:type:`c3_isp_params_block_type`
391 *
392 * @header: the C3 ISP parameters block header
393 * @matrix: a 3 x 3 matrix used for color correction,
394 *          the value of matrix[x][y] is orig_value x 256. [-4096..4095]
395 * @reserved: applications must zero this array
396 */
397struct c3_isp_params_ccm {
398	struct c3_isp_params_block_header header;
399	__s16 matrix[3][3];
400	__u16 reserved[3];
401} __attribute__((aligned(8)));
402
403/**
404 * struct c3_isp_params_csc - ISP Color Space Conversion configuration
405 *
406 * This struct allows the configuration of the matrix for color space
407 * conversion. The matrix consists of 3 x 3 points, so need to set matrix[3][3].
408 *
409 * header.type should be set to C3_ISP_PARAMS_BLOCK_CSC
410 * from :c:type:`c3_isp_params_block_type`
411 *
412 * @header: the C3 ISP parameters block header
413 * @matrix: a 3x3 matrix used for the color space conversion,
414 *          the value of matrix[x][y] is orig_value x 256. [-4096..4095]
415 * @reserved: applications must zero this array
416 */
417struct c3_isp_params_csc {
418	struct c3_isp_params_block_header header;
419	__s16 matrix[3][3];
420	__u16 reserved[3];
421} __attribute__((aligned(8)));
422
423/**
424 * struct c3_isp_params_blc - ISP Black Level Correction configuration
425 *
426 * This struct allows the configuration of the block level offset for each
427 * color channel.
428 *
429 * header.type should be set to C3_ISP_PARAMS_BLOCK_BLC
430 * from :c:type:`c3_isp_params_block_type`
431 *
432 * @header: the C3 ISP parameters block header
433 * @gr_ofst: Gr blc offset (Q4.12 format)
434 * @r_ofst: R blc offset (Q4.12 format)
435 * @b_ofst: B blc offset (Q4.12 format)
436 * @gb_ofst: Gb blc offset(Q4.12 format)
437 */
438struct c3_isp_params_blc {
439	struct c3_isp_params_block_header header;
440	__u16 gr_ofst;
441	__u16 r_ofst;
442	__u16 b_ofst;
443	__u16 gb_ofst;
444};
445
446/**
447 * define C3_ISP_PARAMS_MAX_SIZE - Maximum size of all C3 ISP Parameters
448 *
449 * Though the parameters for the C3 ISP are passed as optional blocks, the
450 * driver still needs to know the absolute maximum size so that it can allocate
451 * a buffer sized appropriately to accommodate userspace attempting to set all
452 * possible parameters in a single frame.
453 */
454#define C3_ISP_PARAMS_MAX_SIZE                     \
455	(sizeof(struct c3_isp_params_awb_gains) +  \
456	 sizeof(struct c3_isp_params_awb_config) + \
457	 sizeof(struct c3_isp_params_ae_config) +  \
458	 sizeof(struct c3_isp_params_af_config) +  \
459	 sizeof(struct c3_isp_params_pst_gamma) +  \
460	 sizeof(struct c3_isp_params_ccm) +        \
461	 sizeof(struct c3_isp_params_csc) +        \
462	 sizeof(struct c3_isp_params_blc))
463
464/**
465 * struct c3_isp_params_cfg - C3 ISP configuration parameters
466 *
467 * This is the driver-specific implementation of
468 * :c:type:`v4l2_isp_params_buffer`.
469 *
470 * Currently only C3_ISP_PARAM_BUFFER_V0 is supported.
471 *
472 * The expected memory layout of the parameters buffer is::
473 *
474 *	+-------------------- struct c3_isp_params_cfg ---- ------------------+
475 *	| version = C3_ISP_PARAM_BUFFER_V0;                                   |
476 *	| data_size = sizeof(struct c3_isp_params_awb_gains) +                |
477 *	|              sizeof(struct c3_isp_params_awb_config);       |
478 *	| +------------------------- data  ---------------------------------+ |
479 *	| | +------------ struct c3_isp_params_awb_gains) ------------------+ |
480 *	| | | +---------  struct c3_isp_params_block_header header -----+ | | |
481 *	| | | | type = C3_ISP_PARAMS_BLOCK_AWB_GAINS;                   | | | |
482 *	| | | | flags = C3_ISP_PARAMS_BLOCK_FL_NONE;                    | | | |
483 *	| | | | size = sizeof(struct c3_isp_params_awb_gains);          | | | |
484 *	| | | +---------------------------------------------------------+ | | |
485 *	| | | gr_gain = ...;                                              | | |
486 *	| | | r_gain = ...;                                               | | |
487 *	| | | b_gain = ...;                                               | | |
488 *	| | | gb_gain = ...;                                              | | |
489 *	| | +------------------ struct c3_isp_params_awb_config ----------+ | |
490 *	| | | +---------- struct c3_isp_param_block_header header ------+ | | |
491 *	| | | | type = C3_ISP_PARAMS_BLOCK_AWB_CONFIG;                  | | | |
492 *	| | | | flags = C3_ISP_PARAMS_BLOCK_FL_NONE;                    | | | |
493 *	| | | | size = sizeof(struct c3_isp_params_awb_config)          | | | |
494 *	| | | +---------------------------------------------------------+ | | |
495 *	| | | tap_point = ...;                                            | | |
496 *	| | | satur_vald = ...;                                           | | |
497 *	| | | horiz_zones_num = ...;                                      | | |
498 *	| | | vert_zones_num = ...;                                       | | |
499 *	| | +-------------------------------------------------------------+ | |
500 *	| +-----------------------------------------------------------------+ |
501 *	+---------------------------------------------------------------------+
502 *
503 * @version: The C3 ISP parameters buffer version
504 * @data_size: The C3 ISP configuration data effective size, excluding this
505 *             header
506 * @data: The C3 ISP configuration blocks data
507 */
508struct c3_isp_params_cfg {
509	__u32 version;
510	__u32 data_size;
511	__u8 data[C3_ISP_PARAMS_MAX_SIZE];
512};
513
514#ifdef __KERNEL__
515/* Make sure the header is type-convertible to the generic v4l2 params one */
516static_assert((sizeof(struct c3_isp_params_cfg) - C3_ISP_PARAMS_MAX_SIZE) ==
517	      sizeof(struct v4l2_isp_params_buffer));
518#endif /* __KERNEL__ */
519
520#endif