Skip to contentSkip to conversation

Add a glossary for the media subsystem

PATCH Superseded Mauro Carvalho Chehab 2 participants 15 messages May 8, 2020 Media (V4L/DVB)

v9 of 11 Superseded Latest is v11 →

lore
Share & tools
lore
#0 lore raw

v9 cover Add a glossary for the media subsystem

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.

At version 9 (and hopefully the final version), I simplified how things were described, avoiding to define things that may not be needed for this initial version, in order to try reach a consensus when merging.

If something is not ok, or other terms need to be added, feel free to submit other patches addressing it.

Mauro Carvalho Chehab (5):
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: glossary.rst: add terms for MC-centric video-node-centric
media: open.rst: document mc-centric and video-node-centric

 .../userspace-api/media/glossary.rst          | 214 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 .../userspace-api/media/v4l/open.rst          | 106 +++++++--
 3 files changed, 309 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/userspace-api/media/glossary.rst
Signature · 1 line
2.26.2
#1 lore raw

PATCH v9 1/5 media: open.rst: better document device node naming

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 identify for a given device.

---
 .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +40 -3
index 38046ef20141..86816b247a17 100644
@@ -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 input/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-sudevX``	 Video sub-devices (used by sensors and other I2C
+			 devices)\ [#]_
+======================== ======================================================
+
+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-sudevX``) 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
Signature · 1 line
2.26.2
#2 lore raw

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

Quoted 3 lines · 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 identify for a given device.

identifier

Quoted 30 lines
---
 .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +5 -3
index 38046ef20141..86816b247a17 100644
@@ -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.
 

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 40

Quoted 9 lines
Documentation/userspace-api/media/v4l/open.rst +6 -0
@@ -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 input/output devices

Also metadata input/output devices.

I would prefer capture/output given the traditional names that V4L2 uses.

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 45

Quoted 5 lines
Documentation/userspace-api/media/v4l/open.rst +5 -0
+``/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-sudevX``	 Video sub-devices (used by sensors and other I2C

sudevX -> subdevX

You made this typo in more places, it's best to search and replace.

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 46

Quoted 1 line
Documentation/userspace-api/media/v4l/open.rst +1 -0
+			 devices)\ [#]_

That suggests that subdevs are i2c devices, they can be any processing block on any bus.

Quoted 16 lines
Documentation/userspace-api/media/v4l/open.rst +16 -0
+======================== ======================================================
+
+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

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 72

Quoted 10 lines
Documentation/userspace-api/media/v4l/open.rst +7 -0
+	│   └── 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-sudevX``) 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

It looks like there is a missing period at the end of the sentence.

Quoted 1 line

Regards,

Hans

#3 lore raw

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

Em Fri, 8 May 2020 15:24:33 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 57 lines · Mauro Carvalho Chehab
Quoted 3 lines

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 identify for a given device.

identifier

Quoted 30 lines
---
 .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +5 -3
index 38046ef20141..86816b247a17 100644
@@ -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.
 

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 40

Quoted 9 lines
Documentation/userspace-api/media/v4l/open.rst +6 -0
@@ -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 input/output devices  

Also metadata input/output devices.

I would prefer capture/output given the traditional names that V4L2 uses.

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 45

Quoted 5 lines
Documentation/userspace-api/media/v4l/open.rst +5 -0
+``/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-sudevX``	 Video sub-devices (used by sensors and other I2C  
Quoted 8 lines

sudevX -> subdevX

You made this typo in more places, it's best to search and replace.

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 46

Quoted 1 line
Documentation/userspace-api/media/v4l/open.rst +1 -0
+			 devices)\ [#]_  

That suggests that subdevs are i2c devices, they can be any processing block on any bus.

For all the above: Ok. Will address at the next version.

Quoted 21 lines
Quoted 21 lines
Documentation/userspace-api/media/v4l/open.rst +20 -0
+======================== ======================================================
+
+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
+
Quoted 8 lines

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 72

Quoted 6 lines
Documentation/userspace-api/media/v4l/open.rst +3 -0
+.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) 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  

