xref: /linux/Documentation/driver-api/media/drivers/ccs/ccs.rst (revision 3df692169e8486fc3dd91fcd5ea81c27a0bac033)
1.. SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
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) exposes 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
59CCS static data
60---------------
61
62The MIPI CCS driver supports CCS static data for all compliant devices,
63including not just those compliant with CCS 1.1 but also CCS 1.0 and SMIA(++).
64For CCS the file names are formed as
65
66	ccs/ccs-sensor-vvvv-mmmm-rrrr.fw (sensor) and
67	ccs/ccs-module-vvvv-mmmm-rrrr.fw (module).
68
69For SMIA++ compliant devices the corresponding file names are
70
71	ccs/smiapp-sensor-vv-mmmm-rr.fw (sensor) and
72	ccs/smiapp-module-vv-mmmm-rrrr.fw (module).
73
74For SMIA (non-++) compliant devices the static data file name is
75
76	ccs/smia-sensor-vv-mmmm-rr.fw (sensor).
77
78vvvv or vv denotes MIPI and SMIA manufacturer IDs respectively, mmmm model ID
79and rrrr or rr revision number.
80
81CCS tools
82~~~~~~~~~
83
84`CCS tools <https://github.com/MIPI-Alliance/ccs-tools/>`_ is a set of
85tools for working with CCS static data files. CCS tools includes a
86definition of the human-readable CCS static data YAML format and includes a
87program to convert it to a binary.
88
89Register definition generator
90-----------------------------
91
92The ccs-regs.asc file contains MIPI CCS register definitions that are used
93to produce C source code files for definitions that can be better used by
94programs written in C language. As there are many dependencies between the
95produced files, please do not modify them manually as it's error-prone and
96in vain, but instead change the script producing them.
97
98Usage
99~~~~~
100
101Conventionally the script is called this way to update the CCS driver
102definitions:
103
104.. code-block:: none
105
106	$ Documentation/driver-api/media/drivers/ccs/mk-ccs-regs -k \
107		-e drivers/media/i2c/ccs/ccs-regs.h \
108		-L drivers/media/i2c/ccs/ccs-limits.h \
109		-l drivers/media/i2c/ccs/ccs-limits.c \
110		-c Documentation/driver-api/media/drivers/ccs/ccs-regs.asc
111
112CCS PLL calculator
113==================
114
115The CCS PLL calculator is used to compute the PLL configuration, given sensor's
116capabilities as well as board configuration and user specified configuration. As
117the configuration space that encompasses all these configurations is vast, the
118PLL calculator isn't entirely trivial. Yet it is relatively simple to use for a
119driver.
120
121The PLL model implemented by the PLL calculator corresponds to MIPI CCS 1.1.
122
123.. kernel-doc:: drivers/media/i2c/ccs-pll.h
124
125**Copyright** |copy| 2020 Intel Corporation
126