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