It looks like there is a missing period at the end of the sentence.

The full sentence here is:

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 of leaving it to chance. When the driver supports multiple devices of the same type more than one device node number can be assigned, separated by commas:

This paragraph (untouched by this patch) sounds ok to me ;-)

Thanks,
Mauro

#4 lore raw

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

Quoted 104 lines · Mauro Carvalho Chehab

Em Fri, 8 May 2020 15:24:33 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 57 lines · Mauro Carvalho Chehab
Quoted 3 lines

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 identify for a given device.

identifier

Quoted 30 lines
---
 .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +5 -3
index 38046ef20141..86816b247a17 100644
@@ -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.
 

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 40

Quoted 9 lines
Documentation/userspace-api/media/v4l/open.rst +6 -0
@@ -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 input/output devices  

Also metadata input/output devices.

I would prefer capture/output given the traditional names that V4L2 uses.

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 45

Quoted 5 lines
Documentation/userspace-api/media/v4l/open.rst +5 -0
+``/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-sudevX``	 Video sub-devices (used by sensors and other I2C  
Quoted 8 lines

sudevX -> subdevX

You made this typo in more places, it's best to search and replace.

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 46

Quoted 1 line
Documentation/userspace-api/media/v4l/open.rst +1 -0
+			 devices)\ [#]_  

That suggests that subdevs are i2c devices, they can be any processing block on any bus.

For all the above: Ok. Will address at the next version.

Quoted 21 lines
Quoted 21 lines
Documentation/userspace-api/media/v4l/open.rst +20 -0
+======================== ======================================================
+
+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
+
Quoted 8 lines

Documentation/userspace-api/media/v4l/open.rst option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers · line 72

Quoted 6 lines
Documentation/userspace-api/media/v4l/open.rst +3 -0
+.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) 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  

It looks like there is a missing period at the end of the sentence.

The full sentence here is:

Quoted 8 lines

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 of leaving it to chance. When the driver supports multiple devices of the same type more than one device node number can be assigned, separated by commas:

This paragraph (untouched by this patch) sounds ok to me ;-)

Ah yes, I misread the patch. It looked like there was an empty line after 'instead'. Never mind :-)

Regards,

Hans

Quoted 4 lines

Thanks,
Mauro

#5 lore raw

PATCH v9 2/5 media: open.rst: remove the minor number range

In reply to 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.

---
 Documentation/userspace-api/media/v4l/open.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +4 -5
index 86816b247a17..ee4c8f123815 100644
@@ -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:
 
Signature · 1 line
2.26.2
#6 lore raw

PATCH v9 3/5 media: docs: add glossary.rst with common terms used at V4L2 spec

In reply to Mauro Carvalho Chehab

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

---
 .../userspace-api/media/glossary.rst          | 182 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 2 files changed, 185 insertions(+)
 create mode 100644 Documentation/userspace-api/media/glossary.rst
Documentation/userspace-api/media/glossary.rst new file +182 -0
new file mode 100644
index 000000000000..18a1ace00159
@@ -0,0 +1,182 @@
+.. 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::
+
+   This goal of this section is to standardize the terms used within the media
+   userspace API documentation. It is written incrementally as they are
+   standardized in the media documentation.
+
+   So, it is a 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
+	ransfer 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.
+
+	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.
+
+    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:`v4l/v4l2`.
+
+    MC API
+	**Media Controller API**
+
+	An API designed to expose and control the relationships between
+	devices and sub-devices.
+
+	See :ref:`media_controller`.
+
+    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.
+
+    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 Hardware
+	Part of a media hardware with is supported by the :term:`V4L2 API`.
+
+    V4L2 Sub-device
+	V4L2 hardware components that aren't controlled by a
+	:term:`bridge driver`.
+
+    V4L2 Sub-device API
+	Part of the :term:`V4L2 API` which control
+	:term:`V4L2 sub-devices <V4L2 Sub-device>`.
+
+	See :ref:`subdev`.
Documentation/userspace-api/media/index.rst +3 -0
index 70a3f3d73698..7f42f83b9f59 100644
@@ -35,6 +35,9 @@ Please see:
     mediactl/media-controller
     cec/cec-api
     gen-errors
