media: docs: create vimc documentation

Create vimc documentation file to explain its basic features, its
topology, how to configure it and to document vimc's subdevices.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Suggested-by: Helen Koike <helen.koike@collabora.com>
[hverkuil-cisco@xs4all.nl: Fix typo: The ``v4l2-utils`` -> The ``v4l-utils`` package]
Signed-off-by: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
André Almeida 2019-06-15 22:09:59 -04:00 committed by Mauro Carvalho Chehab
parent bfa69bdf34
commit 03f4175bd0
3 changed files with 121 additions and 0 deletions

View File

@ -64,5 +64,6 @@ For more details see the file COPYING in the source distribution of Linux.
si476x
soc-camera
uvcvideo
vimc
vivid
zr364xx

View File

@ -0,0 +1,22 @@
# SPDX-License-Identifier: GPL-2.0
digraph board {
rankdir=TB
n00000001 [label="{{} | Sensor A\n/dev/v4l-subdev0 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
n00000001:port0 -> n00000005:port0 [style=bold]
n00000001:port0 -> n0000000b [style=bold]
n00000003 [label="{{} | Sensor B\n/dev/v4l-subdev1 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
n00000003:port0 -> n00000008:port0 [style=bold]
n00000003:port0 -> n0000000f [style=bold]
n00000005 [label="{{<port0> 0} | Debayer A\n/dev/v4l-subdev2 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
n00000005:port1 -> n00000017:port0
n00000008 [label="{{<port0> 0} | Debayer B\n/dev/v4l-subdev3 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
n00000008:port1 -> n00000017:port0 [style=dashed]
n0000000b [label="Raw Capture 0\n/dev/video0", shape=box, style=filled, fillcolor=yellow]
n0000000f [label="Raw Capture 1\n/dev/video1", shape=box, style=filled, fillcolor=yellow]
n00000013 [label="RGB/YUV Input\n/dev/video2", shape=box, style=filled, fillcolor=yellow]
n00000013 -> n00000017:port0 [style=dashed]
n00000017 [label="{{<port0> 0} | Scaler\n/dev/v4l-subdev4 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
n00000017:port1 -> n0000001a [style=bold]
n0000001a [label="RGB/YUV Capture\n/dev/video3", shape=box, style=filled, fillcolor=yellow]
}

View File

@ -0,0 +1,98 @@
.. SPDX-License-Identifier: GPL-2.0
The Virtual Media Controller Driver (vimc)
==========================================
The vimc driver emulates complex video hardware using the V4L2 API and the Media
API. It has a capture device and three subdevices: sensor, debayer and scaler.
Topology
--------
The topology is hardcoded, although you could modify it in vimc-core and
recompile the driver to achieve your own topology. This is the default topology:
.. _vimc_topology_graph:
.. kernel-figure:: vimc.dot
:alt: vimc.dot
:align: center
Media pipeline graph on vimc
Configuring the topology
~~~~~~~~~~~~~~~~~~~~~~~~
Each subdevice will come with its default configuration (pixelformat, height,
width, ...). One needs to configure the topology in order to match the
configuration on each linked subdevice to stream frames through the pipeline.
If the configuration doesn't match, the stream will fail. The ``v4l-utils``
package is a bundle of user-space applications, that comes with ``media-ctl`` and
``v4l2-ctl`` that can be used to configure the vimc configuration. This sequence
of commands fits for the default topology:
.. code-block:: bash
media-ctl -d platform:vimc -V '"Sensor A":0[fmt:SBGGR8_1X8/640x480]'
media-ctl -d platform:vimc -V '"Debayer A":0[fmt:SBGGR8_1X8/640x480]'
media-ctl -d platform:vimc -V '"Sensor B":0[fmt:SBGGR8_1X8/640x480]'
media-ctl -d platform:vimc -V '"Debayer B":0[fmt:SBGGR8_1X8/640x480]'
v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=1920,height=1440
v4l2-ctl -z platform:vimc -d "Raw Capture 0" -v pixelformat=BA81
v4l2-ctl -z platform:vimc -d "Raw Capture 1" -v pixelformat=BA81
Subdevices
----------
Subdevices define the behavior of an entity in the topology. Depending on the
subdevice, the entity can have multiple pads of type source or sink.
vimc-sensor:
Generates images in several formats using video test pattern generator.
Exposes:
* 1 Pad source
vimc-debayer:
Transforms images in bayer format into a non-bayer format.
Exposes:
* 1 Pad sink
* 1 Pad source
vimc-scaler:
Scale up the image by a factor of 3. E.g.: a 640x480 image becomes a
1920x1440 image. (this value can be configured, see at
`Module options`_).
Exposes:
* 1 Pad sink
* 1 Pad source
vimc-capture:
Exposes node /dev/videoX to allow userspace to capture the stream.
Exposes:
* 1 Pad sink
* 1 Pad source
Module options
---------------
Vimc has a few module parameters to configure the driver. You should pass
those arguments to each subdevice, not to the vimc module. For example::
vimc_subdevice.param=value
* ``vimc_scaler.sca_mult=<unsigned int>``
Image size multiplier factor to be used to multiply both width and
height, so the image size will be ``sca_mult^2`` bigger than the
original one. Currently, only supports scaling up (the default value
is 3).
* ``vimc_debayer.deb_mean_win_size=<unsigned int>``
Window size to calculate the mean. Note: the window size needs to be an
odd number, as the main pixel stays in the center of the window,
otherwise the next odd number is considered (the default value is 3).