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 115