+
+    glossary
+
     fdl-appendix
 
     drivers/index
Signature · 1 line
2.26.2
#7 lore raw

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

Quoted 27 lines · Mauro Carvalho Chehab

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

---
 .../userspace-api/media/glossary.rst          | 182 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 2 files changed, 185 insertions(+)
 create mode 100644 Documentation/userspace-api/media/glossary.rst
Documentation/userspace-api/media/glossary.rst new file +10 -0
new file mode 100644
index 000000000000..18a1ace00159
@@ -0,0 +1,182 @@
+.. 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.

Documentation/userspace-api/media/glossary.rst line 20

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+.. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+
+========
+Glossary
+========
+
+.. note::
+
+   This goal of this section is to standardize the terms used within the media

This -> The

Documentation/userspace-api/media/glossary.rst line 24

Quoted 4 lines
Documentation/userspace-api/media/glossary.rst new file +4 -0
+   userspace API documentation. It is written incrementally as they are
+   standardized in the media documentation.
+
+   So, it is a Work In Progress.

I'd just say:

userspace API documentation. This is Work in Progress.

Quoted 14 lines
Documentation/userspace-api/media/glossary.rst new file +14 -0
+
+.. 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.

Documentation/userspace-api/media/glossary.rst line 48

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+
+	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
+	ransfer data in and out of a Kernel driver.

ransfer -> transfer

Documentation/userspace-api/media/glossary.rst line 54

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst new file +6 -0
+
+    Digital TV API
+	**Previously known as DVB API**
+
+	An API designed to control a subset of the :term:`Media Hardware`
+	that implements	digital TV.

I think it will help to provide some examples, e.g.:

that implements digital TV (e.g. DVB, ATSC, etc.).

Quoted 55 lines
Documentation/userspace-api/media/glossary.rst new file +55 -0
+
+	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.
+
+    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

Documentation/userspace-api/media/glossary.rst line 119

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+	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:`v4l/v4l2`.

Is that the right reference? I'd expect that v4l/v4l2 refers to the V4L2 API and not the whole media API.

Documentation/userspace-api/media/glossary.rst line 125

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst new file +6 -0
+
+    MC API
+	**Media Controller API**
+
+	An API designed to expose and control the relationships between
+	devices and sub-devices.

I'd say 'media devices and sub-devices'. Otherwise it would suggest that the MC API also supports non-media devices.

Quoted 37 lines
Documentation/userspace-api/media/glossary.rst new file +37 -0
+
+	See :ref:`media_controller`.
+
+    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.
+
+    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

Documentation/userspace-api/media/glossary.rst line 172

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+	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 Hardware
+	Part of a media hardware with is supported by the :term:`V4L2 API`.

of a -> of the
with -> which

Documentation/userspace-api/media/glossary.rst line 176

Quoted 4 lines
Documentation/userspace-api/media/glossary.rst new file +4 -0
+
+    V4L2 Sub-device
+	V4L2 hardware components that aren't controlled by a
+	:term:`bridge driver`.

I'd give some examples here as well: sensors, HDMI receivers, scalers, deinterlacers. Otherwise this is too vague.

Documentation/userspace-api/media/glossary.rst line 179

Quoted 3 lines
Documentation/userspace-api/media/glossary.rst new file +3 -0
+
+    V4L2 Sub-device API
+	Part of the :term:`V4L2 API` which control

control -> controls

Quoted 9 lines
Documentation/userspace-api/media/glossary.rst new file +3 -0
+	:term:`V4L2 sub-devices <V4L2 Sub-device>`.
+
+	See :ref:`subdev`.
Documentation/userspace-api/media/index.rst +0 -0
index 70a3f3d73698..7f42f83b9f59 100644

