Orange Pi5 kernel

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