From bd579a7d748bd88b0882691bfb2084511501871e Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Sun, 11 Sep 2022 03:16:33 +0300 Subject: Add first version of the documentation Signed-off-by: Laurent Pinchart --- .gitignore | 1 + Makefile | 20 ++ _static/.keep | 0 _templates/.keep | 0 conf.py | 28 ++ configuring-pipelines.rst | 759 +++++++++++++++++++++++++++++++++++++++++++ imx8mp-isp-links-enabled.dot | 17 + imx8mp-isp.dot | 17 + index.rst | 14 + introduction.rst | 117 +++++++ mc-v4l2-api.rst | 289 ++++++++++++++++ omap3isp.dot | 36 ++ scaler-fast.dot | 13 + scaler-hq.dot | 13 + scaler.dot | 28 ++ subdev.svg | 456 ++++++++++++++++++++++++++ 16 files changed, 1808 insertions(+) create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 _static/.keep create mode 100644 _templates/.keep create mode 100644 conf.py create mode 100644 configuring-pipelines.rst create mode 100644 imx8mp-isp-links-enabled.dot create mode 100644 imx8mp-isp.dot create mode 100644 index.rst create mode 100644 introduction.rst create mode 100644 mc-v4l2-api.rst create mode 100644 omap3isp.dot create mode 100644 scaler-fast.dot create mode 100644 scaler-hq.dot create mode 100644 scaler.dot create mode 100644 subdev.svg diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..69fa449 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/_static/.keep b/_static/.keep new file mode 100644 index 0000000..e69de29 diff --git a/_templates/.keep b/_templates/.keep new file mode 100644 index 0000000..e69de29 diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..807faa4 --- /dev/null +++ b/conf.py @@ -0,0 +1,28 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Media Controller & V4L2 documentation' +copyright = '2022, Laurent Pinchart' +author = 'Laurent Pinchart ' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['sphinx.ext.graphviz', 'sphinx.ext.imgconverter'] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +graphviz_output_format = 'svg' +pygments_style = 'default' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'bizstyle' +html_static_path = ['_static'] diff --git a/configuring-pipelines.rst b/configuring-pipelines.rst new file mode 100644 index 0000000..440be2a --- /dev/null +++ b/configuring-pipelines.rst @@ -0,0 +1,759 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Configuring Pipelines +===================== + +Allowing fine-grained control of formats comes at the cost of increasing +complexity for applications. Where an application used to only have to set the +format on a video device, it must now set formats on all pads in the pipeline, +and ensure that the result forms a coherent configuration. + +As previously stated, the examples in this section will be based on the NXP +i.MX8MP ISP device: + +.. graphviz:: imx8mp-isp.dot + :caption: Media graph of the NXP i.MX8MP with default configuration + + +Anatomy of a Pipeline +--------------------- + +.. _media-ctl: https://git.linuxtv.org/v4l-utils.git/tree/utils/media-ctl +.. _v4l2-ctl: https://git.linuxtv.org/v4l-utils.git/tree/utils/v4l2-ctl + +The `media-ctl`_ utility can be used to display the formats on all pads in a +graph. Let's start by disecting the output of ``media-ctl -d /dev/media0 -p``: + +.. code-block:: none + :linenos: + :lineno-start: 1 + + $ media-ctl -d /dev/media0 -p + Media controller API version 6.0.0 + + Media device information + ------------------------ + driver rkisp1 + model rkisp1 + serial + bus info platform:rkisp1 + hw revision 0xe + driver version 6.0.0 + +media-ctl first provides summary information, to quickly identify the hardware +device corresponding to the media controller device (``/dev/media0`` here): + +- the driver name +- the device model name +- the device serial number (when available) +- which bus the device sits on +- the device hardware revision (in a device-specific format) +- the driver version (identical to the kernel version) + +The ISP integrated in the NXP i.MX8MP is also found in Rockchip SoCs. They are +both handled by the ``rkisp1`` kernel driver, as shown by the driver and device +model names. + +media-ctl then prints detailed information for all entities in the graph. +Entities are sorted by their numerical ID, which doesn't necessarily follow any +logical order. To improve readability, the entities below have been reordered +in source to sink order, as shown by the line numbers. This corresponds to the +top to bottom order in the graphical representation of the media graph. + +.. code-block:: none + :linenos: + :lineno-start: 73 + + - entity 34: imx290 2-001a (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SRGGB10_1X10/1920x1080 field:none + crop.bounds:(0,0)/1945x1097 + crop:(12,8)/1920x1080] + -> "csis-32e40000.csi":0 [] + +All entities have a numerical ID and a name. The first entity in pipeline order +has ID ``34`` and is named ``imx290 2-001a``. Names are chosen by drivers but +should follow a set of naming rules. For devices controlled through an I2C bus, +as is the case here, the entity name is made of the device model (``imx290``) +and bus information (``2-001a``) separated by a space. The I2C bus information +is itself made of the bus number and the device address (in hexadecimal), +separated by a dash. + +This particular entity has a total of 1 pad and 1 link (line 73). It is a V4L2 +subdevice whose subtype is a camera sensor (line 74). The subdevice is exposed +to userspace through the ``/dev/v4l-subdev3`` device node (line 75). + +For each pad of the entity media-ctl then displays the pad index and type, the +available links, as well as pad information specific to the entity type. Pad +indices start at 0. The IMX290 camera sensor entity has a single pad, thus at +index 0 and named ``pad0``, whose type is a source pad (line 76). + +Links are displayed on lines starting with a ``->`` (for outbound links, on +source pads) or ``<-`` (for inbound links, on sink pads) sign, followed by the +link target (``"csis-32e40000.csi":0``) and link flags (``[]``). The link +target is a pad of another entity, expressed as the target entity name +surrounded by double quotes, followed by a colon and the target pad index. The +supported link flags (with their numerical values) are: + +ENABLED (0x1) + The link is enabled. In the absence of this flag, the link is disabled. + +IMMUTABLE (0x2) + The link is immutable, its ``ENABLED`` flag cannot be modified. Immutable + links in practice always have the ``ENABLED`` flag set. + +As the list of link flags is empty, this specific link is thus disabled, but +can be enabled as it isn't immutable. The graphical representation displays +this link as a dotted line. + +We will ignore for now the pad information specific to the entity type +displayed on lines 77 to 79, this will be explained further down. + +The next entity, in graph order, is the MIPI CSI-2 receiver that the camera +sensor is attached to: + +.. code-block:: none + :linenos: + :lineno-start: 64 + + - entity 29: csis-32e40000.csi (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev2 + pad0: Sink + [fmt:UYVY8_1X16/640x480 field:none colorspace:smpte170m xfer:709 ycbcr:601 quantization:lim-range] + <- "imx290 2-001a":0 [] + pad1: Source + [fmt:UYVY8_1X16/640x480 field:none colorspace:smpte170m xfer:709 ycbcr:601 quantization:lim-range] + -> "rkisp1_isp":0 [ENABLED] + +The CSI-2 receiver is an IP core internal to the SoC, modelled in the kernel as +a platform device. Entity names from platform devices are more free-formed. In +this case, the driver follows the usual recommendation, which uses the platform +device model name (``csis``) and the platform device name (``32e40000.csi``), +separated by a dash. On machines using Device Tree to describe the system (as +is the case on ARM and ARM64 machines), the platform device name is typically +make of the device's bus address (``32e40000``) and device node name (``csi``). + +This entity has two pads, a sink pad and a source pad, with one link each. The +sink pad, ``pad0`` (line 67), is the target of the link originating from the +camera sensor, and is thus without surprise displayed as connected to the +source pad of the camera sensor (line 69). The link flags being a property of +the link, not the pad, they match the link flags displayed in the camera sensor +entity. + +The source pad, ``pad1`` (line 70), is connected to pad 0 of the ``rkisp1_isp`` +entity (line 72). This link is enabled but not immutable, thus displayed as a +thin plain line in the graphical representation. + +The next entity represents the core of the ISP itself: + +.. code-block:: none + :linenos: + :lineno-start: 14 + + - entity 1: rkisp1_isp (4 pads, 4 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SRGGB10_1X10/800x600 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range + crop.bounds:(0,0)/800x600 + crop:(0,0)/800x600] + <- "csis-32e40000.csi":1 [ENABLED] + pad1: Sink + [fmt:unknown/0x0 field:none] + <- "rkisp1_params":0 [ENABLED,IMMUTABLE] + pad2: Source + [fmt:YUYV8_2X8/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:lim-range + crop.bounds:(0,0)/800x600 + crop:(0,0)/800x600] + -> "rkisp1_resizer_mainpath":0 [ENABLED] + pad3: Source + [fmt:unknown/0x0 field:none] + -> "rkisp1_stats":0 [ENABLED,IMMUTABLE] + +Its name doesn't follow the previously described recommendation for entities +corresponding to platform devices, which shows that applications can't rely on +a particular format for entity names in general. This may be considered as a +kernel bug, but is unlikely to be changed as entity name changes may break +existing applications. + +This entity is also a V4L2 subdevice, with four pads, two sink pads (``pad0`` +and ``pad1`` on lines 17 and 22 respectively) and two source pads (``pad2`` and +``pad3`` on lines 25 and 30). Pads 1 and 3 are connected to entities +representing the video device nodes through which ISP parameters are supplied +and ISP statistics are captured. We will ignore them in this example as they +are not strictly required to operate the device. It is however worth noting +that the corresponding links are enabled and immutable, and thus displayed in +the graphical representation as thich plain lines. + +Pad 2 is a source pad that connects the ISP core to the resizer, which is the +next entity in the pipeline. + +.. code-block:: none + :linenos: + :lineno-start: 34 + + - entity 6: rkisp1_resizer_mainpath (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev1 + pad0: Sink + [fmt:YUYV8_2X8/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:lim-range + crop.bounds:(0,0)/800x600 + crop:(0,0)/800x600] + <- "rkisp1_isp":2 [ENABLED] + pad1: Source + [fmt:YUYV8_2X8/800x600 field:none colorspace:srgb xfer:srgb ycbcr:601 quantization:lim-range] + -> "rkisp1_mainpath":0 [ENABLED,IMMUTABLE] + +The resizer is also a V4L2 subdevice, and has nothing noteworthy at this point +compared to the entities previously described. Its source pad (line 42) is +connected to the last entity in the pipeline: + +.. code-block:: none + :linenos: + :lineno-start: 46 + + - entity 9: rkisp1_mainpath (1 pad, 1 link) + type Node subtype V4L flags 0 + device node name /dev/video0 + pad0: Sink + <- "rkisp1_resizer_mainpath":1 [ENABLED,IMMUTABLE] + +The ``rkisp1_mainpath`` entity, unlike all previous entities, is not a V4L2 +subdevice but a V4L2 video node (line 47). Its device node name is +``/dev/video0`` (line 48), corresponding to the output of the pipeline. This is +the device node from which frames originating from the sensor, processed by the +ISP, and scaled by the resizer are captured. + +Let's try to capture frames in NV16 format with a 800x600 resolution: + +.. code-block:: none + :emphasize-lines: 2 + + $ v4l2-ctl -d /dev/video0 -v pixelformat=NV16,width=800,height=600 --stream-count 10 --stream-mmap + VIDIOC_STREAMON returned -1 (Broken pipe) + +The kernel driver returns the `Broken pipe` error code, which indicates that +the pipeline isn't properly configured. The first possibly culprit to +investigate is the links. + + +Link Setup +---------- + +.. _EBNF metasyntax: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form + +We have seen that, unless immutable, links can be enabled or disabled. Enabling +or disabling links allows configuring data routing through the graph. For +instance, a device that has multiple camera sensors connected to an ISP, but +can only capture from one of the sensors at a time, could be controlled by +enabling one of the links from the camera sensors to select the source. + +In the default configuration of the device, the link from the camera sensor to +the CSI-2 receiver is disabled. The pipeline is thus missing a source, which +causes the capture to fail with the `Broken pipe` error. To fix this, links +must be setup before starting capture. This is done with the media-ctl utility: + +.. code-block:: none + + $ media-ctl -d /dev/media0 --link '"imx290 2-001a":0 -> "csis-32e40000.csi":0 [1]' + +The ``-link`` option (or its shorter form ``-l``) takes a list of links, +expressed as follows (using a syntax close to the `EBNF metasyntax`_, found in +the output of ``media-ctl --help``): + +.. code-block:: ebnf + + links = link { ',' link } ; + link = pad '->' pad '[' flags ']' ; + pad = entity ':' pad-number ; + entity = entity-number | ( '"' entity-name '"' ) ; + +In the above example, we enable (``[1]``) the link from the source pad of the +camera sensor entity (``'"imx290 2-001a":0``) to the sink pad of the CSI-2 +receiver entity (``"csis-32e40000.csi":0``). Links can also be disabled by +clearing the ENABLED flag (using ``[0]``), and multiple links can be setup with +a single command, although this is discouraged in scripts as the resulting +syntax would be hard to read. + +After running the above command, ``media-ctl -p`` reports the link between the +camera sensor and the CSI-2 receiver as enabled: + +.. code-block:: none + :linenos: + :lineno-start: 73 + :emphasize-lines: 8 + + - entity 34: imx290 2-001a (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SRGGB10_1X10/1920x1080 field:none + crop.bounds:(0,0)/1945x1097 + crop:(12,8)/1920x1080] + -> "csis-32e40000.csi":0 [ENABLED] + +This is also displayed in the graphical representation, with the corresponding +link now being a thin plain line instead of a dotted line: + +.. graphviz:: imx8mp-isp-links-enabled.dot + :caption: Media graph of the NXP i.MX8MP after enabling links + +.. note:: + + It is recommended, before setting up links in a pipeline, to reset all + non-immutable links to their disabled state with ``media-ctl --reset``. This + helps starting from a known state and, and avoids depending on a previous + configuration of the media graph. In this specific example, the links + between the CSI-2 receiver and the ISP, and between the ISP and the resizer, + would get disabled, and would need to be enabled manually to create a + complete pipeline. + +Let's try to capture frames in NV16 format with a 800x600 resolution again: + +.. code-block:: none + :emphasize-lines: 2 + + $ v4l2-ctl -d /dev/video0 -v pixelformat=NV16,width=800,height=600 --stream-count 10 --stream-mmap + VIDIOC_STREAMON returned -1 (Broken pipe) + +The kernel still returns the `Broken pipe` error, for an entirely different +reason: we haven't taken care of formats in the pipeline. + + +Formats in the Pipeline +----------------------- + +.. _Media Bus Format: https://linuxtv.org/downloads/v4l-dvb-apis/userspace-api/v4l/subdev-formats.html> + +It is time to stop ignoring the pad information specific to the entity type +that is printed by media-ctl. Let's have a look at the camera sensor entity +again: + +.. code-block:: none + :linenos: + :lineno-start: 73 + :emphasize-lines: 5-7 + + - entity 34: imx290 2-001a (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SRGGB10_1X10/1920x1080 field:none + crop.bounds:(0,0)/1945x1097 + crop:(12,8)/1920x1080] + -> "csis-32e40000.csi":0 [ENABLED] + +For entities corresponding to V4L2 subdevices, media-ctl prints the active +configuration for each pad (lines 68 to 78). The configuration is made of +multiple properties: + +- The media bus format, expressed as + + .. code-block:: ebnf + + media bus format = "fmt:", fcc, "/", size ; + size = width, "x", height ; + + where ``fcc`` is the `media bus format`_ code. Format codes are listed in the + ``linux/media-bus-format.h`` header file of the Linux kernel, and expressed + here as a string without the ``MEDIA_BUS_FMT_`` prefix. + +- The field, for interlaced video: + + .. code-block:: ebnf + + field = "field:", v4l2-field ; + v4l2-field = "any" | "none" | "top" | "bottom" | "interlaced" + | "seq-tb" | "seq-bt" | "alternate" | "interlaced-tb" + | "interlaced-bt" ; + +- The color space, expressed as four properties, reporting the V4L2 color + space, transfer function, YCbCr encoding and quantization range: + + .. code-block:: ebnf + + color space = "colorspace:", v4l2-colorspace, " xfer:", v4l2-xfer-func, + " ycbcr:", v4l2-ycbcr-enc, " quantization:", v4l2-quant ; + v4l2-colorspace = "default" | "smpte170m" | "smpte240m" | "rec709" + | "470m" | "470bg" | "jpeg" | "srgb" | "oprgb" | "bt2020" + | "raw" | "dcip3" ; + v4l2-xfer-func = "default" | "709" | "srgb" | "oprgb" | "smpte240m" + | "smpte2084" | "dcip3" | "none" ; + v4l2-ycbcr-enc = "default" | "601" | "709" | "xv601" | "xv709" | "bt2020" + | "bt2020c" | "smpte240m" ; + v4l2-quant = "default" | "full-range" | "lim-range" ; + +- The compose and crop rectangles: + + .. code-block:: ebnf + + rectangle = "(", left, ",", top, ")", "/", size ; + size = width, "x", height ; + + +In order for a pipeline to be valid, the configuration of pads on both sides of +every link must match. Unless drivers implement custom validation rules, the +default constraint is that the media bus format on both sides must be +identical. For interlaced video, the fields must also be identical, or the +field on the sink side must be equal to ``none`` (in order to support +interlaced sources connected to sinks that only support progressive formats). +The crop and compose rectangles are not taken into account when validating +pipelines, as they are internal to subdevices. + +The default validation is performed by the ``v4l2_subdev_link_validate_default()`` +function in the kernel. If dynamic debugging is enabled (through the +``CONFIG_DYNAMIC_DEBUG`` kernel configuration option), extra messages can be +enabled through debugfs to diagnose the problem more precisely: + +.. code-block:: none + + $ mount -t debugfs none /sys/kernel/debug/ + $ echo 'func v4l2_subdev_link_validate_default +p' > /sys/kernel/debug/dynamic_debug/control + +After trying to capture frames with v4l2-ctl and obtaining the `Broken pipe` +error, the kernel log (obtained with ``dmesg``) provides useful information: + +.. code-block:: none + + rkisp1 32e10000.isp: Validating pad 'rkisp1_isp':0 + rkisp1 32e10000.isp: v4l2_subdev_link_validate_default: width does not match (source 640, sink 800) + rkisp1 32e10000.isp: v4l2_subdev_link_validate_default: height does not match (source 480, sink 600) + rkisp1 32e10000.isp: v4l2_subdev_link_validate_default: media bus code does not match (source 0x0000200f, sink 0x0000300f) + rkisp1 32e10000.isp: v4l2_subdev_link_validate_default: link was "csis-32e40000.csi":1 -> "rkisp1_isp":0 + rkisp1 32e10000.isp: Link 'csis-32e40000.csi':1 -> 'rkisp1_isp':0 failed validation: -32 + +This indicates a mismatch between the source pad of the CSI-2 receiver and the +sink pad of the ISP, both in the resolution and in the format code. The CSI-2 +receiver is configured to output UYVY8_1X16 in 640x480, and the ISP to receive +SRGGB10_1X10 in 800x600, leading to a broken pipeline. + +To fix this, formats must be configuration through the pipeline with a process +referred to as `format propagation`. + + +Format Propagation +------------------ + +Format propagation is a pipeline configuration mechanism where the format is +first configured on the source of the pipeline (the camera sensor in this +case), and then propagated downstream through all subdevices until the video +node at the end of the pipeline. It involves two different types of operations: + +- To ensure that formats on both ends of a link match, when configuring the + format on a source pad of a subdevice, the same format must be set on the + connected sink pad at the other end of the link. This is known as `format + propagation across links`. Subdevices do not automatically propagate formats + across links within the kernel in order to avoid hardcoding use cases in + drivers and to simplify driver implementation. This format propagation is the + responsibility of userspace. + +- Within a subdevice, the kernel ensures that pads configuration stays valid at + all times. When an application configures a format on a subdevice pad, the + driver adjusts parameters that are not valid to the closest supported values. + For instance, resolutions are clampedto the supported range, rounded if the + device has alignment constraints, and unsupported format codes are replaced + with supported values. This is known as `format negotiation` and is similar + to how the kernel handles format setting on V4L2 video devices. + + In addition to the format negotiation at the pad level, the kernel also + ensures that the configurations of all pads within a subdevice remain + coherent with each other. When an application configures the format on a sink + pad, the subdevice driver also adjusts the configuration of the source pads + if the new sink pad configuration would otherwise result in an invalid + subdevice configuration. For instance, the i.MX8MP resizer can scale images + but can't convert between bus format codes, so if an application sets a + format code on the resizer sink pad, the driver will automatically set the + same format code on the resizer source pad. This is known as `format + propagation inside subdevices`, and is the responsibility of the subdevice + drivers. + + Unlike across links where the formats on the source and sink sides of a link + must match, formats on the sink and source pads of a subdevice may be + different. For instance, the i.MX8MP ISP interpolates the raw Bayer data + provided by the camera sensor, and converts it to YUV. The format code on the + source pad of the ISP will thus differ from the sink pad. When userspace + configures the format on the ISP sink pad, the driver will propagate the sink + resolution to the source pad, but will adjust the sink Bayer format code to a + YUV format code on the source pad. + + Format propagation within subdevices ensures that their configuration remains + coherent, but doesn't save applications from having to configure formats on + source pads. Using the resizer example again, the driver will ensure that the + format on the source pad gets adjusted to a value compatible with the format + set on the sink pad, but applications will likely want to then configure the + format on the source pad explicitly in order to change the resolution and + select the scaling ratio. Format propagation within subdevices always operate + `from sink to source`. When userspace sets the format on a source pad, the + driver will adjust it to values compatible with the current configuration of + the sink pads if needed, but will never modify the sink pads configuration by + back-propagating the format from source pad to sink pad. + +Subdevice pad formats can be set with the media-ctl utility, using the +``--set-v4l2`` option (shortened to ``-V``). The syntax is identical to the +format printed by media-ctl with the ``-p`` option. The first step in our +example is to configure the format on the sensor source pad. We use the default +format reported by the media graph (10-bit raw Bayer in 1920x1080), which +corresponds to the sensor native resolution: + +.. code-block:: none + + $ media-ctl -d /dev/media0 -V '"imx290 2-001a":0 [fmt:SRGGB10_1X10/1920x1080 colorspace:raw xfer:none ycbcr:601 quantization:full-range]' + +Running ``media-ctl -p`` again, the format on the sensor source pad has been +updated with the newly selected color space: + +.. code-block:: none + :linenos: + :lineno-start: 73 + :emphasize-lines: 5 + + - entity 34: imx290 2-001a (1 pad, 1 link) + type V4L2 subdev subtype Sensor flags 0 + device node name /dev/v4l-subdev3 + pad0: Source + [fmt:SRGGB10_1X10/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range + crop.bounds:(0,0)/1945x1097 + crop:(12,8)/1920x1080] + -> "csis-32e40000.csi":0 [ENABLED] + +The format is otherwise the same, as we have selected a format code and +resolution identical to the previously configured value. However, this is not +the only change in the media graph. The configuration of the CSI-2 receiver is +now different: + +.. code-block:: none + :linenos: + :lineno-start: 64 + :emphasize-lines: 5,8 + + - entity 29: csis-32e40000.csi (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev2 + pad0: Sink + [fmt:SRGGB10_1X10/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range] + <- "imx290 2-001a":0 [ENABLED] + pad1: Source + [fmt:SRGGB10_1X10/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range] + -> "rkisp1_isp":0 [ENABLED] + +The change in the sink pad format seems to contradict what we have seen before, +as the kernel isn't supposed to propagate formats across links. The reason for +this lies in the media-ctl utility. When setting a format on a source pad, +media-ctl automatically reads back the format from the subdevice (to take into +account possible adjustments applied by the driver) and sets that format on all +sink pads connected through enabled links. + +The source pad format is also modified, due to automatic format propagation by +drivers within subdevices. As the CSI-2 receiver can't transcode or scale, the +source pad format has thus been set to match the sink pad format. + +These two effects simplify the format propagation procedure, as formats on sink +pads don't need to be set manually. Instead, we can read back the format on the +source pad of the next subdevice (the CSI-2 receiver in this case) using +``media-ctl -p``, and set it on the same pad to let media-ctl propagate it to +the next subdevice: + +.. code-block:: none + + $ media-ctl -d /dev/media0 -V '"csis-32e40000.csi":1 [fmt:SRGGB10_1X10/1920x1080 colorspace:raw xfer:none ycbcr:601 quantization:full-range]' + +We expect the next subdevice, ´´rkisp1_isp``, to output an image in a processed +YUV format with a 1920x1080 resolution. This is not what happens: + +.. code-block:: none + :linenos: + :lineno-start: 14 + :emphasize-lines: 6-7,13 + + - entity 1: rkisp1_isp (4 pads, 4 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SRGGB10_1X10/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range + crop.bounds:(0,0)/1920x1080 + crop:(0,0)/800x600] + <- "csis-32e40000.csi":1 [ENABLED] + pad1: Sink + [fmt:unknown/0x0 field:none] + <- "rkisp1_params":0 [ENABLED,IMMUTABLE] + pad2: Source + [fmt:YUYV8_2X8/800x600 field:none colorspace:raw xfer:none ycbcr:601 quantization:lim-range + crop.bounds:(0,0)/800x600 + crop:(0,0)/800x600] + -> "rkisp1_resizer_mainpath":0 [ENABLED] + pad3: Source + [fmt:unknown/0x0 field:none] + -> "rkisp1_stats":0 [ENABLED,IMMUTABLE] + +The output format code (``YUYV8_2X8``) is fine, but the output resolution has +been set to 800x600. This is due to the crop capability of the sink pad. While +the crop bounds have been adjusted (line 19), the crop rectangle itself (line +20) hasn't been adjusted as its previous size (``(0,0)/800x600``) is compatible +with the new sink format. We must thus set the crop rectangle manually on the +sink pad: + +.. code-block:: none + + $ media-ctl -d /dev/media0 -V '"rkisp1_isp":0 [crop:(0,0)/1920x1080]' + +This improves the situation: + +.. code-block:: none + :linenos: + :lineno-start: 14 + :emphasize-lines: 7,13-15 + + - entity 1: rkisp1_isp (4 pads, 4 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SRGGB10_1X10/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range + crop.bounds:(0,0)/1920x1080 + crop:(0,0)/1920x1080] + <- "csis-32e40000.csi":1 [ENABLED] + pad1: Sink + [fmt:unknown/0x0 field:none] + <- "rkisp1_params":0 [ENABLED,IMMUTABLE] + pad2: Source + [fmt:YUYV8_2X8/800x600 field:none colorspace:raw xfer:none ycbcr:601 quantization:lim-range + crop.bounds:(0,0)/1920x1080 + crop:(0,0)/800x600] + -> "rkisp1_resizer_mainpath":0 [ENABLED] + pad3: Source + [fmt:unknown/0x0 field:none] + -> "rkisp1_stats":0 [ENABLED,IMMUTABLE] + +The crop bounds on the source pad (line 27) now cover the full resolution, but +the source crop rectangle (line 28) hasn't been adjusted, for the same reason +as previously. Fixing this is simple: + +.. code-block:: none + + $ media-ctl -d /dev/media0 -V '"rkisp1_isp":2 [crop:(0,0)/1920x1080]' + +This gives us the configuration we want for the source resolution: + +.. code-block:: none + :linenos: + :lineno-start: 14 + :emphasize-lines: 13,15 + + - entity 1: rkisp1_isp (4 pads, 4 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev0 + pad0: Sink + [fmt:SRGGB10_1X10/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:full-range + crop.bounds:(0,0)/1920x1080 + crop:(0,0)/1920x1080] + <- "csis-32e40000.csi":1 [ENABLED] + pad1: Sink + [fmt:unknown/0x0 field:none] + <- "rkisp1_params":0 [ENABLED,IMMUTABLE] + pad2: Source + [fmt:YUYV8_2X8/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:lim-range + crop.bounds:(0,0)/1920x1080 + crop:(0,0)/1920x1080] + -> "rkisp1_resizer_mainpath":0 [ENABLED] + pad3: Source + [fmt:unknown/0x0 field:none] + -> "rkisp1_stats":0 [ENABLED,IMMUTABLE] + +Finally, we set the format on the source pad to let media-ctl propagate it to +the next subdevice (``rkisp1_resizer_mainpath``): + +.. code-block:: none + + $ media-ctl -d /dev/media0 -V '"rkisp1_isp":2 [fmt:YUYV8_2X8/1920x1080]' + +The resizer sink pad format is configured correctly: + +.. code-block:: none + :linenos: + :lineno-start: 34 + :emphasize-lines: 5,7,10 + + - entity 6: rkisp1_resizer_mainpath (2 pads, 2 links) + type V4L2 subdev subtype Unknown flags 0 + device node name /dev/v4l-subdev1 + pad0: Sink + [fmt:YUYV8_2X8/1920x1080 field:none colorspace:raw xfer:none ycbcr:601 quantization:lim-range + crop.bounds:(0,0)/1920x1080 + crop:(0,0)/800x600] + <- "rkisp1_isp":2 [ENABLED] + pad1: Source + [fmt:YUYV8_2X8/800x600 field:none colorspace:raw xfer:none ycbcr:601 quantization:lim-range] + -> "rkisp1_mainpath":0 [ENABLED,IMMUTABLE] + +The resizer source pad (line 43) matches the resolution we want to capture +(``800x600``). However, this is not achieved by scaling, but by cropping the +input frame (line 40). This isn't the desired behaviour, so, even if frame +capture would work with this configuration, we must adjust the sink pad crop +rectangle: + +.. code-block:: none + + $ media-ctl -d /dev/media0 -V '"rkisp1_resizer_mainpath":0 [crop:(0,0)/1920x1080]' + +The source pad format is unchanged and still set to ``YUYV8_2X8/800x600``. If +we wanted to scale to a different resolution, we would need to set the format +on the resizer source pad at this point. + +The next entity in the pipeline (``rkisp1_mainpath``) is not a subdevice but a +video device. There is no need to configure pad formats, as formats on video +devices are set through the classic V4L2 API. Care must be taken to configure +the video device with a pixel format compatible with the source pad of the last +subdevice in the pipeline, and an identical resolution. Which pixel formats +qualify as compatible is device-dependent, as explained in the +:ref:`v4l2-subdevice-formats` section. For the i.MX8MP, the DMA engine at the +output of the pipeline can write the YUV 4:2:2 data it receives from the +resizer in the semi-planar NV16 format: + +.. code-block:: none + + $ v4l2-ctl -d /dev/video0 -v pixelformat=NV16,width=800,height=600 --stream-count 10 --stream-mmap + <<<<<<<<<< + +The pipeline is valid, and 10 frames have been captured successfully. + + +Summary +------- + +Pipelines can be inspected with ``media-ctl -p`` and must configured by +userspace before being used. + +The first configuration step covers link setup. Links should be reset with +``media-ctl -r`` to avoid any influence from a previous configuration, and +individual links should then be enabled with ``media-ctl -l``. + +The second configuration step covers format configuration. Formats are set with +``media-ctl -V`` and must be propagated through the pipeline from source to +sink. The combination of automatic format propagation across links in media-ctl +with the automatic format propagation inside subdevices in the kernel +simplifies format propagation. The generic procedure is as follows: + +#. Set the format on the source pad of the first subdevice in the pipeline. +#. The kernel adjusts the format, and media-ctl automatically propagates it + over the link to the connected sink pad of the next subdevice. +#. If the next subdevice has crop or compose rectangleon its sink or source + pads, sets them as necessary, in the following order: + + - Sink crop + - Sink compose + - Source crop + +#. The kernel automatically propagates the format to the source pad of the + subdevice, adjusting it if needed. +#. Retrieve the propagated format on the source pad of the subdevice, modify it + if required (for instance to configure scaling), and set of on the same + source pad to let media-ctl propagate it across the next link. +#. Repeat this procedure from subdevice to subdevice, until the last subdevice + in the pipeline is reached. + +After configuring the pipeline, frames can be captured from the video device at +the pipeline output with the classic V4L2 API, in a pixel format and resolution +that matches the pipeline configuration. + diff --git a/imx8mp-isp-links-enabled.dot b/imx8mp-isp-links-enabled.dot new file mode 100644 index 0000000..46b0afe --- /dev/null +++ b/imx8mp-isp-links-enabled.dot @@ -0,0 +1,17 @@ +digraph board { + size="5" + rankdir=TB + n00000001 [label="{{ 0 | 1} | rkisp1_isp\n/dev/v4l-subdev0 | { 2 | 3}}", shape=Mrecord, style=filled, fillcolor=green] + n00000001:port2 -> n00000006:port0 + n00000001:port3 -> n0000000d [style=bold] + n00000006 [label="{{ 0} | rkisp1_resizer_mainpath\n/dev/v4l-subdev1 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000006:port1 -> n00000009 [style=bold] + n00000009 [label="rkisp1_mainpath\n/dev/video0", shape=box, style=filled, fillcolor=yellow] + n0000000d [label="rkisp1_stats\n/dev/video1", shape=box, style=filled, fillcolor=yellow] + n00000011 [label="rkisp1_params\n/dev/video2", shape=box, style=filled, fillcolor=yellow] + n00000011 -> n00000001:port1 [style=bold] + n0000001d [label="{{ 0} | csis-32e40000.csi\n/dev/v4l-subdev2 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n0000001d:port1 -> n00000001:port0 + n00000022 [label="{{} | imx290 2-001a\n/dev/v4l-subdev3 | { 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000022:port0 -> n0000001d:port0 +} diff --git a/imx8mp-isp.dot b/imx8mp-isp.dot new file mode 100644 index 0000000..9fcb3be --- /dev/null +++ b/imx8mp-isp.dot @@ -0,0 +1,17 @@ +digraph board { + size="5" + rankdir=TB + n00000001 [label="{{ 0 | 1} | rkisp1_isp\n/dev/v4l-subdev0 | { 2 | 3}}", shape=Mrecord, style=filled, fillcolor=green] + n00000001:port2 -> n00000006:port0 + n00000001:port3 -> n0000000d [style=bold] + n00000006 [label="{{ 0} | rkisp1_resizer_mainpath\n/dev/v4l-subdev1 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000006:port1 -> n00000009 [style=bold] + n00000009 [label="rkisp1_mainpath\n/dev/video0", shape=box, style=filled, fillcolor=yellow] + n0000000d [label="rkisp1_stats\n/dev/video1", shape=box, style=filled, fillcolor=yellow] + n00000011 [label="rkisp1_params\n/dev/video2", shape=box, style=filled, fillcolor=yellow] + n00000011 -> n00000001:port1 [style=bold] + n0000001d [label="{{ 0} | csis-32e40000.csi\n/dev/v4l-subdev2 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n0000001d:port1 -> n00000001:port0 + n00000022 [label="{{} | imx290 2-001a\n/dev/v4l-subdev3 | { 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000022:port0 -> n0000001d:port0 [style=dashed] +} diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..3f12a84 --- /dev/null +++ b/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +============================================= +Application usage of media controller devices +============================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + introduction + mc-v4l2-api + configuring-pipelines + diff --git a/introduction.rst b/introduction.rst new file mode 100644 index 0000000..f595070 --- /dev/null +++ b/introduction.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Introduction +============ + +.. note:: + + This document assumes familiarity of the reader with the concepts of the + traditional `V4L2 API`_, excluding the Media Controller extensions. + +.. _V4L2 API: https://linuxtv.org/downloads/v4l-dvb-apis/userspace-api/v4l/v4l2.html + + +The V4L2 history +---------------- + +When the original Video4Linux (V4L) API was created in 1999, the video capture +devices available for Linux were mostly analog TV capture cards and early +webcams (the first widespread USB webcam hit the market about a year later). +From the point of view of the operating system, devices provided streams of +frames ready to be consumed by applications, with a small set of high-level +parameters to control the frame size or modify the image brightness and +contrast. + +Those devices have shaped the API design. As they are fairly monolithic in the +sense that they appear to the operating system as a black box with relative +high-level controls, the V4L API exposed a device to userspace as one video +device node in ``/dev`` with a set of ioctls to handle buffer management, +format selection, stream control and access to parameters. Many mistakes in the +original design were fixed in Video4Linux2 (V4L2), released in 2002. The +original V4L API got deprecated in 2006 and removed from the Linux kernel in +2010. + +.. note:: + + While the V4L2 API supports both video capture and video output, this + document mostly focusses on the former. + +V4L2 covers a wide range of features for both analog and digital video devices, +including tuner and audio control, and has grown over time to accommodate more +features as video capture devices became more complex. It can enumerate the +device capabilities and parameters (supported video and audio inputs, formats, +frame sizes and frame rates, cropping and composing, analog video standards and +digital video timings, and control parameters), expose them to applications +(with get, try and set access, and a negotiation mechanism), manage buffers +(allocate, queue, dequeue and free them, with the ability to share buffers with +other devices for zero copy operation through dmabuf), start and stop video +streams, and report various conditions to applications through an event +mechanism. The V4L2 API has proven its ability to be extended (from the 51 +ioctls present in 2005 in version 2.6.12 of the kernel, 2 were removed and 33 +added as of version 6.0 in 2022), but has and still retains the same monolithic +device model as its predecessor. + + +Modularity with V4L2 subdevices +------------------------------- + +As Linux moved towards the embedded space, the video capture devices started +exposing the multiple hardware components they contained (such as camera +sensors, TV tuners, video encoders and decoders, image signal processors, ...) +to the operating system instead of hiding them in a black box. The same camera +sensor or TV tuner could be used on different systems with different SoCs, +calling for a different architecture inside the kernel that would enable code +reuse. + +In 2008, the Linux media subsystem gained support for a modular model of video +capture drivers. A new V4L2 subdevice object (``struct v4l2_subdev``) was +created to model external hardware components and expose them to the rest of +the kernel through an abstract API (``struct v4l2_subdev_ops``). The main +driver, also called the bridge driver as it controls the components the bridge +external devices with system memory, still creates the video devices (``struct +video_device``) that are exposed to userspace, but translates and delegates the +API calls from applications into calls to the appropriate subdevices. For +instance, when an application sets a V4L2 control on the video device, the +bridge driver will locate the subdevice that implements that control and +forward it the set control call. + +The bridge driver also creates a top-level V4L2 device (``struct v4l2_device``) +and registers it with the V4L2 framework core, to bind together the subdevices +and video devices inside the kernel. This new model provided code reuse and +modularity inside the kernel. + +.. figure:: subdev.svg + + Modularity with V4L2 subdevices + +The new model only addressed in-kernel issues and kept the monolithic V4L2 +userspace API untouched. The relief it brought was short-lived, as development +of the first Linux kernel driver for an image signal processor (the TI OMAP3 +ISP) showed a need for lower-level control of device internals from +applications. + +An ISP is a complex piece of hardware made of multiple processing blocks. Those +blocks are assembled in image processing pipelines, and in many devices data +routing within pipelines is configurable. Inline pipelines connect a video +source (usually a raw Bayer camera sensor) to the ISP and process frames on the +fly, writing fully processed images to memory. Offline pipelines first capture +raw images to memory and process them in memory-to-memory mode. Hybrid +architectures are also possible, and the same device may be configurable in +different modes depending on the use case. With different devices having +different processing blocks and different routing options, applications need to +control data routing within the device. + +Furthermore, similar operations can often be performed in different places in +the pipeline. For instance, both camera sensors and ISPs are able to scale down +images, with the former usually offering lower-quality scaling than the latter, +but with the ability to achieve higher frame rates. Digital gains and colour +gains are also often found in both camera sensors and ISPs. As where to apply a +given image processing operation is dependent on the use case, a bridge driver +can't correctly decide how to delegate V4L2 API calls from applications to the +appropriate V4L2 subdevice without hardcoding and restricting possible use +cases. + +The OMAP3 ISP driver reached the limits of the monolithic V4L2 API. Two years +of development were needed to fix this problem and finally merge, at the +beginning of 2011, the Media Controller API in the kernel. + diff --git a/mc-v4l2-api.rst b/mc-v4l2-api.rst new file mode 100644 index 0000000..5ac0c01 --- /dev/null +++ b/mc-v4l2-api.rst @@ -0,0 +1,289 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +Media Controller and V4L2 Subdevice APIs +======================================== + +The term `Media Controller` usually covers two distinct APIs: + +- The Media Controller (MC) API itself, whose task it is to expose the internal + topology of the device to applications. + +- The V4L2 subdevice userspace API, which exposes low-level control of + individual subdevices to applications. + +Collectively, and in collaboration with the V4L2 API, these offer the features +needed by applications to control complex video capture devices. + + +The Media Controller API +------------------------ + +.. _media-ctl: https://git.linuxtv.org/v4l-utils.git/tree/utils/media-ctl + +The Media Controller kernel framework and userspace API model devices as a +directed acyclic graph of `entities`. Each entity represents a hardware block, +which can be an external on-board component, an IP core in the SoC, or a piece +of either of those. The API doesn't precisely define how a device should be +split in entities. Individual drivers decide on the exact model they want to +expose, to allow fine-grained control of the hardware blocks while minimizing +the number of entities to avoid unnecessary complexity. + +Entities include `pads`, which model input and output ports through which +entities receive or produce data. Data inputs are called `sinks`, and data +outputs `sources`. The data flow through the graph is modelled by `links` that +connect sources to sinks. Each link connects one source pad of an entity to a +sink pad of another entity. Cycles in the graph are not allowed. + +.. note:: + + The Media Controller API is not limited to video capture devices and has + been designed to model any type of data flow in a media device. This + includes, for instance, audio and display devices. However, as of version + 6.0 of the kernel, the API is only used in the Linux media subsystem, by + V4L2 and DVB drivers, and hasn't made its way to the ALSA and DRM/KMS + subsystems. + +When used in a V4L2 driver, an entity models either a video device (``struct +video_device``) or a subdevice (``struct v4l2_subdevice``). For video capture +devices, subdevices represent video sources (camera sensors, input connectors, +...) or processing elements, and video devices represent the connection to +system memory at the end of a pipeline (typically a DMA engine, but it can also +be a USB connection for USB webcams). The entity type is exposed to +applications as an entity `function`, for instance + +- ``MEDIA_ENT_F_CAM_SENSOR`` for a camera sensor +- ``MEDIA_ENT_F_PROC_VIDEO_SCALER`` for a video scaler +- ``MEDIA_ENT_F_IO_V4L`` for a connection to system memory through a V4L2 video + device + +The kernel media controller device (``struct media_device``) is exposed to +userspace through a media device node, typically named ``/dev/media[0-9]+``. +The `media-ctl`_ tool can query the topology of a Media Controller device and +display it in either plain text (``--print-topology`` or ``-p``) or `DOT format +`_ (``--print-dot``). + +.. code-block:: sh + + $ media-ctl -d /dev/media0 --print-dot | dot -Tsvg > omap3isp.svg + +The following graph represents the TI OMAP3 ISP, with entities corresponding to +subdevices in green and entities corresponding to video devices in yellow. + +.. graphviz:: omap3isp.dot + :caption: Media graph of the TI OMAP3 ISP + +The ``mt9p031 2-0048`` on the top row is a camera sensor, all other entities +are internal to the OMAP3 SoC and part of the ISP. + +Entities, their pads, and the links are intrinsic properties of the device. +They are created by the driver at initialization time to model the hardware +topology. Unless parts of the device is hot-pluggable, no entities or links are +created or removed after initialization. Only their properties can be modified +by applications. + +Data flow routing is controlled by enabling or disabling links, using the +``MEDIA_LNK_FL_ENABLED`` link flag. Links that model immutable connections at +the hardware level are displayed as a thick plain line in the media graph. They +have the ``MEDIA_LNK_FL_IMMUTABLE`` and ``MEDIA_LNK_FL_ENABLED`` flags set and +can't be modified. Links that model configurable routing options can be +controlled, and are displayed as a dotted line if they are disabled or as thin +plain line if they are enabled. + +As the Media Controller API can model any type of data flow, it doesn't expose +any property specific to a particular device type, such as, for instance, pixel +formats or frame rates. This is left to other, device-specific APIs + + +The V4L2 Subdevice Userspace API +-------------------------------- + +.. _V4L2 Subdevice Userspace API: https://linuxtv.org/downloads/v4l-dvb-apis/userspace-api/v4l/dev-subdev.html +.. _V4L2 controls ioctls: https://linuxtv.org/downloads/v4l-dvb-apis/userspace-api/v4l/vidioc-g-ext-ctrls.html +.. _v4l2-ctl: https://git.linuxtv.org/v4l-utils.git/tree/utils/v4l2-ctl + +The `V4L2 Subdevice Userspace API`_ (often shortened to just V4L2 Subdevice API +when this doesn't cause any ambiguity with the in-kernel V4L2 subdevice +operations) has been developed along the Media Controller API to expose to +applications the properties of entities corresponding to V4L2 subdevices. It +allows accessing V4L2 controls directly on a subdevice, as well as formats and +selection rectangles on the subdevice pads. + +Subdevices are exposed to userspace through V4L2 subdevice nodes, typically +named ``/dev/v4l-subdev[0-9]+``. They are controlled using ioctls in a similar +fashion as the V4L2 video devices. The `v4l2-ctl`_ tool supports a wide range +of subdevice-specific options to access subdevices from the command line (see +``v4l2-ctl --help-subdev`` for a detailed list). + +The rest of this document will use the NXP i.MX8MP ISP as an example. Its media +graph is as follows: + +.. graphviz:: imx8mp-isp.dot + :caption: Media graph of the NXP i.MX8MP + +It contains the following V4L2 subdevices: + +- A raw camera sensor (``imx290 2-001a``), with a single source pad connected + to the SoC through a MIPI CSI-2 link. +- A MIPI CSI-2 receiver (``csis-32e40000.csi``), internal to the SoC, that + receives data from the sensor on its sink pad and provides it to the ISP on + its source pad. +- An ISP (``rkisp1_isp``), with two sink pads that receive image data and + processing parameters (0 and 1 respectively) and two source pads that output + image data and statistcis (2 and 3 respectively). +- A scaler (``rkisp1_resizer_mainpath``) that can scale the frames up or down. + +It also contains the following video devices: + +- A capture device that writes video frames to memory (``rkisp1_mainpath``). +- A capture device that writes statistics to memory (``rkisp1_stats``). +- An output device that reads ISP parameters from memory (``rkisp1_params``). + + +V4L2 Subdevice Controls +~~~~~~~~~~~~~~~~~~~~~~~ + +Subdevice controls are accessed using the `V4L2 controls ioctls`_ in exactly +the same way as for video device, except that the ioctls should be issued on +the subdevice node. Tools that access controls on video devices can usually be +used unmodified on subdevices. For instance, to list the controls supported by +the IMX290 camera sensor subdevice, + +.. code-block:: none + + $ v4l2-ctl -d /dev/v4l-subdev3 -l + + User Controls + + exposure 0x00980911 (int) : min=1 max=1123 step=1 default=1123 value=1123 + + Camera Controls + + camera_orientation 0x009a0922 (menu) : min=0 max=2 default=0 value=0 (Front) flags=read-only + camera_sensor_rotation 0x009a0923 (int) : min=0 max=0 step=1 default=0 value=0 flags=read-only + + Image Source Controls + + vertical_blanking 0x009e0901 (int) : min=45 max=45 step=1 default=45 value=45 flags=read-only + horizontal_blanking 0x009e0902 (int) : min=280 max=280 step=1 default=280 value=280 flags=read-only + analogue_gain 0x009e0903 (int) : min=0 max=240 step=1 default=0 value=0 + + Image Processing Controls + + link_frequency 0x009f0901 (intmenu): min=0 max=1 default=0 value=0 (222750000 0xd46e530) flags=read-only + pixel_rate 0x009f0902 (int64) : min=1 max=2147483647 step=1 default=178200000 value=178200000 flags=read-only + test_pattern 0x009f0903 (menu) : min=0 max=7 default=0 value=0 (Disabled) + +By accessing controls on subdevices, applications can control the behaviour of +each subdevice independently. If multiple subdevices in the graph implement the +same control (such as a digital gain), those controls can be set individually. +This wouldn't be possible using with the traditional V4L2 API on video devices, +as the identical controls from two different subdevices would conflict. + + +.. _v4l2-subdevice-formats: + +V4L2 Subdevice Formats +~~~~~~~~~~~~~~~~~~~~~~ + +Where video devices expose only the format of the frames being captured to +memory, subdevices allow fine-grained configuration of formats on every pad in +the pipeline. This enables setting up pipelines with different internal +configurations to match precise use cases. To understand why this is needed, +let's consider the following simplified example, where a 12MP camera sensor +(IMX477) is connected to an SoC that includes an ISP and a scaler. + +.. graphviz:: scaler.dot + :caption: Scaling pipeline + +All three components can affect the image size: + +- The camera sensor can subsample the image through mechanisms such as binning + and skipping. +- The ISP can subsample the image horizontally through averaging. +- The scaler uses a polyphase filter for high quality scaling. + +All these components can further crop the image if desired. + +Different use cases will call for cropping and resizing the image in different +ways through the pipeline. Let's assume that, in all cases, we want to capture +1.5MP images from the 12MP native sensor resolution, When frame rate is more +important than quality, the sensor will typically subsample the image to comply +with the bandwidth limitations of the ISP. As the subsampling factor is +restricted to powers of two, the scaler is further used to achieve the exact +desired size. + +.. graphviz:: scaler-fast.dot + :caption: Fast scaling + +On the other hand, when capturing still images, the full image should be +processed through the pipeline and resized at the very end using the higher +quality scaler. + +.. graphviz:: scaler-hq.dot + :caption: High quality scaling + +Using the traditional V4L2 API on video nodes, the bridge driver configures the +internal pipeline based on the desired capture format. As the use cases above +produce the same format at the output of the pipeline, the bridge driver won't +be able to differentiate between them and configure the pipeline appropriately +for each use case. To solve this problem, the V4L2 subdevice userspace API let +applications access formats on pads directly. + +Formats on subdevice pads are called `media bus formats`. They are described by +the ``v4l2_mbus_framefmt`` structure: + +.. code-block:: c + + struct v4l2_mbus_framefmt { + __u32 width; + __u32 height; + __u32 code; + __u32 field; + __u32 colorspace; + union { + __u16 ycbcr_enc; + __u16 hsv_enc; + }; + __u16 quantization; + __u16 xfer_func; + __u16 flags; + __u16 reserved[10]; + }; + +Unlike the pixel formats used on video devices, which describe how image data +is stored in memory (using the ``v4l2_pix_format`` and +``v4l2_pix_format_mplane`` structures), media bus formats describe how image +data is transmitted on buses between subdevices. The ``bytesperline`` and +``sizeimage`` fields of the pixel format are thus not found in the media bus +formats, as they refer to memory sizes. + +This difference between the two concepts causes a second difference between the +media bus and pixel format structures. The FourCC values used to described +pixel formats are not applicable to bus formats, as they also describe data +organization in memory. Media bus formats instead use `format codes` that +describe how individual bits are organized and transferred on a bus. The format +codes are 32-bit numerical values defined by the ``MEDIA_BUS_FMT_*`` macros and +are documented in the `Media Bus Formats`_ section of the V4L2 API +documentation. + +.. _Media Bus Formats: https://linuxtv.org/downloads/v4l-dvb-apis/userspace-api/v4l/subdev-formats.html> + +.. note:: + + In the remaining of this document, the terms `media bus format`, `bus + format` or `format`, when applying to subdevice pads, refers to the + combination of all fields of the ``v4l2_mbus_framefmt`` structure. To refer + to the media bus format code specifically, the terms `media bus code`, + `format code` or `code` will be used. + +In general, there is no 1:1 universal mapping between pixel formats and media +bus formats. To understand this, let's consider the +``MEDIA_BUS_FMT_UYVY8_1X16`` media bus code that describes on common way to +transmit YUV 4:2:2 data on a 16-bit parallel bus. When the image data reaches +the DMA engine at the end of the pipeline and is written to memory, it can be +rearranged in different ways, producing for instance the ``V4L2_PIX_FMT_UYVY`` +packed pixel format that seem to be a direct match, but also the semi-planar +``V4L2_PIX_FMT_NV16`` format by writing the luma and chroma data to separate +memory planes. How a media bus code is translated to pixel formats depends on +the capabilities of the DMA engine, and is thus device-specific. + diff --git a/omap3isp.dot b/omap3isp.dot new file mode 100644 index 0000000..daa3b41 --- /dev/null +++ b/omap3isp.dot @@ -0,0 +1,36 @@ +digraph board { + rankdir=TB + n00000001 [label="{{ 0} | OMAP3 ISP CCP2\n/dev/v4l-subdev0 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000001:port1 -> n00000005:port0 [style=dashed] + n00000002 [label="OMAP3 ISP CCP2 input\n/dev/video2", shape=box, style=filled, fillcolor=yellow] + n00000002 -> n00000001:port0 [style=dashed] + n00000003 [label="{{ 0} | OMAP3 ISP CSI2a\n/dev/v4l-subdev1 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000003:port1 -> n00000004 [style=dashed] + n00000003:port1 -> n00000005:port0 [style=dashed] + n00000004 [label="OMAP3 ISP CSI2a output\n/dev/video3", shape=box, style=filled, fillcolor=yellow] + n00000005 [label="{{ 0} | OMAP3 ISP CCDC\n/dev/v4l-subdev2 | { 1 | 2}}", shape=Mrecord, style=filled, fillcolor=green] + n00000005:port1 -> n00000006 + n00000005:port2 -> n00000007:port0 [style=dashed] + n00000005:port1 -> n0000000a:port0 [style=dashed] + n00000005:port2 -> n0000000d:port0 [style=bold] + n00000005:port2 -> n0000000e:port0 [style=bold] + n00000005:port2 -> n0000000f:port0 [style=bold] + n00000006 [label="OMAP3 ISP CCDC output\n/dev/video4", shape=box, style=filled, fillcolor=yellow] + n00000007 [label="{{ 0} | OMAP3 ISP preview\n/dev/v4l-subdev3 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n00000007:port1 -> n00000009 [style=dashed] + n00000007:port1 -> n0000000a:port0 + n00000008 [label="OMAP3 ISP preview input\n/dev/video5", shape=box, style=filled, fillcolor=yellow] + n00000008 -> n00000007:port0 + n00000009 [label="OMAP3 ISP preview output\n/dev/video6", shape=box, style=filled, fillcolor=yellow] + n0000000a [label="{{ 0} | OMAP3 ISP resizer\n/dev/v4l-subdev4 | { 1}}", shape=Mrecord, style=filled, fillcolor=green] + n0000000a:port1 -> n0000000c + n0000000b [label="OMAP3 ISP resizer input\n/dev/video7", shape=box, style=filled, fillcolor=yellow] + n0000000b -> n0000000a:port0 [style=dashed] + n0000000c [label="OMAP3 ISP resizer output\n/dev/video8", shape=box, style=filled, fillcolor=yellow] + n0000000d [label="{{ 0} | OMAP3 ISP AEWB\n/dev/v4l-subdev5 | {}}", shape=Mrecord, style=filled, fillcolor=green] + n0000000e [label="{{ 0} | OMAP3 ISP AF\n/dev/v4l-subdev6 | {}}", shape=Mrecord, style=filled, fillcolor=green] + n0000000f [label="{{ 0} | OMAP3 ISP histogram\n/dev/v4l-subdev7 | {}}", shape=Mrecord, style=filled, fillcolor=green] + n00000010 [label="{{} | mt9p031 2-0048\n/dev/v4l-subdev8 | { 0}}", shape=Mrecord, style=filled, fillcolor=green] + n00000010:port0 -> n00000005:port0 +} + diff --git a/scaler-fast.dot b/scaler-fast.dot new file mode 100644 index 0000000..4e5b642 --- /dev/null +++ b/scaler-fast.dot @@ -0,0 +1,13 @@ +digraph board { + size="6" + rankdir=LR + + sensor [label="{ | IMX477\nsensor | 0}", shape=Mrecord, style=filled, fillcolor=green] + isp [label="{ 0 | ISP | 1}", shape=Mrecord, style=filled, fillcolor=green] + scaler [label="{ 0 | scaler | 1}", shape=Mrecord, style=filled, fillcolor=green] + capture [label="DMA", shape=box, style=filled, fillcolor=yellow] + + sensor:port0 -> isp:port0 [labelangle=70, labeldistance=4, headlabel="4056x3040", style=bold] + isp:port1 -> scaler:port0 [labelangle=70, labeldistance=4, headlabel="2028x1520", style=bold] + scaler:port1 -> capture [labelangle=70, labeldistance=4, headlabel="1440x1080", style=bold] +} diff --git a/scaler-hq.dot b/scaler-hq.dot new file mode 100644 index 0000000..cfc0dd3 --- /dev/null +++ b/scaler-hq.dot @@ -0,0 +1,13 @@ +digraph board { + size="6" + rankdir=LR + + sensor [label="{ | IMX477\nsensor | 0}", shape=Mrecord, style=filled, fillcolor=green] + isp [label="{ 0 | ISP | 1}", shape=Mrecord, style=filled, fillcolor=green] + scaler [label="{ 0 | scaler | 1}", shape=Mrecord, style=filled, fillcolor=green] + capture [label="DMA", shape=box, style=filled, fillcolor=yellow] + + sensor:port0 -> isp:port0 [labelangle=70, labeldistance=4, headlabel="4056x3040", style=bold] + isp:port1 -> scaler:port0 [labelangle=70, labeldistance=4, headlabel="4056x3040", style=bold] + scaler:port1 -> capture [labelangle=70, labeldistance=4, headlabel="1440x1080", style=bold] +} diff --git a/scaler.dot b/scaler.dot new file mode 100644 index 0000000..3cb2743 --- /dev/null +++ b/scaler.dot @@ -0,0 +1,28 @@ +digraph board { + size="6" + rankdir=LR + + { + rank=same + sensor [label="{ | IMX477\nsensor | 0}", shape=Mrecord, style=filled, fillcolor=green] + sensor_label [label="Binning &\nskipping", shape=plaintext] + } + + { + rank=same + isp [label="{ 0 | ISP | 1}", shape=Mrecord, style=filled, fillcolor=green] + isp_label [label="Horizontal\naveraging", shape=plaintext] + } + + { + rank=same + scaler [label="{ 0 | scaler | 1}", shape=Mrecord, style=filled, fillcolor=green] + scaler_label [label="Polyphase\nfilter", shape=plaintext] + } + + capture [label="DMA", shape=box, style=filled, fillcolor=yellow] + + sensor:port0 -> isp:port0 [style=bold] + isp:port1 -> scaler:port0 [style=bold] + scaler:port1 -> capture [style=bold] +} diff --git a/subdev.svg b/subdev.svg new file mode 100644 index 0000000..82a25e8 --- /dev/null +++ b/subdev.svg @@ -0,0 +1,456 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + MT9M001Sensor + PXA270SoC + EM28xxUSB + + + + EM28xxUSB + MT9M001Sensor + SAA7114Decoder + + + + + + + -- cgit v1.2.3