[PATCH 0/3] Add a glossary and fix some issues at open.rst docs

[PATCH 0/3] Add a glossary and fix some issues at open.rst docs

[Mauro Carvalho Chehab]

Those three patches were part of an attempt to add definitions for
some terms used at the media subsystem:

	https://lwn.net/Articles/732022/

On that time, the first patch generated heated discussions, on terms
related to mc-centric/vdev-centric. The cern of the discussions were
how to call the subdev API and the non-subdev API part of the 
video4linux API.

I ended by being side-tracked by other things, and didn't have a chance
to submit an updated version.

Well, now I'm doing things differently: at the glossary.rst, I removed
everything related to hardware control. So, it should contain only the
terms that there aren't any divergences. So, I hope we can manage to
merge it this time.

After having this series merged, I'll address again the MC/vdev centric
hardware control on a separate patchset, perhaps using a different
approach together with the new glossary definitions related
to it.

Mauro Carvalho Chehab (3):
  media: add glossary.rst with common terms used at V4L2 spec
  media: open.rst: better document device node naming
  media: open.rst: remove the minor number range

 Documentation/media/uapi/v4l/glossary.rst | 108 ++++++++++++++++++++++
 Documentation/media/uapi/v4l/open.rst     |  53 +++++++++--
 Documentation/media/uapi/v4l/v4l2.rst     |   1 +
 3 files changed, 154 insertions(+), 8 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

-- 
2.17.1

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

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Add a glossary of terms for V4L2, as several concepts are complex
enough to cause misunderstandings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/media/uapi/v4l/glossary.rst | 108 ++++++++++++++++++++++
 Documentation/media/uapi/v4l/v4l2.rst     |   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
new file mode 100644
index 000000000000..3dff6430d79f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -0,0 +1,108 @@
+========
+Glossary
+========
+
+.. note::
+
+   This goal of section is to standardize the terms used within the V4L2
+   documentation. It is written incrementally as they are standardized in
+   the V4L2 documentation. So, it is a Work In Progress.
+
+.. Please keep the glossary entries in alphabetical order
+
+.. glossary::
+
+    Bridge driver
+	The same as V4L2 main driver.
+
+    Device Node
+	A character device node in the file system used to control and do
+	input/output data transfers from/to a Kernel driver.
+
+    Digital Signal Processor - DSP
+	A specialized microprocessor, with its architecture optimized for
+	the operational needs of digital signal processing.
+
+    Driver
+	The part of the Linux Kernel that implements support
+	for a hardware component.
+
+    Field-programmable Gate Array - FPGA
+	A field-programmable gate array (FPGA) is an integrated circuit
+	designed to be configured by a customer or a designer after
+	manufacturing.
+
+	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
+
+    Inter-Integrated Circuit - I²C
+	A  multi-master, multi-slave, packet switched, single-ended,
+	serial computer bus used to control V4L2 sub-devices.
+
+	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
+
+    Integrated circuit - IC
+	A set of electronic circuits on one small flat piece of
+	semiconductor material, normally silicon.
+
+	Also known as chip.
+
+    IP block
+	The same as IP core.
+
+    Intelectual property core - IP 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 cores 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).
+
+    Image Signal Processor - ISP
+	A specialised processor that implements a set of algorithms for
+	processing image data. ISPs may implement algorithms for lens
+	shading correction, demosaic, 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 Controller
+	An API designed to expose and control devices and sub-devices
+	relationships to applications.
+
+	See :ref:`media_controller`.
+
+    MC-centric
+	V4L2 hardware that requires a Media controller.
+
+    Microprocessor
+	An 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.
+
+    SMBus
+	A subset of I²C, with defines a stricter usage of the bus.
+
+    Serial Peripheral Interface Bus - SPI
+	Synchronous serial communication interface specification used for
+	short distance communication, primarily in embedded systems.
+
+    System on a Chip - SoC
+	An integrated circuit that integrates all components of a computer
+	or other electronic systems.
+
+    Sub-device hardware components
+	Hardware components that aren't controlled by the
+	V4L2 main driver.
+
+    V4L2 main driver
+	The V4L2 device driver that implements the main logic to talk with
+	the V4L2 hardware.
+
+	Also known as bridge driver.
+
+    V4L2 sub-device
+	Part of the media hardware that it is implemented by a device
+	driver that is not part of the main V4L2 driver.
+
+	See :ref:`subdev`.
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index b89e5621ae69..74b397a8d033 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
     videodev
     capture-example
     v4l2grab-example
