1.. SPDX-License-Identifier: GPL-2.0
  2
  3The Virtual Media Controller Driver (vimc)
  4==========================================
  5
  6The vimc driver emulates complex video hardware using the V4L2 API and the Media
  7API. It has a capture device and three subdevices: sensor, debayer and scaler.
  8
  9Topology
 10--------
 11
 12The topology is hardcoded, although you could modify it in vimc-core and
 13recompile 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
 23Configuring the topology
 24~~~~~~~~~~~~~~~~~~~~~~~~
 25
 26Each subdevice will come with its default configuration (pixelformat, height,
 27width, ...). One needs to configure the topology in order to match the
 28configuration on each linked subdevice to stream frames through the pipeline.
 29If the configuration doesn't match, the stream will fail. The ``v4l-utils``
 30package 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
 32of 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
 44Subdevices
 45----------
 46
 47Subdevices define the behavior of an entity in the topology. Depending on the
 48subdevice, the entity can have multiple pads of type source or sink.
 49
 50vimc-sensor:
 51	Generates images in several formats using video test pattern generator.
 52	Exposes:
 53
 54	* 1 Pad source
 55
 56vimc-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
 75vimc-debayer:
 76	Transforms images in bayer format into a non-bayer format.
 77	Exposes:
 78
 79	* 1 Pad sink
 80	* 1 Pad source
 81
 82vimc-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
 92vimc-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
 99Module options
100--------------
101
102Vimc 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