1.. SPDX-License-Identifier: GPL-2.0
2
3MIPI CSI-2
4==========
5
6CSI-2 is a data bus intended for transferring images from cameras to
7the host SoC. It is defined by the `MIPI alliance`_.
8
9.. _`MIPI alliance`: http://www.mipi.org/
10
11Transmitter drivers
12-------------------
13
14CSI-2 transmitter, such as a sensor or a TV tuner, drivers need to
15provide the CSI-2 receiver with information on the CSI-2 bus
16configuration. These include the V4L2_CID_LINK_FREQ and
17V4L2_CID_PIXEL_RATE controls and
18(:c:type:`v4l2_subdev_video_ops`->s_stream() callback). These
19interface elements must be present on the sub-device represents the
20CSI-2 transmitter.
21
22The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the
23frequency (and not the symbol rate) of the link. The
24V4L2_CID_PIXEL_RATE is may be used by the receiver to obtain the pixel
25rate the transmitter uses. The
26:c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an
27ability to start and stop the stream.
28
29The value of the V4L2_CID_PIXEL_RATE is calculated as follows::
30
31	pixel_rate = link_freq * 2 * nr_of_lanes / bits_per_sample
32
33where
34
35.. list-table:: variables in pixel rate calculation
36   :header-rows: 1
37
38   * - variable or constant
39     - description
40   * - link_freq
41     - The value of the V4L2_CID_LINK_FREQ integer64 menu item.
42   * - nr_of_lanes
43     - Number of data lanes used on the CSI-2 link. This can
44       be obtained from the OF endpoint configuration.
45   * - 2
46     - Two bits are transferred per clock cycle per lane.
47   * - bits_per_sample
48     - Number of bits per sample.
49
50The transmitter drivers must, if possible, configure the CSI-2
51transmitter to *LP-11 mode* whenever the transmitter is powered on but
52not active, and maintain *LP-11 mode* until stream on. Only at stream
53on should the transmitter activate the clock on the clock lane and
54transition to *HS mode*.
55
56Some transmitters do this automatically but some have to be explicitly
57programmed to do so, and some are unable to do so altogether due to
58hardware constraints.
59
60Stopping the transmitter
61^^^^^^^^^^^^^^^^^^^^^^^^
62
63A transmitter stops sending the stream of images as a result of
64calling the ``.s_stream()`` callback. Some transmitters may stop the
65stream at a frame boundary whereas others stop immediately,
66effectively leaving the current frame unfinished. The receiver driver
67should not make assumptions either way, but function properly in both
68cases.
69
70Receiver drivers
71----------------
72
73Before the receiver driver may enable the CSI-2 transmitter by using
74the :c:type:`v4l2_subdev_video_ops`->s_stream(), it must have powered
75the transmitter up by using the
76:c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take
77place either indirectly by using :c:func:`v4l2_pipeline_pm_use` or
78directly.
79
80Formats
81-------
82
83The media bus pixel codes document parallel formats. Should the pixel data be
84transported over a serial bus, the media bus pixel code that describes a
85parallel format that transfers a sample on a single clock cycle is used.
86