+    glossary
     biblio
 
 
-- 
2.17.1

[PATCH 2/3] media: open.rst: better document device node naming

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>

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.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/media/uapi/v4l/open.rst | 44 +++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index afd116edb40d..7e7aad784388 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,12 +7,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.
 
@@ -23,6 +25,42 @@ 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 existing V4L2 device node types 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
+======================== ======================================================
+
+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
+
+   3. **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) provide a
+      different API and aren't considered as V4L2 device nodes.
+
+      They are 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.17.1

[PATCH 3/3] media: open.rst: remove the minor number range

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>

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+samsung@kernel.org>
---
 Documentation/media/uapi/v4l/open.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index 7e7aad784388..18030131ef77 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -19,11 +19,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 existing V4L2 device node types are:
 
-- 
2.17.1

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

[Sakari Ailus]

Hi Mauro,

Thanks for the set! A few quick comments below, mainly additions and language.

On Tue, Sep 25, 2018 at 09:06:51AM -0300, Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> 
> Add a glossary of terms for V4L2, as several concepts are complex
> enough to cause misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  Documentation/media/uapi/v4l/glossary.rst | 108 ++++++++++++++++++++++
>  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
>  2 files changed, 109 insertions(+)
>  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> 
> diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> new file mode 100644
> index 000000000000..3dff6430d79f
> --- /dev/null
> +++ b/Documentation/media/uapi/v4l/glossary.rst
> @@ -0,0 +1,108 @@
> +========
> +Glossary
> +========
> +
> +.. note::
> +
> +   This goal of section is to standardize the terms used within the V4L2
> +   documentation. It is written incrementally as they are standardized in
> +   the V4L2 documentation. So, it is a Work In Progress.
> +
> +.. Please keep the glossary entries in alphabetical order
> +
> +.. glossary::
> +
> +    Bridge driver
> +	The same as V4L2 main driver.
> +
> +    Device Node
> +	A character device node in the file system used to control and do
> +	input/output data transfers from/to a Kernel driver.
> +
> +    Digital Signal Processor - DSP
> +	A specialized microprocessor, with its architecture optimized for
> +	the operational needs of digital signal processing.
> +
> +    Driver
> +	The part of the Linux Kernel that implements support
> +	for a hardware component.
> +
> +    Field-programmable Gate Array - FPGA
> +	A field-programmable gate array (FPGA) is an integrated circuit
> +	designed to be configured by a customer or a designer after
> +	manufacturing.
> +
> +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> +
> +    Inter-Integrated Circuit - I²C
> +	A  multi-master, multi-slave, packet switched, single-ended,
> +	serial computer bus used to control V4L2 sub-devices.
> +
> +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> +
> +    Integrated circuit - IC
> +	A set of electronic circuits on one small flat piece of
> +	semiconductor material, normally silicon.
> +
> +	Also known as chip.
> +
> +    IP block
> +	The same as IP core.
> +
> +    Intelectual property core - IP 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 cores may be licensed to another party or can be owned
> +	and used by a single party alone.

"Intellectual property" is not really the main point here, but I don't
object. You could use "hardware block" as well; I think that could be more
commonly used.

Either way, we should be fine with just one of "IP block" and "IP core".

