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