|author||Sakari Ailus <email@example.com>||2021-02-01 10:16:03 +0100|
|committer||Mauro Carvalho Chehab <firstname.lastname@example.org>||2021-08-04 14:43:50 +0200|
media: Documentation: media: Improve camera sensor documentation
Modernise the documentation to make it more precise and update the use of pixel rate control and various other changes. In particular: - Use non-proportional font for file names, properties as well as controls. - The unit of the HBLANK control is pixels, not lines. - The unit of PIXEL_RATE control is pixels per second, not Hz. - Merge common requirements for CSI-2 and parallel busses. - Include all DT properties needed for assigned clocks. - Fix referencing the link rate control. - SMIA driver's new name is CCS driver. - The PIXEL_RATE control denotes pixel rate on the pixel array on camera sensors. Do not suggest it is used to tell the maximum pixel rate on the bus anymore. - Improve ReST syntax (plain struct and function names). - Remove the suggestion to use s_power() in receiver drivers. - Make MIPI website URL use HTTPS, add Wikipedia links to BT.601 and BT.656. Fixes: e4cf8c58af75 ("media: Documentation: media: Document how to write camera sensor drivers") Signed-off-by: Sakari Ailus <email@example.com> Reviewed-by: Jacopo Mondi <firstname.lastname@example.org> Reviewed-by: Andrey Konovalov <email@example.com> Signed-off-by: Mauro Carvalho Chehab <firstname.lastname@example.org>
Diffstat (limited to 'Documentation/driver-api/media/tx-rx.rst')
1 files changed, 117 insertions, 0 deletions
diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst
new file mode 100644
@@ -0,0 +1,117 @@
+.. SPDX-License-Identifier: GPL-2.0
+Pixel data transmitter and receiver drivers
+V4L2 supports various devices that transmit and receiver pixel data. Examples of
+these devices include a camera sensor, a TV tuner and a parallel or a CSI-2
+receiver in an SoC.
+The following busses are the most common. This section discusses these two only.
+CSI-2 is a data bus intended for transferring images from cameras to
+the host SoC. It is defined by the `MIPI alliance`_.
+.. _`MIPI alliance`: https://www.mipi.org/
+`BT.601`_ and `BT.656`_ are the most common parallel busses.
+.. _`BT.601`: https://en.wikipedia.org/wiki/Rec._601
+.. _`BT.656`: https://en.wikipedia.org/wiki/ITU-R_BT.656
+Transmitter drivers generally need to provide the receiver drivers with the
+configuration of the transmitter. What is required depends on the type of the
+bus. These are common for both busses.
+Media bus pixel code
+The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the
+receiver the frequency of the bus (i.e. it is not the same as the symbol rate).
+The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the
+receiver driver to control the transmitter driver's streaming state.
+CSI-2 transmitter drivers
+The pixel rate on the bus is calculated as follows::
+ pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample
+.. list-table:: variables in pixel rate calculation
+ :header-rows: 1
+ * - variable or constant
+ - description
+ * - link_freq
+ - The value of the ``V4L2_CID_LINK_FREQ`` integer64 menu item.
+ * - nr_of_lanes
+ - Number of data lanes used on the CSI-2 link. This can
+ be obtained from the OF endpoint configuration.
+ * - 2
+ - Data is transferred on both rising and falling edge of the signal.
+ * - bits_per_sample
+ - Number of bits per sample.
+ * - k
+ - 16 for D-PHY and 7 for C-PHY
+ The pixel rate calculated this way is **not** the same thing as the
+ pixel rate on the camera sensor's pixel array which is indicated by the
+ :ref:`V4L2_CID_PIXEL_RATE <v4l2-cid-pixel-rate>` control.
+LP-11 and LP-111 modes
+The transmitter drivers must, if possible, configure the CSI-2 transmitter to
+*LP-11 or LP-111 mode* whenever the transmitter is powered on but not active,
+and maintain *LP-11 or LP-111 mode* until stream on. Only at stream on should
+the transmitter activate the clock on the clock lane and transition to *HS
+Some transmitters do this automatically but some have to be explicitly
+programmed to do so, and some are unable to do so altogether due to
+The receiver thus need to be configured to expect LP-11 or LP-111 mode from the
+transmitter before the transmitter driver's ``.s_stream()`` op is called.
+Stopping the transmitter
+A transmitter stops sending the stream of images as a result of
+calling the ``.s_stream()`` callback. Some transmitters may stop the
+stream at a frame boundary whereas others stop immediately,
+effectively leaving the current frame unfinished. The receiver driver
+should not make assumptions either way, but function properly in both