> +
> +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> +
> +    Image Signal Processor - ISP
> +	A specialised processor that implements a set of algorithms for
> +	processing image data. ISPs may implement algorithms for lens
> +	shading correction, demosaic, 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 Controller
> +	An API designed to expose and control devices and sub-devices
> +	relationships to applications.
> +
> +	See :ref:`media_controller`.

Could you also add:

Media device

	A device node that implements the Media controller interface. Used
	to access the Media device complex besides the V4L2 and V4L2
	sub-device nodes.

Media hardware complex

	A collection of hardware components that together constitute an
	complex that can be seen as a single device. An example of this is
	a raw Bayer camera and an ISP that processes the images from the
	camera before writing them to system memory.

> +
> +    MC-centric
> +	V4L2 hardware that requires a Media controller.

How about:

Hardware the image data pipeline configuration of which requires the use of
Media controller and V4L2 sub-device interfaces.

> +
> +    Microprocessor
> +	An 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.
> +
> +    SMBus
> +	A subset of I²C, with defines a stricter usage of the bus.
> +
> +    Serial Peripheral Interface Bus - SPI
> +	Synchronous serial communication interface specification used for
> +	short distance communication, primarily in embedded systems.
> +
> +    System on a Chip - SoC
> +	An integrated circuit that integrates all components of a computer
> +	or other electronic systems.
> +
> +    Sub-device hardware components
> +	Hardware components that aren't controlled by the
> +	V4L2 main driver.
> +
> +    V4L2 main driver
> +	The V4L2 device driver that implements the main logic to talk with
> +	the V4L2 hardware.

How about:

V4L2 hardware -> hardware

There's no "V4L2 hardware" as such.

> +
> +	Also known as bridge driver.
> +
> +    V4L2 sub-device
> +	Part of the media hardware that it is implemented by a device
> +	driver that is not part of the main V4L2 driver.

I would agree with the definition if this were the kernel documentation.
Towards user space the API matters. How about:

Control interface for V4L2 sub-devices that are a part of the Media
device.

> +
> +	See :ref:`subdev`.
> diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> index b89e5621ae69..74b397a8d033 100644
> --- a/Documentation/media/uapi/v4l/v4l2.rst
> +++ b/Documentation/media/uapi/v4l/v4l2.rst
> @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
>      videodev
>      capture-example
>      v4l2grab-example
> +    glossary
>      biblio
>  
>  

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

Re: [PATCH 0/3] Add a glossary and fix some issues at open.rst docs

[Sakari Ailus]

On Tue, Sep 25, 2018 at 09:06:50AM -0300, Mauro Carvalho Chehab wrote:
> Those three patches were part of an attempt to add definitions for
> some terms used at the media subsystem:
> 
> 	https://lwn.net/Articles/732022/
> 
> On that time, the first patch generated heated discussions, on terms
> related to mc-centric/vdev-centric. The cern of the discussions were
> how to call the subdev API and the non-subdev API part of the 
> video4linux API.
> 
> I ended by being side-tracked by other things, and didn't have a chance
> to submit an updated version.
> 
> Well, now I'm doing things differently: at the glossary.rst, I removed
> everything related to hardware control. So, it should contain only the
> terms that there aren't any divergences. So, I hope we can manage to
> merge it this time.
> 
> After having this series merged, I'll address again the MC/vdev centric
> hardware control on a separate patchset, perhaps using a different
> approach together with the new glossary definitions related
> to it.
> 
> Mauro Carvalho Chehab (3):
>   media: add glossary.rst with common terms used at V4L2 spec
>   media: open.rst: better document device node naming
>   media: open.rst: remove the minor number range

For patches 2 and 3:

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

-- 
Sakari Ailus
e-mail: sakari.ailus@iki.fi

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

[Mauro Carvalho Chehab]

