Documentation/media/v4l-drivers/vimc.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 The Virtual Media Controller Driver (vimc)
   4 ==========================================
   5
   6 The vimc driver emulates complex video hardware using the V4L2 API and the Media
   7 API. It has a capture device and three subdevices: sensor, debayer and scaler.
   8
   9 Topology
  10 --------
  11
  12 The topology is hardcoded, although you could modify it in vimc-core and
  13 recompile the driver to achieve your own topology. This is the default topology:
  14
  15 .. _vimc_topology_graph:
  16
  17 .. kernel-figure:: vimc.dot
  18     :alt:   Diagram of the default media pipeline topology
  19     :align: center
  20
  21     Media pipeline graph on vimc
  22
  23 Configuring the topology
  24 ~~~~~~~~~~~~~~~~~~~~~~~~
  25
  26 Each subdevice will come with its default configuration (pixelformat, height,
  27 width, ...). One needs to configure the topology in order to match the
  28 configuration on each linked subdevice to stream frames through the pipeline.
  29 If the configuration doesn't match, the stream will fail. The ``v4l-utils``
  30 package is a bundle of user-space applications, that comes with ``media-ctl`` and
  31 ``v4l2-ctl`` that can be used to configure the vimc configuration. This sequence
  32 of commands fits for the default topology:
  33
  34 .. code-block:: bash
  35
  36         media-ctl -d platform:vimc -V '"Sensor A":0[fmt:SBGGR8_1X8/640x480]'
  37         media-ctl -d platform:vimc -V '"Debayer A":0[fmt:SBGGR8_1X8/640x480]'
  38         media-ctl -d platform:vimc -V '"Sensor B":0[fmt:SBGGR8_1X8/640x480]'
  39         media-ctl -d platform:vimc -V '"Debayer B":0[fmt:SBGGR8_1X8/640x480]'
  40         v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=1920,height=1440
  41         v4l2-ctl -z platform:vimc -d "Raw Capture 0" -v pixelformat=BA81
  42         v4l2-ctl -z platform:vimc -d "Raw Capture 1" -v pixelformat=BA81
  43
  44 Subdevices
  45 ----------
  46
  47 Subdevices define the behavior of an entity in the topology. Depending on the
  48 subdevice, the entity can have multiple pads of type source or sink.
  49
  50 vimc-sensor:
  51         Generates images in several formats using video test pattern generator.
  52         Exposes:
  53
  54         * 1 Pad source
  55
  56 vimc-debayer:
  57         Transforms images in bayer format into a non-bayer format.
  58         Exposes:
  59
  60         * 1 Pad sink
  61         * 1 Pad source
  62
  63 vimc-scaler:
  64         Scale up the image by a factor of 3. E.g.: a 640x480 image becomes a
  65         1920x1440 image. (this value can be configured, see at
  66         `Module options`_).
  67         Exposes:
  68
  69         * 1 Pad sink
  70         * 1 Pad source
  71
  72 vimc-capture:
  73         Exposes node /dev/videoX to allow userspace to capture the stream.
  74         Exposes:
  75
  76         * 1 Pad sink
  77         * 1 Pad source
  78
  79 Module options
  80 ---------------
  81
  82 Vimc has a few module parameters to configure the driver. You should pass
  83 those arguments to each subdevice, not to the vimc module. For example::
  84
  85         vimc_subdevice.param=value
  86
  87 * ``vimc_scaler.sca_mult=<unsigned int>``
  88
  89         Image size multiplier factor to be used to multiply both width and
  90         height, so the image size will be ``sca_mult^2`` bigger than the
  91         original one. Currently, only supports scaling up (the default value
  92         is 3).
  93
  94 * ``vimc_debayer.deb_mean_win_size=<unsigned int>``
  95
  96         Window size to calculate the mean. Note: the window size needs to be an
  97         odd number, as the main pixel stays in the center of the window,
  98         otherwise the next odd number is considered (the default value is 3).
  99
 100 Source code documentation
 101 -------------------------
 102
 103 vimc-streamer
 104 ~~~~~~~~~~~~~
 105
 106 .. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.h
 107    :internal:
 108
 109 .. kernel-doc:: drivers/media/platform/vimc/vimc-streamer.c