GNU Linux-libre 6.1.91-gnu
[releases.git] / 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 '"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-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