Documentation/driver-api/media/drivers/ccs/ccs.rst

   1 .. SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause
   2
   3 .. include:: <isonum.txt>
   4
   5 MIPI CCS camera sensor driver
   6 =============================
   7
   8 The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS
   9 <https://www.mipi.org/specifications/camera-command-set>`_ compliant
  10 camera sensors. It exposes three sub-devices representing the pixel array,
  11 the binner and the scaler.
  12
  13 As the capabilities of individual devices vary, the driver exposes
  14 interfaces based on the capabilities that exist in hardware.
  15
  16 Pixel Array sub-device
  17 ----------------------
  18
  19 The pixel array sub-device represents the camera sensor's pixel matrix, as well
  20 as analogue crop functionality present in many compliant devices. The analogue
  21 crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the
  22 entity. The size of the pixel matrix can be obtained by getting the
  23 ``V4L2_SEL_TGT_NATIVE_SIZE`` target.
  24
  25 Binner
  26 ------
  27
  28 The binner sub-device represents the binning functionality on the sensor. For
  29 that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the
  30 sink pad (0).
  31
  32 Additionally, if a device has no scaler or digital crop functionality, the
  33 source pad (1) exposes another digital crop selection rectangle that can only
  34 crop at the end of the lines and frames.
  35
  36 Scaler
  37 ------
  38
  39 The scaler sub-device represents the digital crop and scaling functionality of
  40 the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to
  41 configure the digital crop on the sink pad (0) when digital crop is supported.
  42 Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the
  43 sink pad (0) as well.
  44
  45 Additionally, if the scaler sub-device exists, its source pad (1) exposes
  46 another digital crop selection rectangle that can only crop at the end of the
  47 lines and frames.
  48
  49 Digital and analogue crop
  50 -------------------------
  51
  52 Digital crop functionality is referred to as cropping that effectively works by
  53 dropping some data on the floor. Analogue crop, on the other hand, means that
  54 the cropped information is never retrieved. In case of camera sensors, the
  55 analogue data is never read from the pixel matrix that are outside the
  56 configured selection rectangle that designates crop. The difference has an
  57 effect in device timing and likely also in power consumption.
  58
  59 CCS static data
  60 ---------------
  61
  62 The MIPI CCS driver supports CCS static data for all compliant devices,
  63 including not just those compliant with CCS 1.1 but also CCS 1.0 and SMIA(++).
  64 For 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
  69 For 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
  74 For SMIA (non-++) compliant devices the static data file name is
  75
  76         ccs/smia-sensor-vv-mmmm-rr.fw (sensor).
  77
  78 vvvv or vv denotes MIPI and SMIA manufacturer IDs respectively, mmmm model ID
  79 and rrrr or rr revision number.
  80
  81 CCS tools
  82 ~~~~~~~~~
  83
  84 `CCS tools <https://github.com/MIPI-Alliance/ccs-tools/>`_ is a set of
  85 tools for working with CCS static data files. CCS tools includes a
  86 definition of the human-readable CCS static data YAML format and includes a
  87 program to convert it to a binary.
  88
  89 Register definition generator
  90 -----------------------------
  91
  92 The ccs-regs.asc file contains MIPI CCS register definitions that are used
  93 to produce C source code files for definitions that can be better used by
  94 programs written in C language. As there are many dependencies between the
  95 produced files, please do not modify them manually as it's error-prone and
  96 in vain, but instead change the script producing them.
  97
  98 Usage
  99 ~~~~~
 100
 101 Conventionally the script is called this way to update the CCS driver
 102 definitions:
 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
 112 CCS PLL calculator
 113 ==================
 114
 115 The CCS PLL calculator is used to compute the PLL configuration, given sensor's
 116 capabilities as well as board configuration and user specified configuration. As
 117 the configuration space that encompasses all these configurations is vast, the
 118 PLL calculator isn't entirely trivial. Yet it is relatively simple to use for a
 119 driver.
 120
 121 The 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