Re: [PATCH v2 1/1] doc-rst: v4l: Add documentation on CSI-2 bus configuration

[Philipp Zabel <p.zabel@pengutronix.de>]

Am Mittwoch, den 19.10.2016, 15:59 +0300 schrieb Sakari Ailus:
> Document the interface between the CSI-2 transmitter and receiver drivers.
> 
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
> Hi Philipp,
> 
> Indeed the pixel rate is used by some driver as well.
> 
> How about this one instead?
> 
> The HTML page is available here (without CCS unfortunately):
> 
> <URL:http://www.retiisi.org.uk/v4l2/tmp/csi2.html>
> 
> since v1:
>  
> - Add PIXEL_RATE to the required controls.
> 
> - Document how pixel rate is calculated from the link frequency.
> 
>  Documentation/media/kapi/csi2.rst  | 59 ++++++++++++++++++++++++++++++++++++++
>  Documentation/media/media_kapi.rst |  1 +
>  2 files changed, 60 insertions(+)
>  create mode 100644 Documentation/media/kapi/csi2.rst
> 
> diff --git a/Documentation/media/kapi/csi2.rst b/Documentation/media/kapi/csi2.rst
> new file mode 100644
> index 0000000..31f927d
> --- /dev/null
> +++ b/Documentation/media/kapi/csi2.rst
> @@ -0,0 +1,59 @@
> +MIPI CSI-2
> +==========
> +
> +CSI-2 is a data bus intended for transferring images from cameras to
> +the host SoC. It is defined by the `MIPI alliance`_.
> +
> +.. _`MIPI alliance`: http://www.mipi.org/
> +
> +Transmitter drivers
> +-------------------
> +
> +CSI-2 transmitter, such as a sensor or a TV tuner, drivers need to
> +provide the CSI-2 receiver with information on the CSI-2 bus
> +configuration. These include the V4L2_CID_LINK_FREQ and
> +V4L2_CID_PIXEL_RATE controls and
> +(:c:type:`v4l2_subdev_video_ops`->s_stream() callback). These
> +interface elements must be present on the sub-device represents the
> +CSI-2 transmitter.
> +
> +The V4L2_CID_LINK_FREQ control is used to tell the receiver driver the
> +frequency (and not the symbol rate) of the link. The
> +V4L2_CID_PIXEL_RATE is may be used by the receiver to obtain the pixel
> +rate the transmitter uses. The
> +:c:type:`v4l2_subdev_video_ops`->s_stream() callback provides an
> +ability to start and stop the stream.
> +
> +The value of the V4L2_CID_PIXEL_RATE is calculated as follows::
> +
> +	pixel_rate = link_freq * 2 * nr_of_lanes

This is the total bps, which must be divided by the bits per pixel
depending on the selected MEDIA_BUS_FMT, for example
/16 for MEDIA_BUS_FMT_UYVY8_1X16, or /24 for MEDIA_BUS_FMT_RGB888_1X24,
to obtain pixel_rate.

> +where
> +
> +.. list-table:: variables in pixel rate calculation
> +   :header-rows: 1
> +
> +   * - variable or constant
> +     - description
> +   * - link_freq
> +     - The value of the V4L2_CID_LINK_FREQ integer64 menu item.
> +   * - nr_of_lanes
> +     - Number of data lanes used on the CSI-2 link. This can
> +       be obtained from the OF endpoint configuration.

I suppose the number of lanes should be calculated as
	nr_of_lanes = DIV_ROUND_UP(pixel_rate * bpp, link_freq * 2)
in the receiver driver? Not all lanes configured in the device tree have
to be used, depending on the configured link frequencies and bus format.

> +   * - 2
> +     - Two bits are transferred per clock cycle per lane.
> +
> +The transmitter drivers must configure the CSI-2 transmitter to *LP-11
> +mode* whenever the transmitter is powered on but not active. Some
> +transmitters do this automatically but some have to be explicitly
> +programmed to do so.
> +
> +Receiver drivers
> +----------------
> +
> +Before the receiver driver may enable the CSI-2 transmitter by using
> +the :c:type:`v4l2_subdev_video_ops`->s_stream(), it must have powered
> +the transmitter up by using the
> +:c:type:`v4l2_subdev_core_ops`->s_power() callback. This may take
> +place either indirectly by using :c:func:`v4l2_pipeline_pm_use` or
> +directly.
> diff --git a/Documentation/media/media_kapi.rst b/Documentation/media/media_kapi.rst
> index f282ca2..bc06389 100644
> --- a/Documentation/media/media_kapi.rst
> +++ b/Documentation/media/media_kapi.rst
> @@ -33,3 +33,4 @@ For more details see the file COPYING in the source distribution of Linux.
>      kapi/rc-core
>      kapi/mc-core
>      kapi/cec-core
> +    kapi/csi2

regards
Philipp