xref: /openbmc/linux/Documentation/userspace-api/media/drivers/ccs.rst (revision d0034a7a4ac7fae708146ac0059b9c47a1543f0d)
1db08f69eSSakari Ailus.. SPDX-License-Identifier: GPL-2.0-only
2db08f69eSSakari Ailus
3db08f69eSSakari Ailus.. include:: <isonum.txt>
4db08f69eSSakari Ailus
5db08f69eSSakari AilusMIPI CCS camera sensor driver
6db08f69eSSakari Ailus=============================
7db08f69eSSakari Ailus
8db08f69eSSakari AilusThe MIPI CCS camera sensor driver is a generic driver for `MIPI CCS
9db08f69eSSakari Ailus<https://www.mipi.org/specifications/camera-command-set>`_ compliant
10db08f69eSSakari Ailuscamera sensors. It exposes three sub-devices representing the pixel array,
11db08f69eSSakari Ailusthe binner and the scaler.
12db08f69eSSakari Ailus
13db08f69eSSakari AilusAs the capabilities of individual devices vary, the driver exposes
14db08f69eSSakari Ailusinterfaces based on the capabilities that exist in hardware.
15db08f69eSSakari Ailus
16db08f69eSSakari AilusPixel Array sub-device
17db08f69eSSakari Ailus----------------------
18db08f69eSSakari Ailus
19db08f69eSSakari AilusThe pixel array sub-device represents the camera sensor's pixel matrix, as well
20db08f69eSSakari Ailusas analogue crop functionality present in many compliant devices. The analogue
21db08f69eSSakari Ailuscrop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the
22db08f69eSSakari Ailusentity. The size of the pixel matrix can be obtained by getting the
23db08f69eSSakari Ailus``V4L2_SEL_TGT_NATIVE_SIZE`` target.
24db08f69eSSakari Ailus
25db08f69eSSakari AilusBinner
26db08f69eSSakari Ailus------
27db08f69eSSakari Ailus
28db08f69eSSakari AilusThe binner sub-device represents the binning functionality on the sensor. For
29db08f69eSSakari Ailusthat purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the
30db08f69eSSakari Ailussink pad (0).
31db08f69eSSakari Ailus
32db08f69eSSakari AilusAdditionally, if a device has no scaler or digital crop functionality, the
33db08f69eSSakari Ailussource pad (1) expses another digital crop selection rectangle that can only
34db08f69eSSakari Ailuscrop at the end of the lines and frames.
35db08f69eSSakari Ailus
36db08f69eSSakari AilusScaler
37db08f69eSSakari Ailus------
38db08f69eSSakari Ailus
39db08f69eSSakari AilusThe scaler sub-device represents the digital crop and scaling functionality of
40db08f69eSSakari Ailusthe sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to
41db08f69eSSakari Ailusconfigure the digital crop on the sink pad (0) when digital crop is supported.
42db08f69eSSakari AilusScaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the
43db08f69eSSakari Ailussink pad (0) as well.
44db08f69eSSakari Ailus
45db08f69eSSakari AilusAdditionally, if the scaler sub-device exists, its source pad (1) exposes
46db08f69eSSakari Ailusanother digital crop selection rectangle that can only crop at the end of the
47db08f69eSSakari Ailuslines and frames.
48db08f69eSSakari Ailus
49db08f69eSSakari AilusDigital and analogue crop
50db08f69eSSakari Ailus-------------------------
51db08f69eSSakari Ailus
52db08f69eSSakari AilusDigital crop functionality is referred to as cropping that effectively works by
53db08f69eSSakari Ailusdropping some data on the floor. Analogue crop, on the other hand, means that
54db08f69eSSakari Ailusthe cropped information is never retrieved. In case of camera sensors, the
55db08f69eSSakari Ailusanalogue data is never read from the pixel matrix that are outside the
56db08f69eSSakari Ailusconfigured selection rectangle that designates crop. The difference has an
57db08f69eSSakari Ailuseffect in device timing and likely also in power consumption.
58db08f69eSSakari Ailus
59a8a2d75bSSakari AilusPrivate controls
60a8a2d75bSSakari Ailus----------------
61a8a2d75bSSakari Ailus
62a8a2d75bSSakari AilusThe MIPI CCS driver implements a number of private controls under
63a8a2d75bSSakari Ailus``V4L2_CID_USER_BASE_CCS`` to control the MIPI CCS compliant camera sensors.
64a8a2d75bSSakari Ailus
65a8a2d75bSSakari AilusAnalogue gain model
66a8a2d75bSSakari Ailus~~~~~~~~~~~~~~~~~~~
67a8a2d75bSSakari Ailus
68a8a2d75bSSakari AilusThe CCS defines an analogue gain model where the gain can be calculated using
69a8a2d75bSSakari Ailusthe following formula:
70a8a2d75bSSakari Ailus
71a8a2d75bSSakari Ailus	gain = m0 * x + c0 / (m1 * x + c1)
72a8a2d75bSSakari Ailus
73a8a2d75bSSakari AilusEither m0 or c0 will be zero. The constants that are device specific, can be
74a8a2d75bSSakari Ailusobtained from the following controls:
75a8a2d75bSSakari Ailus
76a8a2d75bSSakari Ailus	V4L2_CID_CCS_ANALOGUE_GAIN_M0
77a8a2d75bSSakari Ailus	V4L2_CID_CCS_ANALOGUE_GAIN_M1
78a8a2d75bSSakari Ailus	V4L2_CID_CCS_ANALOGUE_GAIN_C0
79a8a2d75bSSakari Ailus	V4L2_CID_CCS_ANALOGUE_GAIN_C1
80a8a2d75bSSakari Ailus
81a8a2d75bSSakari AilusThe analogue gain (``x`` in the formula) is controlled through
82a8a2d75bSSakari Ailus``V4L2_CID_ANALOGUE_GAIN`` in this case.
83a8a2d75bSSakari Ailus
84a75210a6SSakari AilusAlternate analogue gain model
85a75210a6SSakari Ailus~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
86a75210a6SSakari Ailus
87a75210a6SSakari AilusThe CCS defines another analogue gain model called alternate analogue gain. In
88a75210a6SSakari Ailusthis case, the formula to calculate actual gain consists of linear and
89a75210a6SSakari Ailusexponential parts:
90a75210a6SSakari Ailus
91a75210a6SSakari Ailus	gain = linear * 2 ^ exponent
92a75210a6SSakari Ailus
93a75210a6SSakari AilusThe ``linear`` and ``exponent`` factors can be set using the
94a75210a6SSakari Ailus``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and
95a75210a6SSakari Ailus``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` controls, respectively
96a75210a6SSakari Ailus
97*7c0ed600SSakari AilusShading correction
98*7c0ed600SSakari Ailus~~~~~~~~~~~~~~~~~~
99*7c0ed600SSakari Ailus
100*7c0ed600SSakari AilusThe CCS standard supports lens shading correction. The feature can be controlled
101*7c0ed600SSakari Ailususing ``V4L2_CID_CCS_SHADING_CORRECTION``. Additionally, the luminance
102*7c0ed600SSakari Ailuscorrection level may be changed using
103*7c0ed600SSakari Ailus``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, where value 0 indicates no
104*7c0ed600SSakari Ailuscorrection and 128 indicates correcting the luminance in corners to 10 % less
105*7c0ed600SSakari Ailusthan in the centre.
106*7c0ed600SSakari Ailus
107*7c0ed600SSakari AilusShading correction needs to be enabled for luminance correction level to have an
108*7c0ed600SSakari Ailuseffect.
109*7c0ed600SSakari Ailus
110db08f69eSSakari Ailus**Copyright** |copy| 2020 Intel Corporation
111