1b9a54336SSakari Ailus.. SPDX-License-Identifier: GPL-2.0 2b9a54336SSakari Ailus 3b9a54336SSakari Ailus.. _transmitter-receiver: 4b9a54336SSakari Ailus 5b9a54336SSakari AilusPixel data transmitter and receiver drivers 6b9a54336SSakari Ailus=========================================== 7b9a54336SSakari Ailus 86f8f9fdeSSakari AilusV4L2 supports various devices that transmit and receive pixel data. Examples of 9cff18d8fSSakari Ailusthese devices include a camera sensor, a TV tuner and a parallel, a BT.656 or a 10cff18d8fSSakari AilusCSI-2 receiver in an SoC. 11b9a54336SSakari Ailus 12b9a54336SSakari AilusBus types 13b9a54336SSakari Ailus--------- 14b9a54336SSakari Ailus 15b9a54336SSakari AilusThe following busses are the most common. This section discusses these two only. 16b9a54336SSakari Ailus 17b9a54336SSakari AilusMIPI CSI-2 18b9a54336SSakari Ailus^^^^^^^^^^ 19b9a54336SSakari Ailus 20b9a54336SSakari AilusCSI-2 is a data bus intended for transferring images from cameras to 21b9a54336SSakari Ailusthe host SoC. It is defined by the `MIPI alliance`_. 22b9a54336SSakari Ailus 23b9a54336SSakari Ailus.. _`MIPI alliance`: https://www.mipi.org/ 24b9a54336SSakari Ailus 25cff18d8fSSakari AilusParallel and BT.656 26cff18d8fSSakari Ailus^^^^^^^^^^^^^^^^^^^ 27b9a54336SSakari Ailus 28cff18d8fSSakari AilusThe parallel and `BT.656`_ buses transport one bit of data on each clock cycle 29cff18d8fSSakari Ailusper data line. The parallel bus uses synchronisation and other additional 30cff18d8fSSakari Ailussignals whereas BT.656 embeds synchronisation. 31b9a54336SSakari Ailus 32b9a54336SSakari Ailus.. _`BT.656`: https://en.wikipedia.org/wiki/ITU-R_BT.656 33b9a54336SSakari Ailus 34b9a54336SSakari AilusTransmitter drivers 35b9a54336SSakari Ailus------------------- 36b9a54336SSakari Ailus 37b9a54336SSakari AilusTransmitter drivers generally need to provide the receiver drivers with the 38b9a54336SSakari Ailusconfiguration of the transmitter. What is required depends on the type of the 39b9a54336SSakari Ailusbus. These are common for both busses. 40b9a54336SSakari Ailus 41b9a54336SSakari AilusMedia bus pixel code 42b9a54336SSakari Ailus^^^^^^^^^^^^^^^^^^^^ 43b9a54336SSakari Ailus 44b9a54336SSakari AilusSee :ref:`v4l2-mbus-pixelcode`. 45b9a54336SSakari Ailus 46b9a54336SSakari AilusLink frequency 47b9a54336SSakari Ailus^^^^^^^^^^^^^^ 48b9a54336SSakari Ailus 49b9a54336SSakari AilusThe :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the 50b9a54336SSakari Ailusreceiver the frequency of the bus (i.e. it is not the same as the symbol rate). 51b9a54336SSakari Ailus 52b9a54336SSakari Ailus``.s_stream()`` callback 53b9a54336SSakari Ailus^^^^^^^^^^^^^^^^^^^^^^^^ 54b9a54336SSakari Ailus 55b9a54336SSakari AilusThe struct struct v4l2_subdev_video_ops->s_stream() callback is used by the 56b9a54336SSakari Ailusreceiver driver to control the transmitter driver's streaming state. 57b9a54336SSakari Ailus 58b9a54336SSakari Ailus 59b9a54336SSakari AilusCSI-2 transmitter drivers 60b9a54336SSakari Ailus------------------------- 61b9a54336SSakari Ailus 62b9a54336SSakari AilusPixel rate 63b9a54336SSakari Ailus^^^^^^^^^^ 64b9a54336SSakari Ailus 65b9a54336SSakari AilusThe pixel rate on the bus is calculated as follows:: 66b9a54336SSakari Ailus 67b9a54336SSakari Ailus pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample 68b9a54336SSakari Ailus 69b9a54336SSakari Ailuswhere 70b9a54336SSakari Ailus 71b9a54336SSakari Ailus.. list-table:: variables in pixel rate calculation 72b9a54336SSakari Ailus :header-rows: 1 73b9a54336SSakari Ailus 74b9a54336SSakari Ailus * - variable or constant 75b9a54336SSakari Ailus - description 76b9a54336SSakari Ailus * - link_freq 77b9a54336SSakari Ailus - The value of the ``V4L2_CID_LINK_FREQ`` integer64 menu item. 78b9a54336SSakari Ailus * - nr_of_lanes 79b9a54336SSakari Ailus - Number of data lanes used on the CSI-2 link. This can 80b9a54336SSakari Ailus be obtained from the OF endpoint configuration. 81b9a54336SSakari Ailus * - 2 82b9a54336SSakari Ailus - Data is transferred on both rising and falling edge of the signal. 83b9a54336SSakari Ailus * - bits_per_sample 84b9a54336SSakari Ailus - Number of bits per sample. 85b9a54336SSakari Ailus * - k 86b9a54336SSakari Ailus - 16 for D-PHY and 7 for C-PHY 87b9a54336SSakari Ailus 88b9a54336SSakari Ailus.. note:: 89b9a54336SSakari Ailus 90b9a54336SSakari Ailus The pixel rate calculated this way is **not** the same thing as the 91b9a54336SSakari Ailus pixel rate on the camera sensor's pixel array which is indicated by the 92b9a54336SSakari Ailus :ref:`V4L2_CID_PIXEL_RATE <v4l2-cid-pixel-rate>` control. 93b9a54336SSakari Ailus 94*16be18d7SSakari AilusLP-11 and LP-111 states 95*16be18d7SSakari Ailus^^^^^^^^^^^^^^^^^^^^^^^ 96b9a54336SSakari Ailus 97013c35b2SSakari AilusAs part of transitioning to high speed mode, a CSI-2 transmitter typically 98013c35b2SSakari Ailusbriefly sets the bus to LP-11 or LP-111 state, depending on the PHY. This period 99013c35b2SSakari Ailusmay be as short as 100 µs, during which the receiver observes this state and 100013c35b2SSakari Ailusproceeds its own part of high speed mode transition. 101b9a54336SSakari Ailus 102013c35b2SSakari AilusMost receivers are capable of autonomously handling this once the software has 103013c35b2SSakari Ailusconfigured them to do so, but there are receivers which require software 104013c35b2SSakari Ailusinvolvement in observing LP-11 or LP-111 state. 100 µs is a brief period to hit 105013c35b2SSakari Ailusin software, especially when there is no interrupt telling something is 106013c35b2SSakari Ailushappening. 107b9a54336SSakari Ailus 108013c35b2SSakari AilusOne way to address this is to configure the transmitter side explicitly to LP-11 109*16be18d7SSakari Ailusor LP-111 state, which requires support from the transmitter hardware. This is 110013c35b2SSakari Ailusnot universally available. Many devices return to this state once streaming is 111013c35b2SSakari Ailusstopped while the state after power-on is LP-00 or LP-000. 112013c35b2SSakari Ailus 113013c35b2SSakari AilusThe ``.pre_streamon()`` callback may be used to prepare a transmitter for 114013c35b2SSakari Ailustransitioning to streaming state, but not yet start streaming. Similarly, the 115013c35b2SSakari Ailus``.post_streamoff()`` callback is used to undo what was done by the 116013c35b2SSakari Ailus``.pre_streamon()`` callback. The caller of ``.pre_streamon()`` is thus required 117013c35b2SSakari Ailusto call ``.post_streamoff()`` for each successful call of ``.pre_streamon()``. 118013c35b2SSakari Ailus 119013c35b2SSakari AilusIn the context of CSI-2, the ``.pre_streamon()`` callback is used to transition 120*16be18d7SSakari Ailusthe transmitter to the LP-11 or LP-111 state. This also requires powering on the 121013c35b2SSakari Ailusdevice, so this should be only done when it is needed. 122013c35b2SSakari Ailus 123*16be18d7SSakari AilusReceiver drivers that do not need explicit LP-11 or LP-111 state setup are 124*16be18d7SSakari Ailuswaived from calling the two callbacks. 125b9a54336SSakari Ailus 126b9a54336SSakari AilusStopping the transmitter 127b9a54336SSakari Ailus^^^^^^^^^^^^^^^^^^^^^^^^ 128b9a54336SSakari Ailus 129b9a54336SSakari AilusA transmitter stops sending the stream of images as a result of 130b9a54336SSakari Ailuscalling the ``.s_stream()`` callback. Some transmitters may stop the 131b9a54336SSakari Ailusstream at a frame boundary whereas others stop immediately, 132b9a54336SSakari Ailuseffectively leaving the current frame unfinished. The receiver driver 133b9a54336SSakari Ailusshould not make assumptions either way, but function properly in both 134b9a54336SSakari Ailuscases. 135