0001 .. SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
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 Register definition generator
0060 -----------------------------
0061
0062 The ccs-regs.asc file contains MIPI CCS register definitions that are used
0063 to produce C source code files for definitions that can be better used by
0064 programs written in C language. As there are many dependencies between the
0065 produced files, please do not modify them manually as it's error-prone and
0066 in vain, but instead change the script producing them.
0067
0068 Usage
0069 ~~~~~
0070
0071 Conventionally the script is called this way to update the CCS driver
0072 definitions:
0073
0074 .. code-block:: none
0075
0076 $ Documentation/driver-api/media/drivers/ccs/mk-ccs-regs -k \
0077 -e drivers/media/i2c/ccs/ccs-regs.h \
0078 -L drivers/media/i2c/ccs/ccs-limits.h \
0079 -l drivers/media/i2c/ccs/ccs-limits.c \
0080 -c Documentation/driver-api/media/drivers/ccs/ccs-regs.asc
0081
0082 CCS PLL calculator
0083 ==================
0084
0085 The CCS PLL calculator is used to compute the PLL configuration, given sensor's
0086 capabilities as well as board configuration and user specified configuration. As
0087 the configuration space that encompasses all these configurations is vast, the
0088 PLL calculator isn't entirely trivial. Yet it is relatively simple to use for a
0089 driver.
0090
0091 The PLL model implemented by the PLL calculator corresponds to MIPI CCS 1.1.
0092
0093 .. kernel-doc:: drivers/media/i2c/ccs-pll.h
0094
0095 **Copyright** |copy| 2020 Intel Corporation
