Documentation/admin-guide/media/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 '"Scaler":0[fmt:RGB888_1X24/640x480]'
  39         media-ctl -d platform:vimc -V '"Scaler":0[crop:(100,50)/400x150]'
  40         media-ctl -d platform:vimc -V '"Scaler":1[fmt:RGB888_1X24/300x700]'
  41         v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=300,height=700
  42         v4l2-ctl -z platform:vimc -d "Raw Capture 0" -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-lens:
  57         Ancillary lens for a sensor. Supports auto focus control. Linked to
  58         a vimc-sensor using an ancillary link. The lens supports FOCUS_ABSOLUTE
  59         control.
  60
  61 .. code-block:: bash
  62
  63         media-ctl -p
  64         ...
  65         - entity 28: Lens A (0 pad, 0 link)
  66                         type V4L2 subdev subtype Lens flags 0
  67                         device node name /dev/v4l-subdev6
  68         - entity 29: Lens B (0 pad, 0 link)
  69                         type V4L2 subdev subtype Lens flags 0
  70                         device node name /dev/v4l-subdev7
  71         v4l2-ctl -d /dev/v4l-subdev7 -C focus_absolute
  72         focus_absolute: 0
  73
  74
  75 vimc-debayer:
  76         Transforms images in bayer format into a non-bayer format.
  77         Exposes:
  78
  79         * 1 Pad sink
  80         * 1 Pad source
  81
  82 vimc-scaler:
  83         Re-size the image to meet the source pad resolution. E.g.: if the sync
  84         pad is configured to 360x480 and the source to 1280x720, the image will
  85         be stretched to fit the source resolution. Works for any resolution
  86         within the vimc limitations (even shrinking the image if necessary).
  87         Exposes:
  88
  89         * 1 Pad sink
  90         * 1 Pad source
  91
  92 vimc-capture:
  93         Exposes node /dev/videoX to allow userspace to capture the stream.
  94         Exposes:
  95
  96         * 1 Pad sink
  97         * 1 Pad source
  98
  99 Module options
 100 --------------
 101
 102 Vimc has a module parameter to configure the driver.
 103
 104 * ``allocator=<unsigned int>``
 105
 106         memory allocator selection, default is 0. It specifies the way buffers
 107         will be allocated.
 108
 109                 - 0: vmalloc
 110                 - 1: dma-contig