Documentation/userspace-api/media/index.rst Please see: · line 43

Quoted 9 lines
Documentation/userspace-api/media/index.rst +3 -0
@@ -35,6 +35,9 @@ Please see:
     mediactl/media-controller
     cec/cec-api
     gen-errors
+
+    glossary
+
     fdl-appendix
 
     drivers/index

Regards,

Hans

#8 lore raw

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

Em Fri, 8 May 2020 15:40:25 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 86 lines · Mauro Carvalho Chehab
Quoted 27 lines

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

---
 .../userspace-api/media/glossary.rst          | 182 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 2 files changed, 185 insertions(+)
 create mode 100644 Documentation/userspace-api/media/glossary.rst
Documentation/userspace-api/media/glossary.rst new file +10 -0
new file mode 100644
index 000000000000..18a1ace00159
@@ -0,0 +1,182 @@
+.. 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.

Documentation/userspace-api/media/glossary.rst line 20

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+.. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+
+========
+Glossary
+========
+
+.. note::
+
+   This goal of this section is to standardize the terms used within the media  

This -> The

Documentation/userspace-api/media/glossary.rst line 24

Quoted 4 lines
Documentation/userspace-api/media/glossary.rst new file +4 -0
+   userspace API documentation. It is written incrementally as they are
+   standardized in the media documentation.
+
+   So, it is a Work In Progress.  

I'd just say:

userspace API documentation. This is Work in Progress.

Quoted 14 lines
Documentation/userspace-api/media/glossary.rst new file +14 -0
+
+.. 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.

Documentation/userspace-api/media/glossary.rst line 48

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+
+	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
+	ransfer data in and out of a Kernel driver.  

ransfer -> transfer

Documentation/userspace-api/media/glossary.rst line 54

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst new file +6 -0
+
+    Digital TV API
+	**Previously known as DVB API**
+
+	An API designed to control a subset of the :term:`Media Hardware`
+	that implements	digital TV.  

I think it will help to provide some examples, e.g.:

Quoted 1 line

that implements digital TV (e.g. DVB, ATSC, etc.).

For the above: Ok!

