[PATCH v10 0/4] Add a glossary for the media subsystem

[PATCH v10 0/4] Add a glossary for the media subsystem

[Mauro Carvalho Chehab]

There are too many technical terms at the media subsystem, and sometimes
the same thing is refered differently at the documentation and on the ML
and IRC discussions.

Let's add a glossary to the uAPI documentation, in order to start using
a common vocabulary at the subsystem's discussion and to let things
clearer for people trying to understand the subsystem.

I'm pretty sure that this document doesn't cover everything, but it can
(and should) be improved overtime.

On version 10, I addressed the comments from Hans (minor adjustments
and typos). Also, two patches were folded together.

Mauro Carvalho Chehab (4):
  media: open.rst: better document device node naming
  media: open.rst: remove the minor number range
  media: docs: add glossary.rst with common terms used at V4L2 spec
  media: open.rst: document mc-centric and video-node-centric

 .../userspace-api/media/glossary.rst          | 216 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 .../userspace-api/media/v4l/open.rst          | 110 +++++++--
 3 files changed, 315 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/userspace-api/media/glossary.rst

-- 
2.26.2

[PATCH v10 1/4] media: open.rst: better document device node naming

[Mauro Carvalho Chehab]

Right now, only kAPI documentation describes the device naming.
However, such description is needed at the uAPI too. Add it,
and describe how to get an unique identifier for a given device.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)

diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
index 38046ef20141..332763053292 100644
--- a/Documentation/userspace-api/media/v4l/open.rst
+++ b/Documentation/userspace-api/media/v4l/open.rst
@@ -14,12 +14,14 @@ Opening and Closing Devices
 ***************************
 
 
-Device Naming
-=============
+.. _v4l2_device_naming:
+
+V4L2 Device Node Naming
+=======================
 
 V4L2 drivers are implemented as kernel modules, loaded manually by the
 system administrator or automatically when a device is first discovered.
-The driver modules plug into the "videodev" kernel module. It provides
+The driver modules plug into the ``videodev`` kernel module. It provides
 helper functions and a common application interface specified in this
 document.
 
@@ -30,6 +32,41 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
 are allocated in ranges depending on the device node type (video, radio,
 etc.).
 
