ccs.rst

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