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