+The device nodes supported by the Video4Linux subsystem are:
+
+======================== ====================================================
+Default device node name Usage
+======================== ====================================================
+``/dev/videoX``		 Video and metadata for capture/output devices
+``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
+``/dev/radioX``		 Radio tuners and modulators
+``/dev/swradioX``	 Software Defined Radio tuners and modulators
+``/dev/v4l-touchX``	 Touch sensors
+``/dev/v4l-subdevX``	 Video sub-devices (used by sensors and other
+			 components of the hardware peripheral)\ [#]_
+======================== ====================================================
+
+Where ``X`` is a non-negative number.
+
+.. note::
+
+   1. The actual device node name is system-dependent, as udev rules may apply.
+   2. There is no guarantee that ``X`` will remain the same for the same
+      device, as the number depends on the device driver's probe order.
+      If you need an unique name, udev default rules produce
+      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing
+      links that can be used uniquely to identify a V4L2 device node::
+
+	$ tree /dev/v4l
+	/dev/v4l
+	├── by-id
+	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
+	└── by-path
+	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
+
+.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different
+       set of system calls, as covered at :ref:`subdev`.
+
 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
 options to select specific video/radio/vbi node numbers. This allows the
 user to request that the device node is named e.g. /dev/video5 instead
-- 
2.26.2

[PATCH v10 2/4] media: open.rst: remove the minor number range

[Mauro Carvalho Chehab]

minor numbers use to range between 0 to 255, but that
was changed a long time ago. While it still applies when
CONFIG_VIDEO_FIXED_MINOR_RANGES, when the minor number is
dynamically allocated, this may not be true. In any case,
this is not relevant, as udev will take care of it.

So, remove this useless misinformation.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Acked-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/userspace-api/media/v4l/open.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
index 332763053292..b9367e02b884 100644
--- a/Documentation/userspace-api/media/v4l/open.rst
+++ b/Documentation/userspace-api/media/v4l/open.rst
@@ -26,11 +26,10 @@ helper functions and a common application interface specified in this
 document.
 
 Each driver thus loaded registers one or more device nodes with major
-number 81 and a minor number between 0 and 255. Minor numbers are
-allocated dynamically unless the kernel is compiled with the kernel
-option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
-are allocated in ranges depending on the device node type (video, radio,
-etc.).
+number 81. Minor numbers are allocated dynamically unless the kernel
+is compiled with the kernel option CONFIG_VIDEO_FIXED_MINOR_RANGES.
+In that case minor numbers are allocated in ranges depending on the
+device node type.
 
 The device nodes supported by the Video4Linux subsystem are:
 
-- 
2.26.2

[PATCH v10 3/4] media: docs: add glossary.rst with common terms used at V4L2 spec

[Mauro Carvalho Chehab]

Add a glossary of terms used within the media userspace API
documentation, as several concepts are complex enough to cause
misunderstandings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../userspace-api/media/glossary.rst          | 216 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 2 files changed, 219 insertions(+)
 create mode 100644 Documentation/userspace-api/media/glossary.rst

diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
new file mode 100644
index 000000000000..45f0933e03c0
--- /dev/null
+++ b/Documentation/userspace-api/media/glossary.rst
@@ -0,0 +1,216 @@
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later
+
+.. For GPL-2.0, see LICENSES/preferred/GPL-2.0
+..
+.. For GFDL-1.1-or-later, see:
+..
+.. Permission is granted to copy, distribute and/or modify this document
+.. under the terms of the GNU Free Documentation License, Version 1.1 or
+.. any later version published by the Free Software Foundation, with no
+.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
+.. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+
+========
+Glossary
+========
+
+.. note::
+
+   The goal of this section is to standardize the terms used within the media
+   userspace API documentation. This is Work In Progress.
+
+.. Please keep the glossary entries in alphabetical order
+
+.. glossary::
+
+    Bridge Driver
+	A :term:`device driver` that implements the main logic to talk with
+	media hardware.
+
+    CEC API
+	**Consumer Electronics Control API**
+
+	An API designed to receive and transmit data via an HDMI
+	CEC interface.
+
+	See :ref:`cec`.
+
+    Device Driver
+	Part of the Linux Kernel that implements support for a hardware
+	component.
+
+    Device Node
+	A character device node in the file system used to control and
+	transfer data in and out of a Kernel driver.
+
+    Digital TV API
+	**Previously known as DVB API**
+
+	An API designed to control a subset of the :term:`Media Hardware`
+	that implements	digital TV (e. g. DVB, ATSC, ISDB, etc).
+
+	See :ref:`dvbapi`.
+
+    DSP
+        **Digital Signal Processor**
+
+	A specialized :term:`Microprocessor`, with its architecture
+	optimized for the operational needs of digital signal processing.
+
+    FPGA
+	**Field-programmable Gate Array**
+
+	An :term:`IC` circuit designed to be configured by a customer or
+	a designer after manufacturing.
+
+	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
+
+    Hardware Component
+	A subset of the :term:`media hardware`. For example an :term:`I²C` or
+	:term:`SPI` device, or an :term:`IP block` inside an
+	:term:`SoC` or :term:`FPGA`.
+
+    Hardware Peripheral
+	A group of :term:`hardware components <hardware component>` that
+	together make a larger user-facing functional peripheral. For
+	instance, the :term:`SoC` :term:`ISP` :term:`IP block <ip block>`
+	and the external camera sensors together make a camera hardware
+	peripheral.
+
+	Also known as :term:`peripheral`.
+
+    I²C
+	**Inter-Integrated Circuit**
+
+	A  multi-master, multi-slave, packet switched, single-ended,
+	serial computer bus used to control some hardware components
+	like sub-device hardware components.
+
+	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
+
+    IC
+	**Integrated circuit**
+
+	A set of electronic circuits on one small flat piece of
+	semiconductor material, normally silicon.
+
+	Also known as chip.
+
+    IP Block
+	**Intellectual property core**
+
+	In electronic design a semiconductor intellectual property core,
+	is a reusable unit of logic, cell, or integrated circuit layout
+	design that is the intellectual property of one party.
+	IP Blocks may be licensed to another party or can be owned
+	and used by a single party alone.
+
+	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
+
+    ISP
+	**Image Signal Processor**
+
+	A specialized processor that implements a set of algorithms for
+	processing image data. ISPs may implement algorithms for lens
+	shading correction, demosaicing, scaling and pixel format conversion
+	as well as produce statistics for the use of the control
+	algorithms (e.g. automatic exposure, white balance and focus).
+
+    Media API
+	A set of userspace APIs used to control the media hardware. It is
+	composed by:
+
+	  - :term:`CEC API`;
+	  - :term:`Digital TV API`;
+	  - :term:`MC API`;
+	  - :term:`RC API`; and
+	  - :term:`V4L2 API`.
+
+	See :doc:`index`.
+
+    MC API
+	**Media Controller API**
+
+	An API designed to expose and control the relationships between
+	multimedia devices and sub-devices.
+
+	See :ref:`media_controller`.
+
+    MC-centric
+	:term:`V4L2 hardware` that requires a :term:`MC API`.
+
+	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
+	(see :ref:`VIDIOC_QUERYCAP`).
+
+	See :ref:`v4l2_hardware_control` for more details.
+
+    Media Hardware
+	Subset of the hardware that is supported by the Linux Media API.
+
+	This includes audio and video capture and playback hardware,
+	digital and analog TV, camera sensors, ISPs, remote controllers,
+	codecs, HDMI Consumer Electronics Control, HDMI capture, etc.
+
+    Microprocessor
+	Electronic circuitry that carries out the instructions of a
+	computer program by performing the basic arithmetic, logical,
+	control and input/output (I/O) operations specified by the
+	instructions on a single integrated circuit.
+
+    Peripheral
+	The same as :term:`hardware peripheral`.
+
+    RC API
+	**Remote Controller API**
+
+	An API designed to receive and transmit data from remote
+	controllers.
+
+	See :ref:`remote_controllers`.
+
+    SMBus
+	A subset of I²C, which defines a stricter usage of the bus.
+
+    SPI
+	**Serial Peripheral Interface Bus**
+
+	Synchronous serial communication interface specification used for
+	short distance communication, primarily in embedded systems.
+
+    SoC
+	**System on a Chip**
+
+	An integrated circuit that integrates all components of a computer
+	or other electronic systems.
+
+    V4L2 API
+	**V4L2 userspace API**
+
+	The userspace API defined in :ref:`v4l2spec`, which is used to
+	control a V4L2 hardware.
+
+    V4L2 Device Node
+	A :term:`device node` that is associated to a V4L driver.
+
+	The V4L2 device node naming is specified at :ref:`v4l2_device_naming`.
+
+    V4L2 Hardware
+	Part of the media hardware which is supported by the :term:`V4L2 API`.
+
+    V4L2 Sub-device
+	V4L2 hardware components that aren't controlled by a
+	:term:`bridge driver`. See :ref:`subdev`.
+
+    Video-node-centric
+	V4L2 hardware that doesn't require a media controller to be used.
+
+	Such hardware have the ``V4L2_CAP_IO_MC`` device_caps field unset
+	(see :ref:`VIDIOC_QUERYCAP`).
+
+    V4L2 Sub-device API
+	Part of the :term:`V4L2 API` which control
+	:term:`V4L2 sub-devices <V4L2 Sub-device>`, like sensors,
+	HDMI receivers, scalers, deinterlacers.
+
+	See :ref:`v4l2_hardware_control` for more details.
diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst
index 70a3f3d73698..7f42f83b9f59 100644
--- a/Documentation/userspace-api/media/index.rst
+++ b/Documentation/userspace-api/media/index.rst
@@ -35,6 +35,9 @@ Please see:
     mediactl/media-controller
     cec/cec-api
     gen-errors
+
+    glossary
+
     fdl-appendix
 
     drivers/index
-- 
2.26.2

[PATCH v10 4/4] media: open.rst: document mc-centric and video-node-centric

[Mauro Carvalho Chehab]

When we added support for omap3, back in 2010, we added a new
type of V4L2 devices that aren't fully controlled via the V4L2
device node.

Yet, we have never clearly documented in the V4L2 specification
the differences between the two types.

Let's document them based on the the current implementation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../userspace-api/media/v4l/open.rst          | 58 +++++++++++++++++--
 1 file changed, 52 insertions(+), 6 deletions(-)

diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
index b9367e02b884..e9cfbe954918 100644
--- a/Documentation/userspace-api/media/v4l/open.rst
+++ b/Documentation/userspace-api/media/v4l/open.rst
@@ -13,6 +13,52 @@
 Opening and Closing Devices
 ***************************
 
+.. _v4l2_hardware_control:
+
+Controlling a hardware peripheral via V4L2
+==========================================
+
+A V4L2 hardware peripheral is usually complex: support for it is
+implemented via a bridge driver and often by several additional drivers.
+The bridge driver exposes one or more V4L2 device nodes
+(see :ref:`v4l2_device_naming`).
+
+There are other drivers providing support for other components of
+the hardware, which may also expose device nodes, called V4L2 sub-devices.
+
+When such V4L2 sub-devices are exposed, they allow controlling those
+other hardware components - usually connected via a serial bus (like
+I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices
+can be controlled indirectly via the bridge driver or explicitly via
+the :ref:`Media Controller <media_controller>` and via the
+:ref:`V4L2 sub-devices <subdev>`.
+
+The devices that require the use of the
+:ref:`Media Controller <media_controller>` are called **MC-centric**
+devices. The devices that are fully controlled via V4L2 device nodes
+are called **video-node-centric**.
+
+Userspace can check if a V4L2 hardware peripheral is MC-centric by
+calling :ref:`VIDIOC_QUERYCAP` and checking the
+:ref:`device_caps field <device-capabilities>`.
+
+If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``,
+then it is MC-centric, otherwise, it is video-node-centric.
+
+It is required for MC-centric hardware to identify the V4L2
+sub-devices and to configure the pipelines via the
+:ref:`media controller API <media_controller>` before using the peripheral.
+Also, the sub-devices' configuration shall be controlled via the
+:ref:`sub-device API <subdev>`.
+
+.. note::
+
+   A video-node-centric may still provide media-controller and
+   sub-device interfaces as well.
+
+  However, in that case the media-controller and the sub-device
+  interfaces are read-only and just provide information about the
+  device. The actual configuration is done via the video nodes.
 
 .. _v4l2_device_naming:
 
@@ -109,7 +155,7 @@ Related Devices
 Devices can support several functions. For example video capturing, VBI
 capturing and radio support.
 
-The V4L2 API creates different nodes for each of these functions.
+The V4L2 API creates different V4L2 device nodes for each of these functions.
 
 The V4L2 API was designed with the idea that one device node could
 support all functions. However, in practice this never worked: this
@@ -119,17 +165,17 @@ switching a device node between different functions only works when
 using the streaming I/O API, not with the
 :ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
 
-Today each device node supports just one function.
+Today each V4L2 device node supports just one function.
 
 Besides video input or output the hardware may also support audio
 sampling or playback. If so, these functions are implemented as ALSA PCM
 devices with optional ALSA audio mixer devices.
 
 One problem with all these devices is that the V4L2 API makes no
-provisions to find these related devices. Some really complex devices
-use the Media Controller (see :ref:`media_controller`) which can be
-used for this purpose. But most drivers do not use it, and while some
-code exists that uses sysfs to discover related devices (see
+provisions to find these related V4L2 device nodes. Some really complex
+hardware use the Media Controller (see :ref:`media_controller`) which can
+be used for this purpose. But several drivers do not use it, and while some
+code exists that uses sysfs to discover related V4L2 device nodes (see
 libmedia_dev in the
 `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
 repository), there is no library yet that can provide a single API
-- 
2.26.2

Re: [PATCH v10 1/4] media: open.rst: better document device node naming

[Sakari Ailus]

Hi Mauro,

Thanks for working on this!

On Thu, Aug 27, 2020 at 09:21:45AM +0200, Mauro Carvalho Chehab wrote:
> Right now, only kAPI documentation describes the device naming.
> However, such description is needed at the uAPI too. Add it,
> and describe how to get an unique identifier for a given device.
> 
> Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
>  1 file changed, 40 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
> index 38046ef20141..332763053292 100644
> --- a/Documentation/userspace-api/media/v4l/open.rst
> +++ b/Documentation/userspace-api/media/v4l/open.rst
> @@ -14,12 +14,14 @@ Opening and Closing Devices
>  ***************************
>  
>  
> -Device Naming
> -=============
> +.. _v4l2_device_naming:
> +
> +V4L2 Device Node Naming
> +=======================
>  
>  V4L2 drivers are implemented as kernel modules, loaded manually by the
>  system administrator or automatically when a device is first discovered.
> -The driver modules plug into the "videodev" kernel module. It provides
> +The driver modules plug into the ``videodev`` kernel module. It provides
>  helper functions and a common application interface specified in this
>  document.
>  
> @@ -30,6 +32,41 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
>  are allocated in ranges depending on the device node type (video, radio,
>  etc.).
>  
> +The device nodes supported by the Video4Linux subsystem are:
> +
> +======================== ====================================================
> +Default device node name Usage
> +======================== ====================================================
> +``/dev/videoX``		 Video and metadata for capture/output devices
> +``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
> +``/dev/radioX``		 Radio tuners and modulators
> +``/dev/swradioX``	 Software Defined Radio tuners and modulators
> +``/dev/v4l-touchX``	 Touch sensors
> +``/dev/v4l-subdevX``	 Video sub-devices (used by sensors and other
> +			 components of the hardware peripheral)\ [#]_
> +======================== ====================================================
> +
> +Where ``X`` is a non-negative number.

s/number/integer/

Reviewed-by: Sakari Ailus <sakari.ailus@linux.intel.com>

> +
> +.. note::
> +
> +   1. The actual device node name is system-dependent, as udev rules may apply.
> +   2. There is no guarantee that ``X`` will remain the same for the same
> +      device, as the number depends on the device driver's probe order.
> +      If you need an unique name, udev default rules produce
> +      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directories containing
> +      links that can be used uniquely to identify a V4L2 device node::
> +
> +	$ tree /dev/v4l
> +	/dev/v4l
> +	├── by-id
> +	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
> +	└── by-path
> +	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
> +
> +.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-subdevX``) use a different
> +       set of system calls, as covered at :ref:`subdev`.
> +
>  Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
>  options to select specific video/radio/vbi node numbers. This allows the
>  user to request that the device node is named e.g. /dev/video5 instead
> 

-- 
Sakari Ailus

Re: [PATCH v10 3/4] media: docs: add glossary.rst with common terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

On Thu, Aug 27, 2020 at 09:21:47AM +0200, Mauro Carvalho Chehab wrote:
> Add a glossary of terms used within the media userspace API
> documentation, as several concepts are complex enough to cause
> misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../userspace-api/media/glossary.rst          | 216 ++++++++++++++++++
>  Documentation/userspace-api/media/index.rst   |   3 +
>  2 files changed, 219 insertions(+)
>  create mode 100644 Documentation/userspace-api/media/glossary.rst
> 
> diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
> new file mode 100644
> index 000000000000..45f0933e03c0
> --- /dev/null
> +++ b/Documentation/userspace-api/media/glossary.rst
> @@ -0,0 +1,216 @@
> +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later
> +
> +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0
> +..
> +.. For GFDL-1.1-or-later, see:
> +..
> +.. Permission is granted to copy, distribute and/or modify this document
> +.. under the terms of the GNU Free Documentation License, Version 1.1 or
> +.. any later version published by the Free Software Foundation, with no
> +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
> +.. A copy of the license is included at
> +.. Documentation/userspace-api/media/fdl-appendix.rst.
> +
> +========
> +Glossary
> +========
> +
> +.. note::
> +
> +   The goal of this section is to standardize the terms used within the media
> +   userspace API documentation. This is Work In Progress.
> +
> +.. Please keep the glossary entries in alphabetical order
> +
> +.. glossary::
> +
> +    Bridge Driver
> +	A :term:`device driver` that implements the main logic to talk with
> +	media hardware.
> +
> +    CEC API
> +	**Consumer Electronics Control API**
> +
> +	An API designed to receive and transmit data via an HDMI
> +	CEC interface.
> +
> +	See :ref:`cec`.
> +
> +    Device Driver
> +	Part of the Linux Kernel that implements support for a hardware
> +	component.
> +
> +    Device Node
> +	A character device node in the file system used to control and
> +	transfer data in and out of a Kernel driver.
> +
> +    Digital TV API
> +	**Previously known as DVB API**
> +
> +	An API designed to control a subset of the :term:`Media Hardware`
> +	that implements	digital TV (e. g. DVB, ATSC, ISDB, etc).
> +
> +	See :ref:`dvbapi`.
> +
> +    DSP
> +        **Digital Signal Processor**
> +
> +	A specialized :term:`Microprocessor`, with its architecture
> +	optimized for the operational needs of digital signal processing.
> +
> +    FPGA
> +	**Field-programmable Gate Array**
> +
> +	An :term:`IC` circuit designed to be configured by a customer or
> +	a designer after manufacturing.
> +
> +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> +
> +    Hardware Component
> +	A subset of the :term:`media hardware`. For example an :term:`I²C` or
> +	:term:`SPI` device, or an :term:`IP block` inside an
> +	:term:`SoC` or :term:`FPGA`.
> +
> +    Hardware Peripheral
> +	A group of :term:`hardware components <hardware component>` that
> +	together make a larger user-facing functional peripheral. For
> +	instance, the :term:`SoC` :term:`ISP` :term:`IP block <ip block>`
> +	and the external camera sensors together make a camera hardware
> +	peripheral.
> +
> +	Also known as :term:`peripheral`.
> +
> +    I²C
> +	**Inter-Integrated Circuit**
> +
> +	A  multi-master, multi-slave, packet switched, single-ended,
> +	serial computer bus used to control some hardware components
> +	like sub-device hardware components.
> +
> +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> +
> +    IC
> +	**Integrated circuit**
> +
> +	A set of electronic circuits on one small flat piece of
> +	semiconductor material, normally silicon.
> +
> +	Also known as chip.
> +
> +    IP Block
> +	**Intellectual property core**
> +
> +	In electronic design a semiconductor intellectual property core,
> +	is a reusable unit of logic, cell, or integrated circuit layout
> +	design that is the intellectual property of one party.
> +	IP Blocks may be licensed to another party or can be owned
> +	and used by a single party alone.
> +
> +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> +
> +    ISP
> +	**Image Signal Processor**
> +
> +	A specialized processor that implements a set of algorithms for
> +	processing image data. ISPs may implement algorithms for lens
> +	shading correction, demosaicing, scaling and pixel format conversion
> +	as well as produce statistics for the use of the control
> +	algorithms (e.g. automatic exposure, white balance and focus).
> +
> +    Media API
> +	A set of userspace APIs used to control the media hardware. It is
> +	composed by:
> +
> +	  - :term:`CEC API`;
> +	  - :term:`Digital TV API`;
> +	  - :term:`MC API`;
> +	  - :term:`RC API`; and
> +	  - :term:`V4L2 API`.
> +
> +	See :doc:`index`.
> +
> +    MC API
> +	**Media Controller API**
> +
> +	An API designed to expose and control the relationships between
> +	multimedia devices and sub-devices.
> +
> +	See :ref:`media_controller`.
> +
> +    MC-centric
> +	:term:`V4L2 hardware` that requires a :term:`MC API`.
> +
> +	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
> +	(see :ref:`VIDIOC_QUERYCAP`).
> +
> +	See :ref:`v4l2_hardware_control` for more details.
	
I think this should be documented as referring to drivers, for it's a
property of a driver, not hardware.

There is hardware that better fits for MC-enabled drivers but still has
V4L2-centric driver written for it. The matter is further complicated by
e.g. raw camera systems that may consist of several different kinds of
devices, including external ISPs.

Say, a simple raw sensor + a CSI-2 receiver would fit for V4L2-centric
model well, but add a more complex sensor or that external ISP and that no
longer is the case. The CSI-2 receiver is still the same in both cases
though.

Similar comment on video-node-centric.

The rest looks fine to me.

> +
> +    Media Hardware
> +	Subset of the hardware that is supported by the Linux Media API.
> +
> +	This includes audio and video capture and playback hardware,
> +	digital and analog TV, camera sensors, ISPs, remote controllers,
> +	codecs, HDMI Consumer Electronics Control, HDMI capture, etc.
> +
> +    Microprocessor
> +	Electronic circuitry that carries out the instructions of a
> +	computer program by performing the basic arithmetic, logical,
> +	control and input/output (I/O) operations specified by the
> +	instructions on a single integrated circuit.
> +
> +    Peripheral
> +	The same as :term:`hardware peripheral`.
> +
> +    RC API
> +	**Remote Controller API**
> +
> +	An API designed to receive and transmit data from remote
> +	controllers.
> +
> +	See :ref:`remote_controllers`.
> +
> +    SMBus
> +	A subset of I²C, which defines a stricter usage of the bus.
> +
> +    SPI
> +	**Serial Peripheral Interface Bus**
> +
> +	Synchronous serial communication interface specification used for
> +	short distance communication, primarily in embedded systems.
> +
> +    SoC
> +	**System on a Chip**
> +
> +	An integrated circuit that integrates all components of a computer
> +	or other electronic systems.
> +
> +    V4L2 API
> +	**V4L2 userspace API**
> +
> +	The userspace API defined in :ref:`v4l2spec`, which is used to
> +	control a V4L2 hardware.
> +
> +    V4L2 Device Node
> +	A :term:`device node` that is associated to a V4L driver.
> +
> +	The V4L2 device node naming is specified at :ref:`v4l2_device_naming`.
> +
> +    V4L2 Hardware
> +	Part of the media hardware which is supported by the :term:`V4L2 API`.
> +
> +    V4L2 Sub-device
> +	V4L2 hardware components that aren't controlled by a
> +	:term:`bridge driver`. See :ref:`subdev`.
> +
> +    Video-node-centric
> +	V4L2 hardware that doesn't require a media controller to be used.
> +
> +	Such hardware have the ``V4L2_CAP_IO_MC`` device_caps field unset
> +	(see :ref:`VIDIOC_QUERYCAP`).
> +
> +    V4L2 Sub-device API
> +	Part of the :term:`V4L2 API` which control
> +	:term:`V4L2 sub-devices <V4L2 Sub-device>`, like sensors,
> +	HDMI receivers, scalers, deinterlacers.
> +
> +	See :ref:`v4l2_hardware_control` for more details.
> diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst
> index 70a3f3d73698..7f42f83b9f59 100644
> --- a/Documentation/userspace-api/media/index.rst
> +++ b/Documentation/userspace-api/media/index.rst
> @@ -35,6 +35,9 @@ Please see:
>      mediactl/media-controller
>      cec/cec-api
>      gen-errors
> +
> +    glossary
> +
>      fdl-appendix
>  
>      drivers/index

-- 
Sakari Ailus

Re: [PATCH v10 4/4] media: open.rst: document mc-centric and video-node-centric

[Sakari Ailus]

Hi Mauro,

On Thu, Aug 27, 2020 at 09:21:48AM +0200, Mauro Carvalho Chehab wrote:
> When we added support for omap3, back in 2010, we added a new
> type of V4L2 devices that aren't fully controlled via the V4L2
> device node.
> 
> Yet, we have never clearly documented in the V4L2 specification
> the differences between the two types.
> 
> Let's document them based on the the current implementation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../userspace-api/media/v4l/open.rst          | 58 +++++++++++++++++--
>  1 file changed, 52 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
> index b9367e02b884..e9cfbe954918 100644
> --- a/Documentation/userspace-api/media/v4l/open.rst
> +++ b/Documentation/userspace-api/media/v4l/open.rst
> @@ -13,6 +13,52 @@
>  Opening and Closing Devices
>  ***************************
>  
> +.. _v4l2_hardware_control:
> +
> +Controlling a hardware peripheral via V4L2
> +==========================================
> +
> +A V4L2 hardware peripheral is usually complex: support for it is
> +implemented via a bridge driver and often by several additional drivers.

How about this, instead:

Hardware that is supported using the V4L2 uAPI often consists of multiple
devices or peripherals, each of which have their own driver.

> +The bridge driver exposes one or more V4L2 device nodes
> +(see :ref:`v4l2_device_naming`).
> +
> +There are other drivers providing support for other components of
> +the hardware, which may also expose device nodes, called V4L2 sub-devices.
> +
> +When such V4L2 sub-devices are exposed, they allow controlling those
> +other hardware components - usually connected via a serial bus (like
> +I²C, SMBus or SPI). Depending on the bridge driver, those sub-devices
> +can be controlled indirectly via the bridge driver or explicitly via
> +the :ref:`Media Controller <media_controller>` and via the
> +:ref:`V4L2 sub-devices <subdev>`.
> +
> +The devices that require the use of the
> +:ref:`Media Controller <media_controller>` are called **MC-centric**
> +devices. The devices that are fully controlled via V4L2 device nodes
> +are called **video-node-centric**.
> +
> +Userspace can check if a V4L2 hardware peripheral is MC-centric by
> +calling :ref:`VIDIOC_QUERYCAP` and checking the
> +:ref:`device_caps field <device-capabilities>`.
> +
> +If the device returns ``V4L2_CAP_IO_MC`` flag at ``device_caps``,
> +then it is MC-centric, otherwise, it is video-node-centric.
> +
> +It is required for MC-centric hardware to identify the V4L2

s/hardware/drivers/

> +sub-devices and to configure the pipelines via the
> +:ref:`media controller API <media_controller>` before using the peripheral.
> +Also, the sub-devices' configuration shall be controlled via the
> +:ref:`sub-device API <subdev>`.
> +
> +.. note::
> +
> +   A video-node-centric may still provide media-controller and
> +   sub-device interfaces as well.
> +
> +  However, in that case the media-controller and the sub-device
> +  interfaces are read-only and just provide information about the
> +  device. The actual configuration is done via the video nodes.
>  
>  .. _v4l2_device_naming:
>  
> @@ -109,7 +155,7 @@ Related Devices
>  Devices can support several functions. For example video capturing, VBI
>  capturing and radio support.
>  
> -The V4L2 API creates different nodes for each of these functions.
> +The V4L2 API creates different V4L2 device nodes for each of these functions.
>  
>  The V4L2 API was designed with the idea that one device node could
>  support all functions. However, in practice this never worked: this
> @@ -119,17 +165,17 @@ switching a device node between different functions only works when
>  using the streaming I/O API, not with the
>  :ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
>  
> -Today each device node supports just one function.
> +Today each V4L2 device node supports just one function.
>  
>  Besides video input or output the hardware may also support audio
>  sampling or playback. If so, these functions are implemented as ALSA PCM
>  devices with optional ALSA audio mixer devices.
>  
>  One problem with all these devices is that the V4L2 API makes no
> -provisions to find these related devices. Some really complex devices
> -use the Media Controller (see :ref:`media_controller`) which can be
> -used for this purpose. But most drivers do not use it, and while some
> -code exists that uses sysfs to discover related devices (see
> +provisions to find these related V4L2 device nodes. Some really complex
> +hardware use the Media Controller (see :ref:`media_controller`) which can
> +be used for this purpose. But several drivers do not use it, and while some
> +code exists that uses sysfs to discover related V4L2 device nodes (see
>  libmedia_dev in the
>  `v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
>  repository), there is no library yet that can provide a single API
> 

-- 
Sakari Ailus

Re: [PATCH v10 3/4] media: docs: add glossary.rst with common terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Thu, 27 Aug 2020 14:08:11 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Thu, Aug 27, 2020 at 09:21:47AM +0200, Mauro Carvalho Chehab wrote:
> > Add a glossary of terms used within the media userspace API
> > documentation, as several concepts are complex enough to cause
> > misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  .../userspace-api/media/glossary.rst          | 216 ++++++++++++++++++
> >  Documentation/userspace-api/media/index.rst   |   3 +
> >  2 files changed, 219 insertions(+)
> >  create mode 100644 Documentation/userspace-api/media/glossary.rst
> > 
> > diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
> > new file mode 100644
> > index 000000000000..45f0933e03c0
> > --- /dev/null
> > +++ b/Documentation/userspace-api/media/glossary.rst
> > @@ -0,0 +1,216 @@
> > +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later
> > +
> > +.. For GPL-2.0, see LICENSES/preferred/GPL-2.0
> > +..
> > +.. For GFDL-1.1-or-later, see:
> > +..
> > +.. Permission is granted to copy, distribute and/or modify this document
> > +.. under the terms of the GNU Free Documentation License, Version 1.1 or
> > +.. any later version published by the Free Software Foundation, with no
> > +.. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
> > +.. A copy of the license is included at
> > +.. Documentation/userspace-api/media/fdl-appendix.rst.
> > +
> > +========
> > +Glossary
> > +========
> > +
> > +.. note::
> > +
> > +   The goal of this section is to standardize the terms used within the media
> > +   userspace API documentation. This is Work In Progress.
> > +
> > +.. Please keep the glossary entries in alphabetical order
> > +
> > +.. glossary::
> > +
> > +    Bridge Driver
> > +	A :term:`device driver` that implements the main logic to talk with
> > +	media hardware.
> > +
> > +    CEC API
> > +	**Consumer Electronics Control API**
> > +
> > +	An API designed to receive and transmit data via an HDMI
> > +	CEC interface.
> > +
> > +	See :ref:`cec`.
> > +
> > +    Device Driver
> > +	Part of the Linux Kernel that implements support for a hardware
> > +	component.
> > +
> > +    Device Node
> > +	A character device node in the file system used to control and
> > +	transfer data in and out of a Kernel driver.
> > +
> > +    Digital TV API
> > +	**Previously known as DVB API**
> > +
> > +	An API designed to control a subset of the :term:`Media Hardware`
> > +	that implements	digital TV (e. g. DVB, ATSC, ISDB, etc).
> > +
> > +	See :ref:`dvbapi`.
> > +
> > +    DSP
> > +        **Digital Signal Processor**
> > +
> > +	A specialized :term:`Microprocessor`, with its architecture
> > +	optimized for the operational needs of digital signal processing.
> > +
> > +    FPGA
> > +	**Field-programmable Gate Array**
> > +
> > +	An :term:`IC` circuit designed to be configured by a customer or
> > +	a designer after manufacturing.
> > +
> > +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> > +
> > +    Hardware Component
> > +	A subset of the :term:`media hardware`. For example an :term:`I²C` or
> > +	:term:`SPI` device, or an :term:`IP block` inside an
> > +	:term:`SoC` or :term:`FPGA`.
> > +
> > +    Hardware Peripheral
> > +	A group of :term:`hardware components <hardware component>` that
> > +	together make a larger user-facing functional peripheral. For
> > +	instance, the :term:`SoC` :term:`ISP` :term:`IP block <ip block>`
> > +	and the external camera sensors together make a camera hardware
> > +	peripheral.
> > +
> > +	Also known as :term:`peripheral`.
> > +
> > +    I²C
> > +	**Inter-Integrated Circuit**
> > +
> > +	A  multi-master, multi-slave, packet switched, single-ended,
> > +	serial computer bus used to control some hardware components
> > +	like sub-device hardware components.
> > +
> > +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> > +
> > +    IC
> > +	**Integrated circuit**
> > +
> > +	A set of electronic circuits on one small flat piece of
> > +	semiconductor material, normally silicon.
> > +
> > +	Also known as chip.
> > +
> > +    IP Block
> > +	**Intellectual property core**
> > +
> > +	In electronic design a semiconductor intellectual property core,
> > +	is a reusable unit of logic, cell, or integrated circuit layout
> > +	design that is the intellectual property of one party.
> > +	IP Blocks may be licensed to another party or can be owned
> > +	and used by a single party alone.
> > +
> > +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> > +
> > +    ISP
> > +	**Image Signal Processor**
> > +
> > +	A specialized processor that implements a set of algorithms for
> > +	processing image data. ISPs may implement algorithms for lens
> > +	shading correction, demosaicing, scaling and pixel format conversion
> > +	as well as produce statistics for the use of the control
> > +	algorithms (e.g. automatic exposure, white balance and focus).
> > +
> > +    Media API
> > +	A set of userspace APIs used to control the media hardware. It is
> > +	composed by:
> > +
> > +	  - :term:`CEC API`;
> > +	  - :term:`Digital TV API`;
> > +	  - :term:`MC API`;
> > +	  - :term:`RC API`; and
> > +	  - :term:`V4L2 API`.
> > +
> > +	See :doc:`index`.
> > +
> > +    MC API
> > +	**Media Controller API**
> > +
> > +	An API designed to expose and control the relationships between
> > +	multimedia devices and sub-devices.
> > +
> > +	See :ref:`media_controller`.
> > +
> > +    MC-centric
> > +	:term:`V4L2 hardware` that requires a :term:`MC API`.
> > +
> > +	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
> > +	(see :ref:`VIDIOC_QUERYCAP`).
> > +
> > +	See :ref:`v4l2_hardware_control` for more details.  
> 	
> I think this should be documented as referring to drivers, for it's a
> property of a driver, not hardware.
> 
> There is hardware that better fits for MC-enabled drivers but still has
> V4L2-centric driver written for it. The matter is further complicated by
> e.g. raw camera systems that may consist of several different kinds of
> devices, including external ISPs.
> 
> Say, a simple raw sensor + a CSI-2 receiver would fit for V4L2-centric
> model well, but add a more complex sensor or that external ISP and that no
> longer is the case. The CSI-2 receiver is still the same in both cases
> though.
> 
> Similar comment on video-node-centric.

Makes sense. Do you have some suggestion for the text??

> 
> The rest looks fine to me.

Ok.

Thanks,
Mauro

Re: [PATCH v10 3/4] media: docs: add glossary.rst with common terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Thu, 27 Aug 2020 14:08:11 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> > +    MC-centric
> > +	:term:`V4L2 hardware` that requires a :term:`MC API`.
> > +
> > +	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
> > +	(see :ref:`VIDIOC_QUERYCAP`).
> > +
> > +	See :ref:`v4l2_hardware_control` for more details.  
> 	
> I think this should be documented as referring to drivers, for it's a
> property of a driver, not hardware.
> 
> There is hardware that better fits for MC-enabled drivers but still has
> V4L2-centric driver written for it. The matter is further complicated by
> e.g. raw camera systems that may consist of several different kinds of
> devices, including external ISPs.
> 
> Say, a simple raw sensor + a CSI-2 receiver would fit for V4L2-centric
> model well, but add a more complex sensor or that external ISP and that no
> longer is the case. The CSI-2 receiver is still the same in both cases
> though.
> 
> Similar comment on video-node-centric.

I guess I got what you meant. I'm folding it with the following diff:

diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
index 45f0933e03c0..023bb561c406 100644
--- a/Documentation/userspace-api/media/glossary.rst
+++ b/Documentation/userspace-api/media/glossary.rst
@@ -138,9 +138,9 @@ Glossary
 	See :ref:`media_controller`.
 
     MC-centric
-	:term:`V4L2 hardware` that requires a :term:`MC API`.
+	:term:`V4L2 hardware` device driver that requires :term:`MC API`.
 
-	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
+	Such drivers have ``V4L2_CAP_IO_MC`` device_caps field set
 	(see :ref:`VIDIOC_QUERYCAP`).
 
 	See :ref:`v4l2_hardware_control` for more details.
@@ -203,9 +203,9 @@ Glossary
 	:term:`bridge driver`. See :ref:`subdev`.
 
     Video-node-centric
-	V4L2 hardware that doesn't require a media controller to be used.
+	V4L2 device driver that doesn't require a media controller to be used.
 
-	Such hardware have the ``V4L2_CAP_IO_MC`` device_caps field unset
+	Such drivers have the ``V4L2_CAP_IO_MC`` device_caps field unset
 	(see :ref:`VIDIOC_QUERYCAP`).
 
     V4L2 Sub-device API


Thanks,
Mauro

Re: [PATCH v10 3/4] media: docs: add glossary.rst with common terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

On Fri, Aug 28, 2020 at 11:11:00AM +0200, Mauro Carvalho Chehab wrote:
> Em Thu, 27 Aug 2020 14:08:11 +0300
> Sakari Ailus <sakari.ailus@iki.fi> escreveu:
> 
> > > +    MC-centric
> > > +	:term:`V4L2 hardware` that requires a :term:`MC API`.
> > > +
> > > +	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
> > > +	(see :ref:`VIDIOC_QUERYCAP`).
> > > +
> > > +	See :ref:`v4l2_hardware_control` for more details.  
> > 	
> > I think this should be documented as referring to drivers, for it's a
> > property of a driver, not hardware.
> > 
> > There is hardware that better fits for MC-enabled drivers but still has
> > V4L2-centric driver written for it. The matter is further complicated by
> > e.g. raw camera systems that may consist of several different kinds of
> > devices, including external ISPs.
> > 
> > Say, a simple raw sensor + a CSI-2 receiver would fit for V4L2-centric
> > model well, but add a more complex sensor or that external ISP and that no
> > longer is the case. The CSI-2 receiver is still the same in both cases
> > though.
> > 
> > Similar comment on video-node-centric.
> 
> I guess I got what you meant. I'm folding it with the following diff:
> 
> diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
> index 45f0933e03c0..023bb561c406 100644
> --- a/Documentation/userspace-api/media/glossary.rst
> +++ b/Documentation/userspace-api/media/glossary.rst
> @@ -138,9 +138,9 @@ Glossary
>  	See :ref:`media_controller`.
>  
>      MC-centric
> -	:term:`V4L2 hardware` that requires a :term:`MC API`.
> +	:term:`V4L2 hardware` device driver that requires :term:`MC API`.
>  
> -	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field set
> +	Such drivers have ``V4L2_CAP_IO_MC`` device_caps field set
>  	(see :ref:`VIDIOC_QUERYCAP`).
>  
>  	See :ref:`v4l2_hardware_control` for more details.
> @@ -203,9 +203,9 @@ Glossary
>  	:term:`bridge driver`. See :ref:`subdev`.
>  
>      Video-node-centric
> -	V4L2 hardware that doesn't require a media controller to be used.
> +	V4L2 device driver that doesn't require a media controller to be used.
>  
> -	Such hardware have the ``V4L2_CAP_IO_MC`` device_caps field unset
> +	Such drivers have the ``V4L2_CAP_IO_MC`` device_caps field unset
>  	(see :ref:`VIDIOC_QUERYCAP`).
>  
>      V4L2 Sub-device API

Yes, something like that. I also looked at a few more terms such as "V4L2
hardware" that are a bit of an oxymoron. This isn't in current
documentation so we should give them a little bit more thought before
adding them. I'll reply to the latest patch.

-- 
Kind regards,

Sakari Ailus