Commit db08f69e authored by Sakari Ailus's avatar Sakari Ailus Committed by Mauro Carvalho Chehab
Browse files

media: Documentation: ccs: Add user documentation for the CCS driver 



Add user documentation for the CCS driver. This includes e.g. sub-devices
implemented by the driver.

Signed-off-by: default avatarSakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent cd9f145d

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

0 → 100644
+59 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0-only



.. include:: <isonum.txt>



MIPI CCS camera sensor driver

=============================



The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS

<https://www.mipi.org/specifications/camera-command-set>`_ compliant

camera sensors. It exposes three sub-devices representing the pixel array,

the binner and the scaler.



As the capabilities of individual devices vary, the driver exposes

interfaces based on the capabilities that exist in hardware.



Pixel Array sub-device

----------------------



The pixel array sub-device represents the camera sensor's pixel matrix, as well

as analogue crop functionality present in many compliant devices. The analogue

crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the

entity. The size of the pixel matrix can be obtained by getting the

``V4L2_SEL_TGT_NATIVE_SIZE`` target.



Binner

------



The binner sub-device represents the binning functionality on the sensor. For

that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the

sink pad (0).



Additionally, if a device has no scaler or digital crop functionality, the

source pad (1) expses another digital crop selection rectangle that can only

crop at the end of the lines and frames.



Scaler

------



The scaler sub-device represents the digital crop and scaling functionality of

the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to

configure the digital crop on the sink pad (0) when digital crop is supported.

Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the

sink pad (0) as well.



Additionally, if the scaler sub-device exists, its source pad (1) exposes

another digital crop selection rectangle that can only crop at the end of the

lines and frames.



Digital and analogue crop

-------------------------



Digital crop functionality is referred to as cropping that effectively works by

dropping some data on the floor. Analogue crop, on the other hand, means that

the cropped information is never retrieved. In case of camera sensors, the

analogue data is never read from the pixel matrix that are outside the

configured selection rectangle that designates crop. The difference has an

effect in device timing and likely also in power consumption.



**Copyright** |copy| 2020 Intel Corporation

Documentation/userspace-api/media/drivers/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -31,6 +31,7 @@ For more details see the file COPYING in the source distribution of Linux. 
	:maxdepth: 5

	:numbered:



	ccs

	cx2341x-uapi

	imx-uapi

	max2175

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -11836,6 +11836,7 @@ L: linux-media@vger.kernel.org 
S:	Maintained

F:	Documentation/devicetree/bindings/media/i2c/mipi-ccs.yaml

F:	Documentation/driver-api/media/drivers/ccs/

F:	Documentation/userspace-api/media/drivers/ccs.rst

F:	drivers/media/i2c/ccs-pll.c

F:	drivers/media/i2c/ccs-pll.h

F:	drivers/media/i2c/ccs/