Quoted 61 lines
Quoted 61 lines
Documentation/userspace-api/media/glossary.rst new file +60 -0
+
+	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.
+
+    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`;
Quoted 8 lines

Documentation/userspace-api/media/glossary.rst line 119

Quoted 5 lines
Documentation/userspace-api/media/glossary.rst new file +5 -0
+	  - :term:`MC API`;
+	  - :term:`RC API`; and
+	  - :term:`V4L2 API`.
+
+	See :doc:`v4l/v4l2`.  

Is that the right reference? I'd expect that v4l/v4l2 refers to the V4L2 API and not the whole media API.

That's the right reference: userspace-api/media/v4l/v4l2.rst file has just the V4L2 API.

The entire API file is now at userspace-api/media/index.html.

Quoted 10 lines

Documentation/userspace-api/media/glossary.rst line 125

Quoted 7 lines
Documentation/userspace-api/media/glossary.rst new file +6 -0
+
+    MC API
+	**Media Controller API**
+
+	An API designed to expose and control the relationships between
+	devices and sub-devices.  

I'd say 'media devices and sub-devices'. Otherwise it would suggest that the MC API also supports non-media devices.

Yeah, it sounds too generic, but MC is currently used also by audio devices.

Ok, "audio" is "media", but not covered by this spec.

We might use "multimedia" or some similar word. What do you think?

Thanks,
Mauro

#9 lore raw

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

Quoted 163 lines · Mauro Carvalho Chehab

Em Fri, 8 May 2020 15:40:25 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 86 lines · Mauro Carvalho Chehab
Quoted 27 lines

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

---
 .../userspace-api/media/glossary.rst          | 182 ++++++++++++++++++
 Documentation/userspace-api/media/index.rst   |   3 +
 2 files changed, 185 insertions(+)
 create mode 100644 Documentation/userspace-api/media/glossary.rst
Documentation/userspace-api/media/glossary.rst new file +10 -0
new file mode 100644
index 000000000000..18a1ace00159
@@ -0,0 +1,182 @@
+.. 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.

Documentation/userspace-api/media/glossary.rst line 20

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+.. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+
+========
+Glossary
+========
+
+.. note::
+
+   This goal of this section is to standardize the terms used within the media  

This -> The

Documentation/userspace-api/media/glossary.rst line 24

Quoted 4 lines
Documentation/userspace-api/media/glossary.rst new file +4 -0
+   userspace API documentation. It is written incrementally as they are
+   standardized in the media documentation.
+
+   So, it is a Work In Progress.  

I'd just say:

userspace API documentation. This is Work in Progress.

Quoted 14 lines
Documentation/userspace-api/media/glossary.rst new file +14 -0
+
+.. 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.

Documentation/userspace-api/media/glossary.rst line 48

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst new file +10 -0
+
+	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
+	ransfer data in and out of a Kernel driver.  

ransfer -> transfer

Documentation/userspace-api/media/glossary.rst line 54

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst new file +6 -0
+
+    Digital TV API
+	**Previously known as DVB API**
+
+	An API designed to control a subset of the :term:`Media Hardware`
+	that implements	digital TV.  

I think it will help to provide some examples, e.g.:

Quoted 1 line

that implements digital TV (e.g. DVB, ATSC, etc.).

For the above: Ok!

Quoted 61 lines
Quoted 61 lines
Documentation/userspace-api/media/glossary.rst new file +60 -0
+
+	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.
+
+    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`;
Quoted 8 lines

Documentation/userspace-api/media/glossary.rst line 119

Quoted 5 lines
Documentation/userspace-api/media/glossary.rst new file +5 -0
+	  - :term:`MC API`;
+	  - :term:`RC API`; and
+	  - :term:`V4L2 API`.
+
+	See :doc:`v4l/v4l2`.  

Is that the right reference? I'd expect that v4l/v4l2 refers to the V4L2 API and not the whole media API.

Quoted 2 lines

That's the right reference: userspace-api/media/v4l/v4l2.rst file has just the V4L2 API.

That's what I mean: This is the glossary entry for 'Media API', so why have a reference to the V4L2 API? I expect to see a reference to the top-level media API.

Quoted 14 lines

The entire API file is now at userspace-api/media/index.html.

Quoted 10 lines

Documentation/userspace-api/media/glossary.rst line 125

Quoted 7 lines
Documentation/userspace-api/media/glossary.rst new file +6 -0
+
+    MC API
+	**Media Controller API**
+
+	An API designed to expose and control the relationships between
+	devices and sub-devices.  

I'd say 'media devices and sub-devices'. Otherwise it would suggest that the MC API also supports non-media devices.

Quoted 5 lines

Yeah, it sounds too generic, but MC is currently used also by audio devices.>
Ok, "audio" is "media", but not covered by this spec.

We might use "multimedia" or some similar word. What do you think?

Multimedia is fine. Or audio/video.

Regards,

Hans

Quoted 4 lines

Thanks,
Mauro

#10 lore raw

PATCH v9 4/5 media: glossary.rst: add terms for MC-centric video-node-centric

In reply to Mauro Carvalho Chehab

Now that we have a chapter describing hardware control, let's add the terms used there to the glossary.

---
 .../userspace-api/media/glossary.rst          | 42 ++++++++++++++++---
 1 file changed, 37 insertions(+), 5 deletions(-)
Documentation/userspace-api/media/glossary.rst +37 -5
index 18a1ace00159..8cdb7900e994 100644
@@ -69,6 +69,20 @@ Glossary
 
 	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 a
+	: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 external camera sensors together make a camera hardware
+	peripheral.
+
+	Also known as :term:`peripheral`.
+
     I²C
 	**Inter-Integrated Circuit**
 