Em Tue, 25 Sep 2018 16:03:57 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> Thanks for the set! A few quick comments below, mainly additions and language.
> 
> On Tue, Sep 25, 2018 at 09:06:51AM -0300, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > 
> > Add a glossary of terms for V4L2, as several concepts are complex
> > enough to cause misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >  Documentation/media/uapi/v4l/glossary.rst | 108 ++++++++++++++++++++++
> >  Documentation/media/uapi/v4l/v4l2.rst     |   1 +
> >  2 files changed, 109 insertions(+)
> >  create mode 100644 Documentation/media/uapi/v4l/glossary.rst
> > 
> > diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
> > new file mode 100644
> > index 000000000000..3dff6430d79f
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > @@ -0,0 +1,108 @@
> > +========
> > +Glossary
> > +========
> > +
> > +.. note::
> > +
> > +   This goal of section is to standardize the terms used within the V4L2
> > +   documentation. It is written incrementally as they are standardized in
> > +   the V4L2 documentation. So, it is a Work In Progress.
> > +
> > +.. Please keep the glossary entries in alphabetical order
> > +
> > +.. glossary::
> > +
> > +    Bridge driver
> > +	The same as V4L2 main driver.
> > +
> > +    Device Node
> > +	A character device node in the file system used to control and do
> > +	input/output data transfers from/to a Kernel driver.
> > +
> > +    Digital Signal Processor - DSP
> > +	A specialized microprocessor, with its architecture optimized for
> > +	the operational needs of digital signal processing.
> > +
> > +    Driver
> > +	The part of the Linux Kernel that implements support
> > +	for a hardware component.
> > +
> > +    Field-programmable Gate Array - FPGA
> > +	A field-programmable gate array (FPGA) is an integrated circuit
> > +	designed to be configured by a customer or a designer after
> > +	manufacturing.
> > +
> > +	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> > +
> > +    Inter-Integrated Circuit - I²C
> > +	A  multi-master, multi-slave, packet switched, single-ended,
> > +	serial computer bus used to control V4L2 sub-devices.
> > +
> > +	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
> > +
> > +    Integrated circuit - IC
> > +	A set of electronic circuits on one small flat piece of
> > +	semiconductor material, normally silicon.
> > +
> > +	Also known as chip.
> > +
> > +    IP block
> > +	The same as IP core.
> > +
> > +    Intelectual property core - IP 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 cores may be licensed to another party or can be owned
> > +	and used by a single party alone.  
> 
> "Intellectual property" is not really the main point here, but I don't
> object. You could use "hardware block" as well; I think that could be more
> commonly used.
> 
> Either way, we should be fine with just one of "IP block" and "IP core".

Let's stick with IP block then. "IP is "Intelectual Property", so we
need to use it at the glossary.

> 
> > +
> > +	See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core).
> > +
> > +    Image Signal Processor - ISP
> > +	A specialised processor that implements a set of algorithms for
> > +	processing image data. ISPs may implement algorithms for lens
> > +	shading correction, demosaic, 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 Controller
> > +	An API designed to expose and control devices and sub-devices
> > +	relationships to applications.
> > +
> > +	See :ref:`media_controller`.  
> 
> Could you also add:
> 
> Media device
> 
> 	A device node that implements the Media controller interface. Used
> 	to access the Media device complex besides the V4L2 and V4L2
> 	sub-device nodes.
> 
> Media hardware complex
> 
> 	A collection of hardware components that together constitute an
> 	complex that can be seen as a single device. An example of this is
> 	a raw Bayer camera and an ISP that processes the images from the
> 	camera before writing them to system memory.

I prefer to keep those more polemic terms to a next patchset.

Yeah, I know that we ended by coming with that "complex" term,
but the more I heard it, the less I like using it on that context.

Anyway, I'm having some ideas that could prevent us the need
of using a complex[1] term like that, but for now, let's skip this
discussion, merging only the parts that won't cause discussions. 

[1] "complex" in the sense that it produces complex discussions.

