Documentation/media/kapi/csi2.rst

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