@@ -126,6 +140,14 @@ Glossary
 
 	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 unset
+	(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.
 
@@ -139,6 +161,9 @@ Glossary
 	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**
 
@@ -168,15 +193,22 @@ Glossary
 	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 a media hardware with is supported by the :term:`V4L2 API`.
 
     V4L2 Sub-device
 	V4L2 hardware components that aren't controlled by a
-	:term:`bridge driver`.
+	:term:`bridge driver`. See :ref:`subdev`.
 
-    V4L2 Sub-device API
-	Part of the :term:`V4L2 API` which control
-	:term:`V4L2 sub-devices <V4L2 Sub-device>`.
+    Video-node-Centric
+	V4L2 hardware that doesn't require a media controller to be used.
 
-	See :ref:`subdev`.
+	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset
+	(see :ref:`VIDIOC_QUERYCAP`).
+
+	See :ref:`v4l2_hardware_control` for more details.
Signature · 1 line
2.26.2
#11 lore raw

Re: [PATCH v9 4/5] media: glossary.rst: add terms for MC-centric video-node-centric

Quoted 13 lines · Mauro Carvalho Chehab

Now that we have a chapter describing hardware control, let's add the terms used there to the glossary.

---
 .../userspace-api/media/glossary.rst          | 42 ++++++++++++++++---
 1 file changed, 37 insertions(+), 5 deletions(-)
Documentation/userspace-api/media/glossary.rst +0 -0
index 18a1ace00159..8cdb7900e994 100644

Documentation/userspace-api/media/glossary.rst Glossary · line 74

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst +3 -0
@@ -69,6 +69,20 @@ Glossary
 
 	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 a

inside a -> inside an

Documentation/userspace-api/media/glossary.rst Glossary · line 80

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst +6 -0
+	: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>`

Are there some commas missing here after 'SoC' and 'ISP'?

Quoted 9 lines
Documentation/userspace-api/media/glossary.rst +5 -0
+	and external camera sensors together make a camera hardware
+	peripheral.
+
+	Also known as :term:`peripheral`.
+
     I²C
 	**Inter-Integrated Circuit**
 

Documentation/userspace-api/media/glossary.rst Glossary · line 144

Quoted 5 lines
Documentation/userspace-api/media/glossary.rst +2 -0
@@ -126,6 +140,14 @@ Glossary
 
 	See :ref:`media_controller`.
 
+    MC-Centric
+	:term:`V4L2 hardware` that requires a :term:`MC API`.

a -> the

Documentation/userspace-api/media/glossary.rst Glossary · line 146

Quoted 2 lines
Documentation/userspace-api/media/glossary.rst +2 -0
+
+	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset

They have that capability set, not unset.

Quoted 28 lines
Documentation/userspace-api/media/glossary.rst +12 -0
+	(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.
 
@@ -139,6 +161,9 @@ Glossary
 	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**
 
@@ -168,15 +193,22 @@ Glossary
 	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 a media hardware with is supported by the :term:`V4L2 API`.

Documentation/userspace-api/media/glossary.rst Glossary · line 208

Quoted 10 lines
Documentation/userspace-api/media/glossary.rst +2 -4
 
     V4L2 Sub-device
 	V4L2 hardware components that aren't controlled by a
-	:term:`bridge driver`.
+	:term:`bridge driver`. See :ref:`subdev`.
 
-    V4L2 Sub-device API
-	Part of the :term:`V4L2 API` which control
-	:term:`V4L2 sub-devices <V4L2 Sub-device>`.
+    Video-node-Centric

Either Video-Node-Centric or Video-node-centric, but not Video-node-Centric, that's inconsistent use of capitals.

Documentation/userspace-api/media/glossary.rst Glossary · line 209

Quoted 1 line
Documentation/userspace-api/media/glossary.rst +1 -0
+	V4L2 hardware that doesn't require a media controller to be used.

a media controller to be used -> the MC API.

Documentation/userspace-api/media/glossary.rst Glossary

Quoted 7 lines
Documentation/userspace-api/media/glossary.rst +4 -1
-	See :ref:`subdev`.
+	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset
+	(see :ref:`VIDIOC_QUERYCAP`).
+
+	See :ref:`v4l2_hardware_control` for more details.
 

Regards,

Hans

#12 lore raw

Re: [PATCH v9 4/5] media: glossary.rst: add terms for MC-centric video-node-centric

Em Fri, 8 May 2020 15:46:50 +0200
Hans Verkuil <[email protected]> escreveu:

Quoted 23 lines · Mauro Carvalho Chehab
Quoted 13 lines

Now that we have a chapter describing hardware control, let's add the terms used there to the glossary.

---
 .../userspace-api/media/glossary.rst          | 42 ++++++++++++++++---
 1 file changed, 37 insertions(+), 5 deletions(-)
Documentation/userspace-api/media/glossary.rst +0 -0
index 18a1ace00159..8cdb7900e994 100644

Documentation/userspace-api/media/glossary.rst Glossary · line 74

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst +3 -0
@@ -69,6 +69,20 @@ Glossary
 
 	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 a  

inside a -> inside an

Quoted 8 lines

Documentation/userspace-api/media/glossary.rst Glossary · line 80

Quoted 6 lines
Documentation/userspace-api/media/glossary.rst +6 -0
+	: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>`  

Are there some commas missing here after 'SoC' and 'ISP'?

There is a comma missing, but not at the place you pointed (IMHO) ;-)

