0001 .. SPDX-License-Identifier: GPL-2.0-only
0002
0003 .. include:: <isonum.txt>
0004
0005 MIPI CCS camera sensor driver
0006 =============================
0007
0008 The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS
0009 <https://www.mipi.org/specifications/camera-command-set>`_ compliant
0010 camera sensors. It exposes three sub-devices representing the pixel array,
0011 the binner and the scaler.
0012
0013 As the capabilities of individual devices vary, the driver exposes
0014 interfaces based on the capabilities that exist in hardware.
0015
0016 Pixel Array sub-device
0017 ----------------------
0018
0019 The pixel array sub-device represents the camera sensor's pixel matrix, as well
0020 as analogue crop functionality present in many compliant devices. The analogue
0021 crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the
0022 entity. The size of the pixel matrix can be obtained by getting the
0023 ``V4L2_SEL_TGT_NATIVE_SIZE`` target.
0024
0025 Binner
0026 ------
0027
0028 The binner sub-device represents the binning functionality on the sensor. For
0029 that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the
0030 sink pad (0).
0031
0032 Additionally, if a device has no scaler or digital crop functionality, the
0033 source pad (1) expses another digital crop selection rectangle that can only
0034 crop at the end of the lines and frames.
0035
0036 Scaler
0037 ------
0038
0039 The scaler sub-device represents the digital crop and scaling functionality of
0040 the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to
0041 configure the digital crop on the sink pad (0) when digital crop is supported.
0042 Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the
0043 sink pad (0) as well.
0044
0045 Additionally, if the scaler sub-device exists, its source pad (1) exposes
0046 another digital crop selection rectangle that can only crop at the end of the
0047 lines and frames.
0048
0049 Digital and analogue crop
0050 -------------------------
0051
0052 Digital crop functionality is referred to as cropping that effectively works by
0053 dropping some data on the floor. Analogue crop, on the other hand, means that
0054 the cropped information is never retrieved. In case of camera sensors, the
0055 analogue data is never read from the pixel matrix that are outside the
0056 configured selection rectangle that designates crop. The difference has an
0057 effect in device timing and likely also in power consumption.
0058
0059 Private controls
0060 ----------------
0061
0062 The MIPI CCS driver implements a number of private controls under
0063 ``V4L2_CID_USER_BASE_CCS`` to control the MIPI CCS compliant camera sensors.
0064
0065 Analogue gain model
0066 ~~~~~~~~~~~~~~~~~~~
0067
0068 The CCS defines an analogue gain model where the gain can be calculated using
0069 the following formula:
0070
0071 gain = m0 * x + c0 / (m1 * x + c1)
0072
0073 Either m0 or c0 will be zero. The constants that are device specific, can be
0074 obtained from the following controls:
0075
0076 V4L2_CID_CCS_ANALOGUE_GAIN_M0
0077 V4L2_CID_CCS_ANALOGUE_GAIN_M1
0078 V4L2_CID_CCS_ANALOGUE_GAIN_C0
0079 V4L2_CID_CCS_ANALOGUE_GAIN_C1
0080
0081 The analogue gain (``x`` in the formula) is controlled through
0082 ``V4L2_CID_ANALOGUE_GAIN`` in this case.
0083
0084 Alternate analogue gain model
0085 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0086
0087 The CCS defines another analogue gain model called alternate analogue gain. In
0088 this case, the formula to calculate actual gain consists of linear and
0089 exponential parts:
0090
0091 gain = linear * 2 ^ exponent
0092
0093 The ``linear`` and ``exponent`` factors can be set using the
0094 ``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and
0095 ``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` controls, respectively
0096
0097 Shading correction
0098 ~~~~~~~~~~~~~~~~~~
0099
0100 The CCS standard supports lens shading correction. The feature can be controlled
0101 using ``V4L2_CID_CCS_SHADING_CORRECTION``. Additionally, the luminance
0102 correction level may be changed using
0103 ``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, where value 0 indicates no
0104 correction and 128 indicates correcting the luminance in corners to 10 % less
0105 than in the centre.
0106
0107 Shading correction needs to be enabled for luminance correction level to have an
0108 effect.
0109
0110 **Copyright** |copy| 2020 Intel Corporation
