1 .. SPDX-License-Identifier: GPL-2.0-only 1 .. SPDX-License-Identifier: GPL-2.0-only
2 2
3 .. include:: <isonum.txt> 3 .. include:: <isonum.txt>
4 4
5 .. _media-ccs-uapi: 5 .. _media-ccs-uapi:
6 6
7 MIPI CCS camera sensor driver 7 MIPI CCS camera sensor driver
8 ============================= 8 =============================
9 9
10 The MIPI CCS camera sensor driver is a generic 10 The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS
11 <https://www.mipi.org/specifications/camera-co 11 <https://www.mipi.org/specifications/camera-command-set>`_ compliant
12 camera sensors. It exposes three sub-devices r 12 camera sensors. It exposes three sub-devices representing the pixel array,
13 the binner and the scaler. 13 the binner and the scaler.
14 14
15 As the capabilities of individual devices vary 15 As the capabilities of individual devices vary, the driver exposes
16 interfaces based on the capabilities that exis 16 interfaces based on the capabilities that exist in hardware.
17 17
18 Also see :ref:`the CCS driver kernel documenta 18 Also see :ref:`the CCS driver kernel documentation <media-ccs-driver>`.
19 19
20 Pixel Array sub-device 20 Pixel Array sub-device
21 ---------------------- 21 ----------------------
22 22
23 The pixel array sub-device represents the came 23 The pixel array sub-device represents the camera sensor's pixel matrix, as well
24 as analogue crop functionality present in many 24 as analogue crop functionality present in many compliant devices. The analogue
25 crop is configured using the ``V4L2_SEL_TGT_CR 25 crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the
26 entity. The size of the pixel matrix can be ob 26 entity. The size of the pixel matrix can be obtained by getting the
27 ``V4L2_SEL_TGT_NATIVE_SIZE`` target. 27 ``V4L2_SEL_TGT_NATIVE_SIZE`` target.
28 28
29 Binner 29 Binner
30 ------ 30 ------
31 31
32 The binner sub-device represents the binning f 32 The binner sub-device represents the binning functionality on the sensor. For
33 that purpose, selection target ``V4L2_SEL_TGT_ 33 that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the
34 sink pad (0). 34 sink pad (0).
35 35
36 Additionally, if a device has no scaler or dig 36 Additionally, if a device has no scaler or digital crop functionality, the
37 source pad (1) exposes another digital crop se 37 source pad (1) exposes another digital crop selection rectangle that can only
38 crop at the end of the lines and frames. 38 crop at the end of the lines and frames.
39 39
40 Scaler 40 Scaler
41 ------ 41 ------
42 42
43 The scaler sub-device represents the digital c 43 The scaler sub-device represents the digital crop and scaling functionality of
44 the sensor. The V4L2 selection target ``V4L2_S 44 the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to
45 configure the digital crop on the sink pad (0) 45 configure the digital crop on the sink pad (0) when digital crop is supported.
46 Scaling is configured using selection target ` 46 Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the
47 sink pad (0) as well. 47 sink pad (0) as well.
48 48
49 Additionally, if the scaler sub-device exists, 49 Additionally, if the scaler sub-device exists, its source pad (1) exposes
50 another digital crop selection rectangle that 50 another digital crop selection rectangle that can only crop at the end of the
51 lines and frames. 51 lines and frames.
52 52
53 Digital and analogue crop 53 Digital and analogue crop
54 ------------------------- 54 -------------------------
55 55
56 Digital crop functionality is referred to as c 56 Digital crop functionality is referred to as cropping that effectively works by
57 dropping some data on the floor. Analogue crop 57 dropping some data on the floor. Analogue crop, on the other hand, means that
58 the cropped information is never retrieved. In 58 the cropped information is never retrieved. In case of camera sensors, the
59 analogue data is never read from the pixel mat 59 analogue data is never read from the pixel matrix that are outside the
60 configured selection rectangle that designates 60 configured selection rectangle that designates crop. The difference has an
61 effect in device timing and likely also in pow 61 effect in device timing and likely also in power consumption.
62 62
63 Private controls 63 Private controls
64 ---------------- 64 ----------------
65 65
66 The MIPI CCS driver implements a number of pri 66 The MIPI CCS driver implements a number of private controls under
67 ``V4L2_CID_USER_BASE_CCS`` to control the MIPI 67 ``V4L2_CID_USER_BASE_CCS`` to control the MIPI CCS compliant camera sensors.
68 68
69 Analogue gain model 69 Analogue gain model
70 ~~~~~~~~~~~~~~~~~~~ 70 ~~~~~~~~~~~~~~~~~~~
71 71
72 The CCS defines an analogue gain model where t 72 The CCS defines an analogue gain model where the gain can be calculated using
73 the following formula: 73 the following formula:
74 74
75 gain = m0 * x + c0 / (m1 * x + c1) 75 gain = m0 * x + c0 / (m1 * x + c1)
76 76
77 Either m0 or c0 will be zero. The constants th 77 Either m0 or c0 will be zero. The constants that are device specific, can be
78 obtained from the following controls: 78 obtained from the following controls:
79 79
80 V4L2_CID_CCS_ANALOGUE_GAIN_M0 80 V4L2_CID_CCS_ANALOGUE_GAIN_M0
81 V4L2_CID_CCS_ANALOGUE_GAIN_M1 81 V4L2_CID_CCS_ANALOGUE_GAIN_M1
82 V4L2_CID_CCS_ANALOGUE_GAIN_C0 82 V4L2_CID_CCS_ANALOGUE_GAIN_C0
83 V4L2_CID_CCS_ANALOGUE_GAIN_C1 83 V4L2_CID_CCS_ANALOGUE_GAIN_C1
84 84
85 The analogue gain (``x`` in the formula) is co 85 The analogue gain (``x`` in the formula) is controlled through
86 ``V4L2_CID_ANALOGUE_GAIN`` in this case. 86 ``V4L2_CID_ANALOGUE_GAIN`` in this case.
87 87
88 Alternate analogue gain model 88 Alternate analogue gain model
89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90 90
91 The CCS defines another analogue gain model ca 91 The CCS defines another analogue gain model called alternate analogue gain. In
92 this case, the formula to calculate actual gai 92 this case, the formula to calculate actual gain consists of linear and
93 exponential parts: 93 exponential parts:
94 94
95 gain = linear * 2 ^ exponent 95 gain = linear * 2 ^ exponent
96 96
97 The ``linear`` and ``exponent`` factors can be 97 The ``linear`` and ``exponent`` factors can be set using the
98 ``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and 98 ``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and
99 ``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` con 99 ``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` controls, respectively
100 100
101 Shading correction 101 Shading correction
102 ~~~~~~~~~~~~~~~~~~ 102 ~~~~~~~~~~~~~~~~~~
103 103
104 The CCS standard supports lens shading correct 104 The CCS standard supports lens shading correction. The feature can be controlled
105 using ``V4L2_CID_CCS_SHADING_CORRECTION``. Add 105 using ``V4L2_CID_CCS_SHADING_CORRECTION``. Additionally, the luminance
106 correction level may be changed using 106 correction level may be changed using
107 ``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, w 107 ``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, where value 0 indicates no
108 correction and 128 indicates correcting the lu 108 correction and 128 indicates correcting the luminance in corners to 10 % less
109 than in the centre. 109 than in the centre.
110 110
111 Shading correction needs to be enabled for lum 111 Shading correction needs to be enabled for luminance correction level to have an
112 effect. 112 effect.
113 113
114 **Copyright** |copy| 2020 Intel Corporation 114 **Copyright** |copy| 2020 Intel Corporation
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.