Removing the :term: markup, what the above is saying is:

For instance, the SoC ISP IP block and external camera sensors together make a camera hardware peripheral.

Ok, we could just call it as "ISP", instead of trying to be too formal.

Quoted 18 lines
Quoted 10 lines
Documentation/userspace-api/media/glossary.rst +5 -0
+	and external camera sensors together make a camera hardware
+	peripheral.
+
+	Also known as :term:`peripheral`.
+
     I²C
 	**Inter-Integrated Circuit**
 

Documentation/userspace-api/media/glossary.rst Glossary · line 144

Quoted 5 lines
Documentation/userspace-api/media/glossary.rst +2 -0
@@ -126,6 +140,14 @@ Glossary
 
 	See :ref:`media_controller`.
 
+    MC-Centric
+	:term:`V4L2 hardware` that requires a :term:`MC API`.  

a -> the

Quoted 4 lines

Documentation/userspace-api/media/glossary.rst Glossary · line 146

Quoted 2 lines
Documentation/userspace-api/media/glossary.rst +2 -0
+
+	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset  

They have that capability set, not unset.

Sorry, cut and paste error... it is identical to the video-node-centric below ;-)

Quoted 35 lines
Quoted 35 lines
Documentation/userspace-api/media/glossary.rst +13 -1
+	(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.
 
@@ -139,6 +161,9 @@ Glossary
 	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**
 
@@ -168,15 +193,22 @@ Glossary
 	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 a media hardware with is supported by the :term:`V4L2 API`.
 
     V4L2 Sub-device
 	V4L2 hardware components that aren't controlled by a
-	:term:`bridge driver`.
+	:term:`bridge driver`. See :ref:`subdev`.
 
Quoted 7 lines

Documentation/userspace-api/media/glossary.rst Glossary · line 208

Quoted 4 lines
Documentation/userspace-api/media/glossary.rst +1 -3
-    V4L2 Sub-device API
-	Part of the :term:`V4L2 API` which control
-	:term:`V4L2 sub-devices <V4L2 Sub-device>`.
+    Video-node-Centric  

Either Video-Node-Centric or Video-node-centric, but not Video-node-Centric, that's inconsistent use of capitals.

Ok.

Quoted 15 lines

Documentation/userspace-api/media/glossary.rst Glossary · line 209

Quoted 2 lines
Documentation/userspace-api/media/glossary.rst +1 -0
+	V4L2 hardware that doesn't require a media controller to be used.  

a media controller to be used -> the MC API.

Documentation/userspace-api/media/glossary.rst Glossary

Quoted 7 lines
Documentation/userspace-api/media/glossary.rst +4 -1
-	See :ref:`subdev`.
+	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset
+	(see :ref:`VIDIOC_QUERYCAP`).
+
+	See :ref:`v4l2_hardware_control` for more details.
 

Regards,

Quoted 1 line

Hans

Thanks,
Mauro

#13 lore raw

PATCH v9 5/5 media: open.rst: document mc-centric and video-node-centric

In reply to 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.

---
 .../userspace-api/media/v4l/open.rst          | 54 ++++++++++++++++---
 1 file changed, 48 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +48 -6
index ee4c8f123815..8a9f766ab855 100644
@@ -13,6 +13,48 @@
 Opening and Closing Devices
 ***************************
 
+.. _v4l2_hardware_control:
+
+Controlling a hardware peripheral via V4L2
+==========================================
+
+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, with may also expose device nodes, called V4L2 sub-devices.
+
+When such V4L2 sub-devices are exposed, they allow controlling
+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``,
+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 a both media-controller and
+   sub-device interfaces as well.
 
 .. _v4l2_device_naming:
 
@@ -109,7 +151,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 +161,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
Signature · 1 line
2.26.2
#14 lore raw

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

Quoted 19 lines · 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.

---
 .../userspace-api/media/v4l/open.rst          | 54 ++++++++++++++++---
 1 file changed, 48 insertions(+), 6 deletions(-)
Documentation/userspace-api/media/v4l/open.rst +0 -0
index ee4c8f123815..8a9f766ab855 100644

Documentation/userspace-api/media/v4l/open.rst line 21

Quoted 9 lines
Documentation/userspace-api/media/v4l/open.rst +6 -0
@@ -13,6 +13,48 @@
 Opening and Closing Devices
 ***************************
 
+.. _v4l2_hardware_control:
+
+Controlling a hardware peripheral via V4L2
+==========================================
+
+V4L2 hardware peripheral is usually complex: support for it is

V4L2 -> A V4L2

Documentation/userspace-api/media/v4l/open.rst line 27

Quoted 6 lines
Documentation/userspace-api/media/v4l/open.rst +6 -0
+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, with may also expose device nodes, called V4L2 sub-devices.

with -> which

Documentation/userspace-api/media/v4l/open.rst line 30

Quoted 3 lines
Documentation/userspace-api/media/v4l/open.rst +3 -0
+
+When such V4L2 sub-devices are exposed, they allow controlling
+other hardware components - usually connected via a serial bus (like

other -> those other

Quoted 6 lines
Documentation/userspace-api/media/v4l/open.rst +6 -0
+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

Documentation/userspace-api/media/v4l/open.rst line 46

Quoted 10 lines
Documentation/userspace-api/media/v4l/open.rst +10 -0
+: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``,
+it is MC-centric, otherwise, it is video-node-centric.

then it is MC-centric, otherwise it is video-node-centric.

Documentation/userspace-api/media/v4l/open.rst line 56

Quoted 10 lines
Documentation/userspace-api/media/v4l/open.rst +10 -0
+
+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 a both media-controller and

a both -> the

Documentation/userspace-api/media/v4l/open.rst line 57

Quoted 1 line
Documentation/userspace-api/media/v4l/open.rst +1 -0
+   sub-device interfaces as well.

Add:

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.

Quoted 26 lines
Documentation/userspace-api/media/v4l/open.rst +2 -3
 .. _v4l2_device_naming:
 
@@ -109,7 +151,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 +161,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

Documentation/userspace-api/media/v4l/open.rst switching a device node between different functions only works when · line 177

Quoted 10 lines
Documentation/userspace-api/media/v4l/open.rst +4 -3
-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

Regards,

Hans