| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
.. _transmitter-receiver: |
| 4 |
|
| 5 |
Pixel data transmitter and receiver drivers |
| 6 |
=========================================== |
| 7 |
|
| 8 |
V4L2 supports various devices that transmit and receive pixel data. Examples of |
| 9 |
these devices include a camera sensor, a TV tuner and a parallel, a BT.656 or a |
| 10 |
CSI-2 receiver in an SoC. |
| 11 |
|
| 12 |
Bus types |
| 13 |
--------- |
| 14 |
|
| 15 |
The following buses are the most common. This section discusses these two only. |
| 16 |
|
| 17 |
MIPI CSI-2 |
| 18 |
^^^^^^^^^^ |
| 19 |
|
| 20 |
CSI-2 is a data bus intended for transferring images from cameras to |
| 21 |
the host SoC. It is defined by the `MIPI alliance`_. |
| 22 |
|
| 23 |
.. _`MIPI alliance`: https://www.mipi.org/ |
| 24 |
|
| 25 |
Parallel and BT.656 |
| 26 |
^^^^^^^^^^^^^^^^^^^ |
| 27 |
|
| 28 |
The parallel and `BT.656`_ buses transport one bit of data on each clock cycle |
| 29 |
per data line. The parallel bus uses synchronisation and other additional |
| 30 |
signals whereas BT.656 embeds synchronisation. |
| 31 |
|
| 32 |
.. _`BT.656`: https://en.wikipedia.org/wiki/ITU-R_BT.656 |
| 33 |
|
| 34 |
Transmitter drivers |
| 35 |
------------------- |
| 36 |
|
| 37 |
Transmitter drivers generally need to provide the receiver drivers with the |
| 38 |
configuration of the transmitter. What is required depends on the type of the |
| 39 |
bus. These are common for both buses. |
| 40 |
|
| 41 |
Media bus pixel code |
| 42 |
^^^^^^^^^^^^^^^^^^^^ |
| 43 |
|
| 44 |
See :ref:`v4l2-mbus-pixelcode`. |
| 45 |
|
| 46 |
Link frequency |
| 47 |
^^^^^^^^^^^^^^ |
| 48 |
|
| 49 |
The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the |
| 50 |
receiver the frequency of the bus (i.e. it is not the same as the symbol rate). |
| 51 |
|
| 52 |
Drivers that do not have user-configurable link frequency should report it |
| 53 |
through the ``.get_mbus_config()`` subdev pad operation, in the ``link_freq`` |
| 54 |
field of struct v4l2_mbus_config, instead of through controls. |
| 55 |
|
| 56 |
Receiver drivers should use :c:func:`v4l2_get_link_freq` helper to obtain the |
| 57 |
link frequency from the transmitter sub-device. |
| 58 |
|
| 59 |
``.enable_streams()`` and ``.disable_streams()`` callbacks |
| 60 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 61 |
|
| 62 |
The struct v4l2_subdev_pad_ops->enable_streams() and struct |
| 63 |
v4l2_subdev_pad_ops->disable_streams() callbacks are used by the receiver driver |
| 64 |
to control the transmitter driver's streaming state. These callbacks may not be |
| 65 |
called directly, but by using ``v4l2_subdev_enable_streams()`` and |
| 66 |
``v4l2_subdev_disable_streams()``. |
| 67 |
|
| 68 |
Stopping the transmitter |
| 69 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
| 70 |
|
| 71 |
A transmitter stops sending the stream of images as a result of |
| 72 |
calling the ``.disable_streams()`` callback. Some transmitters may stop the |
| 73 |
stream at a frame boundary whereas others stop immediately, |
| 74 |
effectively leaving the current frame unfinished. The receiver driver |
| 75 |
should not make assumptions either way, but function properly in both |
| 76 |
cases. |
| 77 |
|
| 78 |
CSI-2 transmitter drivers |
| 79 |
------------------------- |
| 80 |
|
| 81 |
Pixel rate |
| 82 |
^^^^^^^^^^ |
| 83 |
|
| 84 |
The pixel rate on the bus is calculated as follows:: |
| 85 |
|
| 86 |
pixel_rate = link_freq * 2 * nr_of_lanes * 16 / k / bits_per_sample |
| 87 |
|
| 88 |
where |
| 89 |
|
| 90 |
.. list-table:: variables in pixel rate calculation |
| 91 |
:header-rows: 1 |
| 92 |
|
| 93 |
* - variable or constant |
| 94 |
- description |
| 95 |
* - link_freq |
| 96 |
- The value of the ``V4L2_CID_LINK_FREQ`` integer64 menu item. |
| 97 |
* - nr_of_lanes |
| 98 |
- Number of data lanes used on the CSI-2 link. |
| 99 |
* - 2 |
| 100 |
- Data is transferred on both rising and falling edge of the signal. |
| 101 |
* - bits_per_sample |
| 102 |
- Number of bits per sample. |
| 103 |
* - k |
| 104 |
- 16 for D-PHY and 7 for C-PHY. |
| 105 |
|
| 106 |
Information on whether D-PHY or C-PHY is used, and the value of ``nr_of_lanes``, can be obtained from the OF endpoint configuration. |
| 107 |
|
| 108 |
.. note:: |
| 109 |
|
| 110 |
The pixel rate calculated this way is **not** the same thing as the |
| 111 |
pixel rate on the camera sensor's pixel array which is indicated by the |
| 112 |
:ref:`V4L2_CID_PIXEL_RATE <v4l2-cid-pixel-rate>` control. |
| 113 |
|
| 114 |
LP-11 and LP-111 states |
| 115 |
^^^^^^^^^^^^^^^^^^^^^^^ |
| 116 |
|
| 117 |
As part of transitioning to high speed mode, a CSI-2 transmitter typically |
| 118 |
briefly sets the bus to LP-11 or LP-111 state, depending on the PHY. This period |
| 119 |
may be as short as 100 µs, during which the receiver observes this state and |
| 120 |
proceeds its own part of high speed mode transition. |
| 121 |
|
| 122 |
Most receivers are capable of autonomously handling this once the software has |
| 123 |
configured them to do so, but there are receivers which require software |
| 124 |
involvement in observing LP-11 or LP-111 state. 100 µs is a brief period to hit |
| 125 |
in software, especially when there is no interrupt telling something is |
| 126 |
happening. |
| 127 |
|
| 128 |
One way to address this is to configure the transmitter side explicitly to LP-11 |
| 129 |
or LP-111 state, which requires support from the transmitter hardware. This is |
| 130 |
not universally available. Many devices return to this state once streaming is |
| 131 |
stopped while the state after power-on is LP-00 or LP-000. |
| 132 |
|
| 133 |
The ``.pre_streamon()`` callback may be used to prepare a transmitter for |
| 134 |
transitioning to streaming state, but not yet start streaming. Similarly, the |
| 135 |
``.post_streamoff()`` callback is used to undo what was done by the |
| 136 |
``.pre_streamon()`` callback. The caller of ``.pre_streamon()`` is thus required |
| 137 |
to call ``.post_streamoff()`` for each successful call of ``.pre_streamon()``. |
| 138 |
|
| 139 |
In the context of CSI-2, the ``.pre_streamon()`` callback is used to transition |
| 140 |
the transmitter to the LP-11 or LP-111 state. This also requires powering on the |
| 141 |
device, so this should be only done when it is needed. |
| 142 |
|
| 143 |
Receiver drivers that do not need explicit LP-11 or LP-111 state setup are |
| 144 |
waived from calling the two callbacks. |