> 
> > +
> > +    MC-centric
> > +	V4L2 hardware that requires a Media controller.  
> 
> How about:
> 
> Hardware the image data pipeline configuration of which requires the use of
> Media controller and V4L2 sub-device interfaces.

Sounds ok, but, if we add something like that, we need to define what 
is a "V4L2 sub-device interface".

Anyway, I should have been removed this one from here, as this
should belong to the next patch series, together with the addition
of such concept.

> > +
> > +    Microprocessor
> > +	An 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.
> > +
> > +    SMBus
> > +	A subset of I²C, with defines a stricter usage of the bus.
> > +
> > +    Serial Peripheral Interface Bus - SPI
> > +	Synchronous serial communication interface specification used for
> > +	short distance communication, primarily in embedded systems.
> > +
> > +    System on a Chip - SoC
> > +	An integrated circuit that integrates all components of a computer
> > +	or other electronic systems.
> > +
> > +    Sub-device hardware components
> > +	Hardware components that aren't controlled by the
> > +	V4L2 main driver.

Here, it should be, instead:

	V4L2 hardware components that aren't controlled by the
	V4L2 main driver.

(for a discussion about V4L2 hardware, see below).

> > +
> > +    V4L2 main driver
> > +	The V4L2 device driver that implements the main logic to talk with
> > +	the V4L2 hardware.  
> 
> How about:
> 
> V4L2 hardware -> hardware
> 
> There's no "V4L2 hardware" as such.

While this glossary is now being added to just the V4L2 side, if
done right, it could be a common glossary for the entire media API
set. So, let's be very precise to the parts of it that are V4L2
specific from others that would cover the entire media hardware.

Imagine a (fictional) peripheral device that it is an union of
all devices we have on media, e. g. a single device that would
have:

	- Camera sensors;
	- Video capture and output;
	- HDMI capture;
	- codecs;
	- m2m;
	- ISP;
	- CEC;
	- Audio inputs and outputs;
	- Radio;
	- Software Defined Radio;
	- Analog TV;
	- Digital TV;
	- Remote Controller.

We need a term to refer to the subset of such hardware that is supported
via the V4L2 API.

We ended by defining such hardware subset as "V4L2 hardware", in order
to distinguish it from the part of the media hardware that is not
supported by the V4L2 API, like Remote Controller, CEC, "Digital TV",
etc.

Just as a reminder, in the past I guess someone proposed to use
a term like "Video hardware". It has the problem of not covering 
radio or analog TV parts of the device.

> > +
> > +	Also known as bridge driver.
> > +
> > +    V4L2 sub-device
> > +	Part of the media hardware that it is implemented by a device
> > +	driver that is not part of the main V4L2 driver.  
> 
> I would agree with the definition if this were the kernel documentation.
> Towards user space the API matters. How about:
> 
> Control interface for V4L2 sub-devices that are a part of the Media
> device.

There's no definition for "Media device" at the glossary (and a
definition for it should include CEC, Remote Controller, Digital TV,
etc). With a definition like that, your proposal is wrong, as not
all other components of a media hardware is controlled by the V4L2
sub-device API.

Btw, I guess we can just remove this one, as we have already
a definition for "Sub-device hardware components" that sounds
clear enough.


> 
> > +
> > +	See :ref:`subdev`.
> > diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
> > index b89e5621ae69..74b397a8d033 100644
> > --- a/Documentation/media/uapi/v4l/v4l2.rst
> > +++ b/Documentation/media/uapi/v4l/v4l2.rst
> > @@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
> >      videodev
> >      capture-example
> >      v4l2grab-example
> > +    glossary
> >      biblio
> >  
> >    
> 

I'll send soon a version 2 of this patch.

Thanks,
Mauro

[PATCH v2] media: docs: add glossary.rst with common terms used at V4L2 spec

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Add a glossary of terms for V4L2, as several concepts are complex
enough to cause misunderstandings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---

