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