v2.: Did some changes based on Sakari's feedback.

 Documentation/media/media_uapi.rst        |   2 +
 Documentation/media/uapi/v4l/glossary.rst | 118 ++++++++++++++++++++++
 Documentation/media/uapi/v4l/v4l2.rst     |   1 +
 3 files changed, 121 insertions(+)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
index 28eb35a1f965..aebe48b98ad3 100644
--- a/Documentation/media/media_uapi.rst
+++ b/Documentation/media/media_uapi.rst
@@ -2,6 +2,8 @@
 
 .. include:: <isonum.txt>
 
+.. _media_uapi:
+
 ########################################
 Linux Media Infrastructure userspace API
 ########################################
diff --git a/Documentation/media/uapi/v4l/glossary.rst b/Documentation/media/uapi/v4l/glossary.rst
new file mode 100644
index 000000000000..d91833255404
--- /dev/null
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -0,0 +1,118 @@
+========
+Glossary
+========
+
+.. note::
+
+   This goal of 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
+	The same as V4L2 main driver.
+
+    Device Node
+	A character device node in the file system used to control and do
+	input/output data transfers from/to a Kernel driver.
+
+    Digital Signal Processor - DSP
+	A specialized microprocessor, with its architecture optimized for
+	the operational needs of digital signal processing.
+
+    Driver
+	The part of the Linux Kernel that implements support
+	for a hardware component.
+
+    Field-programmable Gate Array - FPGA
+	A field-programmable gate array (FPGA) is an integrated circuit
+	designed to be configured by a customer or a designer after
+	manufacturing.
+
+	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
+
+    Inter-Integrated Circuit - I²C
+	A  multi-master, multi-slave, packet switched, single-ended,
+	serial computer bus used to control V4L2 sub-devices.
+
+	See http://www.nxp.com/docs/en/user-guide/UM10204.pdf.
+
+    Integrated circuit - IC
+	A set of electronic circuits on one small flat piece of
+	semiconductor material, normally silicon.
+
+	Also known as chip.
+
+    Intelectual property core - IP block
+	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 cores 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).
+
+    Image Signal Processor - ISP
+	A specialised processor that implements a set of algorithms for
+	processing image data. ISPs may implement algorithms for lens
+	shading correction, demosaic, 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 Controller
+	An API designed to expose and control devices and sub-devices'
+	relationships to applications.
+
+	See :ref:`media_controller`.
+
+    Media Hardware
+        The parts of a hardware that are supported by the Linux
+	media API (see :ref:`media_uapi`).
+
+	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
+	An 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.
+
+    SMBus
+	A subset of I²C, with defines a stricter usage of the bus.
+
+    Serial Peripheral Interface Bus - SPI
+	Synchronous serial communication interface specification used for
+	short distance communication, primarily in embedded systems.
+
+    System on a Chip - SoC
+	An integrated circuit that integrates all components of a computer
+	or other electronic systems.
+
+    Sub-device hardware components
+	V4L2 hardware components that aren't controlled by the
+	V4L2 main driver.
+
+    V4L2 userspace API - V4L2 API
+       The userspace API defined at :ref:`v4l2spec`, with is used
+       to control a V4L2 hardware.
+
+    V4L2 hardware
+       Part of the media hardware with is supported by the V4L2
+       userspace API.
+
+    V4L2 main driver
+	The V4L2 device driver that implements the main logic to talk with
+	a V4L2 hardware.
+
+	Also known as bridge driver.
+
+    V4L2 sub-device
+	Part of the media hardware that it is implemented by a device
+	driver that is not part of the main V4L2 driver.
+
+	See :ref:`subdev`.
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
index b89e5621ae69..74b397a8d033 100644
--- a/Documentation/media/uapi/v4l/v4l2.rst
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -32,6 +32,7 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification.
     videodev
     capture-example
     v4l2grab-example
+    glossary
     biblio
 
 
-- 
2.17.1