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

[PATCH v3] 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 used within the media userspace API
documentation, as several concepts are complex enough to cause
misunderstandings.

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

v3:
  - Add SPDX header and dual-license the glossary
  - Make glossary generic enough to be used for all media uAPI documentation;
  - Add a few new items to the glossary, to imply that it covers not only V4L2;
  - Move it to the uAPI document as a hole.

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

 Documentation/media/media_uapi.rst    |   3 +
 Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
 2 files changed, 165 insertions(+)
 create mode 100644 Documentation/media/uapi/glossary.rst

diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
index 28eb35a1f965..41f091a26003 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
 ########################################
@@ -31,3 +33,4 @@ License".
     uapi/cec/cec-api
     uapi/gen-errors
     uapi/fdl-appendix
+    uapi/glossary
diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
new file mode 100644
index 000000000000..9e2a2b29e8b2
--- /dev/null
+++ b/Documentation/media/uapi/glossary.rst
@@ -0,0 +1,162 @@
+.. 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/media/uapi/fdl-appendix.rst.
+
+========
+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
+	A device driver that implements the main logic to talk with
+	a media hardware.
+
+	For V4L2 hardware, this is also known as V4L2 main driver.
+
+    Consumer Electronics Control API
+	An API designed to receive and transmit data via a HDMI
+	CEC interface.
+
+	See :ref:`cec`.
+
+    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 TV API - DVB API
+	An API designed to control the media device components related to
+	digital TV, including frontends, demuxes, streaming, conditional
+	access, etc.
+
+	See :ref:`dvbapi`.
+
+    Digital Signal Processor - DSP
+	A specialized microprocessor, with its architecture optimized for
+	the operational needs of digital signal processing.
+
+    Driver
+	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 some hardware components
+	like sub-device hardware components.
+
+	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 API
+	A set of userspace APIs used to control a media hardware.
+
+	See :ref:`media_uapi`.
+
+    Media Controller
+	An API designed to expose and control devices and sub-devices'
+	relationships to applications.
+
+	See :ref:`media_controller`.
+
+    Media Hardware
+	Subset of a hardware that is supported by the Linux Media API.
+
+	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.
+
+
+	See :ref:`media_uapi`.
+
+
+    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.
+
+    Remote Controller API
+	An API designed to receive and transmit data from remote
+	controllers.
+
+	See :ref:`remote_controllers`.
+
+    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 a
+	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 a media hardware with is supported by the V4L2
+       userspace API.
+
+    V4L2 main driver
+	A V4L2 device driver that implements the main logic to talk with
+	a V4L2 hardware.
+
+    V4L2 sub-device
+	Part of a media hardware that it is implemented by a device
+	driver that is not part of the main V4L2 driver.
+
+	See :ref:`subdev`.
-- 
2.17.1

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

[Hans Verkuil]

On 09/25/2018 09:14 PM, Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> 
> Add a glossary of terms used within the media userspace API
> documentation, as several concepts are complex enough to cause
> misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> 
> v3:
>   - Add SPDX header and dual-license the glossary
>   - Make glossary generic enough to be used for all media uAPI documentation;
>   - Add a few new items to the glossary, to imply that it covers not only V4L2;
>   - Move it to the uAPI document as a hole.
> 
> v2: Did some changes based on Sakari's feedback.
> 
>  Documentation/media/media_uapi.rst    |   3 +
>  Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
>  2 files changed, 165 insertions(+)
>  create mode 100644 Documentation/media/uapi/glossary.rst
> 
> diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
> index 28eb35a1f965..41f091a26003 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
>  ########################################
> @@ -31,3 +33,4 @@ License".
>      uapi/cec/cec-api
>      uapi/gen-errors
>      uapi/fdl-appendix
> +    uapi/glossary
> diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
> new file mode 100644
> index 000000000000..9e2a2b29e8b2
> --- /dev/null
> +++ b/Documentation/media/uapi/glossary.rst
> @@ -0,0 +1,162 @@
> +.. 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/media/uapi/fdl-appendix.rst.
> +
> +========
> +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
> +	A device driver that implements the main logic to talk with
> +	a media hardware.

s/a //

> +
> +	For V4L2 hardware, this is also known as V4L2 main driver.

s/as/as the/

> +
> +    Consumer Electronics Control API
> +	An API designed to receive and transmit data via a HDMI
> +	CEC interface.
> +
> +	See :ref:`cec`.
> +
> +    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 TV API - DVB API
> +	An API designed to control the media device components related to
> +	digital TV, including frontends, demuxes, streaming, conditional
> +	access, etc.

To be added to this glossary in the future:

- Frontend
- Demux
- Conditional Access

> +
> +	See :ref:`dvbapi`.
> +
> +    Digital Signal Processor - DSP
> +	A specialized microprocessor, with its architecture optimized for
> +	the operational needs of digital signal processing.
> +
> +    Driver
> +	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 some hardware components
> +	like sub-device hardware components.
> +
> +	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

Intelectual -> Intellectual

> +	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

demosaicing

> +	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 a media hardware.
> +
> +	See :ref:`media_uapi`.
> +
> +    Media Controller
> +	An API designed to expose and control devices and sub-devices'
> +	relationships to applications.

I'd rephrase this:

	An API designed to expose and control the relationships between
	devices and sub-devices.

It's an API, so no need to add 'to applications', since that's already
implicit in the name 'API'.

> +
> +	See :ref:`media_controller`.
> +
> +    Media Hardware
> +	Subset of a hardware that is supported by the Linux Media API.

s/a/the/

> +
> +	Includes audio and video capture and playback hardware,

s/Includes/This includes/

> +	digital and analog TV, camera sensors, ISPs, remote controllers,
> +	codecs, HDMI Consumer Electronics Control, HDMI capture, etc.
> +
> +
> +	See :ref:`media_uapi`.
> +
> +
> +    Microprocessor
> +	An electronic circuitry that carries out the instructions

s/An electronic/Electronic/

> +	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.
> +
> +    Remote Controller API
> +	An API designed to receive and transmit data from remote
> +	controllers.
> +
> +	See :ref:`remote_controllers`.
> +
> +    SMBus
> +	A subset of I²C, with defines a stricter usage of the bus.

with -> which

> +
> +    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 a
> +	V4L2 main driver.
> +
> +    V4L2 userspace API - V4L2 API
> +       The userspace API defined at :ref:`v4l2spec`, with is used to control

with -> which

> +       a V4L2 hardware.
> +
> +    V4L2 hardware
> +       Part of a media hardware with is supported by the V4L2

with -> which

> +       userspace API.
> +
> +    V4L2 main driver
> +	A V4L2 device driver that implements the main logic to talk with
> +	a V4L2 hardware.

s/a//

> +
> +    V4L2 sub-device
> +	Part of a media hardware that it is implemented by a device

s/a/the/
s/it//

> +	driver that is not part of the main V4L2 driver.
> +
> +	See :ref:`subdev`.
> 

Regards,

	Hans

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

[Mauro Carvalho Chehab]

Em Mon, 1 Oct 2018 17:20:26 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 09/25/2018 09:14 PM, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > 
> > Add a glossary of terms used within the media userspace API
> > documentation, as several concepts are complex enough to cause
> > misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > 
> > v3:
> >   - Add SPDX header and dual-license the glossary
> >   - Make glossary generic enough to be used for all media uAPI documentation;
> >   - Add a few new items to the glossary, to imply that it covers not only V4L2;
> >   - Move it to the uAPI document as a hole.
> > 
> > v2: Did some changes based on Sakari's feedback.
> > 
> >  Documentation/media/media_uapi.rst    |   3 +
> >  Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
> >  2 files changed, 165 insertions(+)
> >  create mode 100644 Documentation/media/uapi/glossary.rst
> > 
> > diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
> > index 28eb35a1f965..41f091a26003 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
> >  ########################################
> > @@ -31,3 +33,4 @@ License".
> >      uapi/cec/cec-api
> >      uapi/gen-errors
> >      uapi/fdl-appendix
> > +    uapi/glossary
> > diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
> > new file mode 100644
> > index 000000000000..9e2a2b29e8b2
> > --- /dev/null
> > +++ b/Documentation/media/uapi/glossary.rst
> > @@ -0,0 +1,162 @@
> > +.. 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/media/uapi/fdl-appendix.rst.
> > +
> > +========
> > +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
> > +	A device driver that implements the main logic to talk with
> > +	a media hardware.  
> 
> s/a //
> 
> > +
> > +	For V4L2 hardware, this is also known as V4L2 main driver.  
> 
> s/as/as the/
> 
> > +
> > +    Consumer Electronics Control API
> > +	An API designed to receive and transmit data via a HDMI
> > +	CEC interface.
> > +
> > +	See :ref:`cec`.
> > +
> > +    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 TV API - DVB API
> > +	An API designed to control the media device components related to
> > +	digital TV, including frontends, demuxes, streaming, conditional
> > +	access, etc.  
> 
> To be added to this glossary in the future:
> 
> - Frontend
> - Demux
> - Conditional Access

Yeah. The idea here is just to place a boilerplate for it.

We should in the future add more terms to the glossary. After
having the glossary added, it should be reviewed along the other
documents. Then, I'll add digital TV specific terms.

> 
> > +
> > +	See :ref:`dvbapi`.
> > +
> > +    Digital Signal Processor - DSP
> > +	A specialized microprocessor, with its architecture optimized for
> > +	the operational needs of digital signal processing.
> > +
> > +    Driver
> > +	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 some hardware components
> > +	like sub-device hardware components.
> > +
> > +	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  
> 
> Intelectual -> Intellectual
> 
> > +	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  
> 
> demosaicing
> 
> > +	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 a media hardware.
> > +
> > +	See :ref:`media_uapi`.
> > +
> > +    Media Controller
> > +	An API designed to expose and control devices and sub-devices'
> > +	relationships to applications.  
> 
> I'd rephrase this:
> 
> 	An API designed to expose and control the relationships between
> 	devices and sub-devices.
> 
> It's an API, so no need to add 'to applications', since that's already
> implicit in the name 'API'.
> 
> > +
> > +	See :ref:`media_controller`.
> > +
> > +    Media Hardware
> > +	Subset of a hardware that is supported by the Linux Media API.  
> 
> s/a/the/
> 
> > +
> > +	Includes audio and video capture and playback hardware,  
> 
> s/Includes/This includes/
> 
> > +	digital and analog TV, camera sensors, ISPs, remote controllers,
> > +	codecs, HDMI Consumer Electronics Control, HDMI capture, etc.
> > +
> > +
> > +	See :ref:`media_uapi`.
> > +
> > +
> > +    Microprocessor
> > +	An electronic circuitry that carries out the instructions  
> 
> s/An electronic/Electronic/
> 
> > +	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.
> > +
> > +    Remote Controller API
> > +	An API designed to receive and transmit data from remote
> > +	controllers.
> > +
> > +	See :ref:`remote_controllers`.
> > +
> > +    SMBus
> > +	A subset of I²C, with defines a stricter usage of the bus.  
> 
> with -> which
> 
> > +
> > +    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 a
> > +	V4L2 main driver.
> > +
> > +    V4L2 userspace API - V4L2 API
> > +       The userspace API defined at :ref:`v4l2spec`, with is used to control  
> 
> with -> which
> 
> > +       a V4L2 hardware.
> > +
> > +    V4L2 hardware
> > +       Part of a media hardware with is supported by the V4L2  
> 
> with -> which
> 
> > +       userspace API.
> > +
> > +    V4L2 main driver
> > +	A V4L2 device driver that implements the main logic to talk with
> > +	a V4L2 hardware.  
> 
> s/a//
> 
> > +
> > +    V4L2 sub-device
> > +	Part of a media hardware that it is implemented by a device  
> 
> s/a/the/
> s/it//
> 
> > +	driver that is not part of the main V4L2 driver.
> > +
> > +	See :ref:`subdev`.
> >   
> 
> Regards,
> 
> 	Hans


Except for the Digital TV new terms, all suggestions accepted.
I'm enclosing the diff against v3.

Thanks,
Mauro

-


diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
index 9e2a2b29e8b2..4307decd345f 100644
--- a/Documentation/media/uapi/glossary.rst
+++ b/Documentation/media/uapi/glossary.rst
@@ -29,9 +29,9 @@ Glossary
 
     Bridge driver
 	A device driver that implements the main logic to talk with
-	a media hardware.
+	media hardware.
 
-	For V4L2 hardware, this is also known as V4L2 main driver.
+	For V4L2 hardware, this is also known as the V4L2 main driver.
 
     Consumer Electronics Control API
 	An API designed to receive and transmit data via a HDMI
@@ -78,7 +78,7 @@ Glossary
 
 	Also known as chip.
 
-    Intelectual property core - IP block
+    Intellectual 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.
@@ -90,7 +90,7 @@ Glossary
     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
+	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).
 
@@ -100,15 +100,15 @@ Glossary
 	See :ref:`media_uapi`.
 
     Media Controller
-	An API designed to expose and control devices and sub-devices'
-	relationships to applications.
+	An API designed to expose and control the relationships between
+	devices and sub-devices.
 
 	See :ref:`media_controller`.
 
     Media Hardware
-	Subset of a hardware that is supported by the Linux Media API.
+	Subset of the hardware that is supported by the Linux Media API.
 
-	Includes audio and video capture and playback hardware,
+	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.
 
@@ -117,8 +117,8 @@ Glossary
 
 
     Microprocessor
-	An electronic circuitry that carries out the instructions
-	of a computer program by performing the basic arithmetic, logical,
+	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.
 
@@ -129,7 +129,7 @@ Glossary
 	See :ref:`remote_controllers`.
 
     SMBus
-	A subset of I²C, with defines a stricter usage of the bus.
+	A subset of I²C, whith defines a stricter usage of the bus.
 
     Serial Peripheral Interface Bus - SPI
 	Synchronous serial communication interface specification used for
@@ -144,19 +144,19 @@ Glossary
 	V4L2 main driver.
 
     V4L2 userspace API - V4L2 API
-       The userspace API defined at :ref:`v4l2spec`, with is used to control
-       a V4L2 hardware.
+	The userspace API defined at :ref:`v4l2spec`, whith is used to
+	control a V4L2 hardware.
 
     V4L2 hardware
-       Part of a media hardware with is supported by the V4L2
-       userspace API.
+	Part of a media hardware with is supported by the V4L2
+	userspace API.
 
     V4L2 main driver
 	A V4L2 device driver that implements the main logic to talk with
-	a V4L2 hardware.
+	V4L2 hardware.
 
     V4L2 sub-device
-	Part of a media hardware that it is implemented by a device
+	Part of the media hardware that is implemented by a device
 	driver that is not part of the main V4L2 driver.
 
 	See :ref:`subdev`.

[PATCH v4] 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 used within the media userspace API
documentation, as several concepts are complex enough to cause
misunderstandings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/media/media_uapi.rst    |   3 +
 Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
 2 files changed, 165 insertions(+)
 create mode 100644 Documentation/media/uapi/glossary.rst

diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
index 28eb35a1f965..41f091a26003 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
 ########################################
@@ -31,3 +33,4 @@ License".
     uapi/cec/cec-api
     uapi/gen-errors
     uapi/fdl-appendix
+    uapi/glossary
diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
new file mode 100644
index 000000000000..4307decd345f
--- /dev/null
+++ b/Documentation/media/uapi/glossary.rst
@@ -0,0 +1,162 @@
+.. 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/media/uapi/fdl-appendix.rst.
+
+========
+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
+	A device driver that implements the main logic to talk with
+	media hardware.
+
+	For V4L2 hardware, this is also known as the V4L2 main driver.
+
+    Consumer Electronics Control API
+	An API designed to receive and transmit data via a HDMI
+	CEC interface.
+
+	See :ref:`cec`.
+
+    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 TV API - DVB API
+	An API designed to control the media device components related to
+	digital TV, including frontends, demuxes, streaming, conditional
+	access, etc.
+
+	See :ref:`dvbapi`.
+
+    Digital Signal Processor - DSP
+	A specialized microprocessor, with its architecture optimized for
+	the operational needs of digital signal processing.
+
+    Driver
+	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 some hardware components
+	like sub-device hardware components.
+
+	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.
+
+    Intellectual 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, 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 a media hardware.
+
+	See :ref:`media_uapi`.
+
+    Media Controller
+	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.
+
+
+	See :ref:`media_uapi`.
+
+
+    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.
+
+    Remote Controller API
+	An API designed to receive and transmit data from remote
+	controllers.
+
+	See :ref:`remote_controllers`.
+
+    SMBus
+	A subset of I²C, whith 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 a
+	V4L2 main driver.
+
+    V4L2 userspace API - V4L2 API
+	The userspace API defined at :ref:`v4l2spec`, whith is used to
+	control a V4L2 hardware.
+
+    V4L2 hardware
+	Part of a media hardware with is supported by the V4L2
+	userspace API.
+
+    V4L2 main driver
+	A V4L2 device driver that implements the main logic to talk with
+	V4L2 hardware.
+
+    V4L2 sub-device
+	Part of the media hardware that is implemented by a device
+	driver that is not part of the main V4L2 driver.
+
+	See :ref:`subdev`.
-- 
2.17.1

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

[Hans Verkuil]

On 10/04/18 12:58, Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> 
> Add a glossary of terms used within the media userspace API
> documentation, as several concepts are complex enough to cause
> misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  Documentation/media/media_uapi.rst    |   3 +
>  Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
>  2 files changed, 165 insertions(+)
>  create mode 100644 Documentation/media/uapi/glossary.rst
> 
> diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
> index 28eb35a1f965..41f091a26003 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
>  ########################################
> @@ -31,3 +33,4 @@ License".
>      uapi/cec/cec-api
>      uapi/gen-errors
>      uapi/fdl-appendix
> +    uapi/glossary
> diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
> new file mode 100644
> index 000000000000..4307decd345f
> --- /dev/null
> +++ b/Documentation/media/uapi/glossary.rst
> @@ -0,0 +1,162 @@
> +.. 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/media/uapi/fdl-appendix.rst.
> +
> +========
> +Glossary
> +========
> +
> +.. note::
> +
> +   This goal of section is to standardize the terms used within the media

The goal of this section

(Huh, was wrong in v3 as well, I completely read over this at the time!)

> +   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 device driver that implements the main logic to talk with
> +	media hardware.
> +
> +	For V4L2 hardware, this is also known as the V4L2 main driver.
> +
> +    Consumer Electronics Control API
> +	An API designed to receive and transmit data via a HDMI

a HDMI -> an HDMI

(when you pronounce it 'HDMI' starts with a vowel, hence the 'an')

> +	CEC interface.
> +
> +	See :ref:`cec`.
> +
> +    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 TV API - DVB API
> +	An API designed to control the media device components related to
> +	digital TV, including frontends, demuxes, streaming, conditional
> +	access, etc.
> +
> +	See :ref:`dvbapi`.
> +
> +    Digital Signal Processor - DSP
> +	A specialized microprocessor, with its architecture optimized for
> +	the operational needs of digital signal processing.
> +
> +    Driver
> +	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 some hardware components
> +	like sub-device hardware components.
> +
> +	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.
> +
> +    Intellectual 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, 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 a media hardware.
> +
> +	See :ref:`media_uapi`.
> +
> +    Media Controller
> +	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.
> +

You can delete one empty line here.

> +
> +	See :ref:`media_uapi`.
> +
> +
> +    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.
> +
> +    Remote Controller API
> +	An API designed to receive and transmit data from remote
> +	controllers.
> +
> +	See :ref:`remote_controllers`.
> +
> +    SMBus
> +	A subset of I²C, whith defines a stricter usage of the bus.

whith -> which

> +
> +    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 a
> +	V4L2 main driver.
> +
> +    V4L2 userspace API - V4L2 API
> +	The userspace API defined at :ref:`v4l2spec`, whith is used to

whith -> which

> +	control a V4L2 hardware.
> +
> +    V4L2 hardware
> +	Part of a media hardware with is supported by the V4L2
> +	userspace API.
> +
> +    V4L2 main driver
> +	A V4L2 device driver that implements the main logic to talk with
> +	V4L2 hardware.
> +
> +    V4L2 sub-device
> +	Part of the media hardware that is implemented by a device
> +	driver that is not part of the main V4L2 driver.
> +
> +	See :ref:`subdev`.
> 

Regards,

	Hans

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

[Mauro Carvalho Chehab]

Em Thu, 4 Oct 2018 13:11:12 +0200
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 10/04/18 12:58, Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > 
> > Add a glossary of terms used within the media userspace API
> > documentation, as several concepts are complex enough to cause
> > misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> >  Documentation/media/media_uapi.rst    |   3 +
> >  Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
> >  2 files changed, 165 insertions(+)
> >  create mode 100644 Documentation/media/uapi/glossary.rst
> > 
> > diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst
> > index 28eb35a1f965..41f091a26003 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
> >  ########################################
> > @@ -31,3 +33,4 @@ License".
> >      uapi/cec/cec-api
> >      uapi/gen-errors
> >      uapi/fdl-appendix
> > +    uapi/glossary
> > diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
> > new file mode 100644
> > index 000000000000..4307decd345f
> > --- /dev/null
> > +++ b/Documentation/media/uapi/glossary.rst
> > @@ -0,0 +1,162 @@
> > +.. 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/media/uapi/fdl-appendix.rst.
> > +
> > +========
> > +Glossary
> > +========
> > +
> > +.. note::
> > +
> > +   This goal of section is to standardize the terms used within the media
> 
> The goal of this section
> 
> (Huh, was wrong in v3 as well, I completely read over this at the time!)
> 
> > +   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 device driver that implements the main logic to talk with
> > +	media hardware.
> > +
> > +	For V4L2 hardware, this is also known as the V4L2 main driver.
> > +
> > +    Consumer Electronics Control API
> > +	An API designed to receive and transmit data via a HDMI
> 
> a HDMI -> an HDMI
> 
> (when you pronounce it 'HDMI' starts with a vowel, hence the 'an')
> 
> > +	CEC interface.
> > +
> > +	See :ref:`cec`.
> > +
> > +    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 TV API - DVB API
> > +	An API designed to control the media device components related to
> > +	digital TV, including frontends, demuxes, streaming, conditional
> > +	access, etc.
> > +
> > +	See :ref:`dvbapi`.
> > +
> > +    Digital Signal Processor - DSP
> > +	A specialized microprocessor, with its architecture optimized for
> > +	the operational needs of digital signal processing.
> > +
> > +    Driver
> > +	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 some hardware components
> > +	like sub-device hardware components.
> > +
> > +	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.
> > +
> > +    Intellectual 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, 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 a media hardware.
> > +
> > +	See :ref:`media_uapi`.
> > +
> > +    Media Controller
> > +	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.
> > +
> 
> You can delete one empty line here.
> 
> > +
> > +	See :ref:`media_uapi`.
> > +
> > +
> > +    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.
> > +
> > +    Remote Controller API
> > +	An API designed to receive and transmit data from remote
> > +	controllers.
> > +
> > +	See :ref:`remote_controllers`.
> > +
> > +    SMBus
> > +	A subset of I²C, whith defines a stricter usage of the bus.
> 
> whith -> which
> 
> > +
> > +    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 a
> > +	V4L2 main driver.
> > +
> > +    V4L2 userspace API - V4L2 API
> > +	The userspace API defined at :ref:`v4l2spec`, whith is used to
> 
> whith -> which
> 
> > +	control a V4L2 hardware.
> > +
> > +    V4L2 hardware
> > +	Part of a media hardware with is supported by the V4L2
> > +	userspace API.
> > +
> > +    V4L2 main driver
> > +	A V4L2 device driver that implements the main logic to talk with
> > +	V4L2 hardware.
> > +
> > +    V4L2 sub-device
> > +	Part of the media hardware that is implemented by a device
> > +	driver that is not part of the main V4L2 driver.
> > +
> > +	See :ref:`subdev`.
> > 
> 
> Regards,
> 
> 	Hans

Thanks,
Mauro

I'm folding the fixes below.

diff --git a/Documentation/media/uapi/glossary.rst b/Documentation/media/uapi/glossary.rst
index 4307decd345f..10ce18d09607 100644
--- a/Documentation/media/uapi/glossary.rst
+++ b/Documentation/media/uapi/glossary.rst
@@ -17,7 +17,7 @@ Glossary
 
 .. note::
 
-   This goal of section is to standardize the terms used within the media
+   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.
 
@@ -34,7 +34,7 @@ Glossary
 	For V4L2 hardware, this is also known as the V4L2 main driver.
 
     Consumer Electronics Control API
-	An API designed to receive and transmit data via a HDMI
+	An API designed to receive and transmit data via an HDMI
 	CEC interface.
 
 	See :ref:`cec`.
@@ -115,7 +115,6 @@ Glossary
 
 	See :ref:`media_uapi`.
 
-
     Microprocessor
 	Electronic circuitry that carries out the instructions of a
 	computer program by performing the basic arithmetic, logical,
@@ -129,7 +128,7 @@ Glossary
 	See :ref:`remote_controllers`.
 
     SMBus
-	A subset of I²C, whith defines a stricter usage of the bus.
+	A subset of I²C, which defines a stricter usage of the bus.
 
     Serial Peripheral Interface Bus - SPI
 	Synchronous serial communication interface specification used for
@@ -144,7 +143,7 @@ Glossary
 	V4L2 main driver.
 
     V4L2 userspace API - V4L2 API
-	The userspace API defined at :ref:`v4l2spec`, whith is used to
+	The userspace API defined at :ref:`v4l2spec`, which is used to
 	control a V4L2 hardware.
 
     V4L2 hardware

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

[Laurent Pinchart]

Hi Mauro,

(CC'ing Kieran)

Thank you for the patch.

On Tuesday, 25 September 2018 22:14:51 EEST Mauro Carvalho Chehab wrote:
> From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> 
> Add a glossary of terms used within the media userspace API
> documentation, as several concepts are complex enough to cause
> misunderstandings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
> 
> v3:
>   - Add SPDX header and dual-license the glossary
>   - Make glossary generic enough to be used for all media uAPI
> documentation; - Add a few new items to the glossary, to imply that it
> covers not only V4L2; - Move it to the uAPI document as a hole.
> 
> v2: Did some changes based on Sakari's feedback.
> 
>  Documentation/media/media_uapi.rst    |   3 +
>  Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
>  2 files changed, 165 insertions(+)
>  create mode 100644 Documentation/media/uapi/glossary.rst
> 
> diff --git a/Documentation/media/media_uapi.rst
> b/Documentation/media/media_uapi.rst index 28eb35a1f965..41f091a26003
> 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
>  ########################################
> @@ -31,3 +33,4 @@ License".
>      uapi/cec/cec-api
>      uapi/gen-errors
>      uapi/fdl-appendix
> +    uapi/glossary

Is there an easy way to cross-reference to the glossary when terms are used ?

> diff --git a/Documentation/media/uapi/glossary.rst
> b/Documentation/media/uapi/glossary.rst new file mode 100644
> index 000000000000..9e2a2b29e8b2
> --- /dev/null
> +++ b/Documentation/media/uapi/glossary.rst
> @@ -0,0 +1,162 @@
> +.. 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/media/uapi/fdl-appendix.rst.
> +
> +========
> +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

Shouldn't all words start with a capital letter ?

> +	A device driver that implements the main logic to talk with
> +	a media hardware.

Terms that are part of the glossary should also be capitalized (and cross-
referenced within the glossary).

Hardware is still uncountable in English. I know we've discussed this 
previously, but if we want to write a glossary, it should be in English. Maybe 
we need to involve a native English speaker here. Kieran ? :-)

Additionally, I don't think the definition is correct. Bridges, as defined in 
V4L2, are opposed to subdevs, while "media hardware" in your definition 
includes everything. This needs to be clarified.

> +	For V4L2 hardware, this is also known as V4L2 main driver.

Do we use the term V4L2 main driver in the V4L2 spec ?

> +    Consumer Electronics Control API
> +	An API designed to receive and transmit data via a HDMI
> +	CEC interface.

So the definition of "Consumer Electronics Control" is CEC ? :-) It would be 
more useful to do it the other way around, define CEC as Consumer Electronics 
Control, and explain what it is.

> +	See :ref:`cec`.
> +
> +    Device Node
> +	A character device node in the file system used to control and do
> +	input/output data transfers from/to a Kernel driver.

Maybe "and transfer data in and out of a kernel driver" ?

> +
> +    Digital TV API - DVB API

Is DVB the same as Digital TV ? The digital video API (https://linuxtv.org/
downloads/v4l-dvb-apis-new/uapi/v4l/dv-timings.html) is sometimes referred to 
digital TV too. How about standardizing on DVB and avoiding digital TV 
completely in the specification ?

> +	An API designed to control the media device components related to
> +	digital TV, including frontends, demuxes, streaming, conditional
> +	access, etc.
> +
> +	See :ref:`dvbapi`.
> +
> +    Digital Signal Processor - DSP

Here and below I would put the abbreviation first. If someone looks up a term 
in the glossary because they don't know what it means, they're more likely to 
search for the abbreviation, not the full term.

> +	A specialized microprocessor, with its architecture optimized for
> +	the operational needs of digital signal processing.

Stupid question, do we need this entry in the glossary ? The term DSP doesn't 
seem to be used anywhere in the documentation, and in a video context, I 
expect the definition of ISP to be more relevant.

I also wonder whether we shouldn't drop terms that are defined by the industry 
(such as DSP, FPGA, I2C, IC, IP core, ISP, Microprocessor, SMBus and SPI), and 
only focus on terms that have a custom definition in the Linux media 
subsystem.

> +    Driver
> +	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 some hardware components
> +	like sub-device hardware components.
> +
> +	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 API
> +	A set of userspace APIs used to control a media hardware.

How about explcitly listing the APIs that the umbrella term "Media API" covers 
?

> +	See :ref:`media_uapi`.
> +
> +    Media Controller
> +	An API designed to expose and control devices and sub-devices'
> +	relationships to applications.

What do you mean by "relationships to applications" ?

> +	See :ref:`media_controller`.
> +
> +    Media Hardware
> +	Subset of a hardware that is supported by the Linux Media API.
> +
> +	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.
> +
> +
> +	See :ref:`media_uapi`.
> +
> +

Extra blank space ?

> +    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.
> +
> +    Remote Controller API
> +	An API designed to receive and transmit data from remote
> +	controllers.
> +
> +	See :ref:`remote_controllers`.
> +
> +    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 a
> +	V4L2 main driver.
> +
> +    V4L2 userspace API - V4L2 API
> +       The userspace API defined at :ref:`v4l2spec`, with is used to

s/at/in/

> control
> +       a V4L2 hardware.
> +
> +    V4L2 hardware
> +       Part of a media hardware with is supported by the V4L2
> +       userspace API.

That's kind of a circular definition, isn't it ?

> +    V4L2 main driver
> +	A V4L2 device driver that implements the main logic to talk with
> +	a V4L2 hardware.
> +
> +    V4L2 sub-device
> +	Part of a media hardware that it is implemented by a device

s/it is/is/

> +	driver that is not part of the main V4L2 driver.

I don't think that's correct a V4L2 subdev is a software object, not a piece 
of hardware.

> +	See :ref:`subdev`.

-- 
Regards,

Laurent Pinchart

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

[Mauro Carvalho Chehab]

Em Thu, 04 Oct 2018 14:41:30 +0300
Laurent Pinchart <laurent.pinchart@ideasonboard.com> escreveu:

> Hi Mauro,
> 
> (CC'ing Kieran)
> 
> Thank you for the patch.
> 
> On Tuesday, 25 September 2018 22:14:51 EEST Mauro Carvalho Chehab wrote:
> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > 
> > Add a glossary of terms used within the media userspace API
> > documentation, as several concepts are complex enough to cause
> > misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > ---
> > 
> > v3:
> >   - Add SPDX header and dual-license the glossary
> >   - Make glossary generic enough to be used for all media uAPI
> > documentation; - Add a few new items to the glossary, to imply that it
> > covers not only V4L2; - Move it to the uAPI document as a hole.
> > 
> > v2: Did some changes based on Sakari's feedback.
> > 
> >  Documentation/media/media_uapi.rst    |   3 +
> >  Documentation/media/uapi/glossary.rst | 162 ++++++++++++++++++++++++++
> >  2 files changed, 165 insertions(+)
> >  create mode 100644 Documentation/media/uapi/glossary.rst
> > 
> > diff --git a/Documentation/media/media_uapi.rst
> > b/Documentation/media/media_uapi.rst index 28eb35a1f965..41f091a26003
> > 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
> >  ########################################
> > @@ -31,3 +33,4 @@ License".
> >      uapi/cec/cec-api
> >      uapi/gen-errors
> >      uapi/fdl-appendix
> > +    uapi/glossary  
> 
> Is there an easy way to cross-reference to the glossary when terms are used ?

According with Sphinx documentation, there is:
	:term:`some glossary term`

But, on the tests I did here, it didn't really work with Sphinx 1.4.

It is actually on my TODO list to seek for a good way to address it
(and to find/replace occurrences of the terms at the documentation
to add cross-refs).

> 
> > diff --git a/Documentation/media/uapi/glossary.rst
> > b/Documentation/media/uapi/glossary.rst new file mode 100644
> > index 000000000000..9e2a2b29e8b2
> > --- /dev/null
> > +++ b/Documentation/media/uapi/glossary.rst
> > @@ -0,0 +1,162 @@
> > +.. 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/media/uapi/fdl-appendix.rst.
> > +
> > +========
> > +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  
> 
> Shouldn't all words start with a capital letter ?

I guess it is a matter of preference.

Right now, I'm capitalizing stuff only when they have acronyms
(like Digital Signal Processor - DSP), but I'm ok of doing it
to the other terms as well.

> 
> > +	A device driver that implements the main logic to talk with
> > +	a media hardware.  
> 
> Terms that are part of the glossary should also be capitalized (and cross-
> referenced within the glossary).

For now, it doesn't matter much. When we add cross references, it will use
either :ref: or :term:, so the actual text will be inserted by
Sphinx.

> 
> Hardware is still uncountable in English. I know we've discussed this 
> previously, but if we want to write a glossary, it should be in English. Maybe 
> we need to involve a native English speaker here. Kieran ? :-)

I'll replace:

	a media hardware -> media hardware

> 
> Additionally, I don't think the definition is correct. Bridges, as defined in 
> V4L2, are opposed to subdevs, while "media hardware" in your definition 
> includes everything. This needs to be clarified.

Please notice that the goal of this glossary is to be generic, and not
specific to V4L2. Extra care should be taken if we want to talk about
"subdevs" here, as such concept doesn't exist on DVB, CEC or RC (but
"main driver" does).

Also, I don't think that a subdev driver would fit into
"implements the main logic to talk with media hardware."

Anyway, if you have a better definition, feel free to suggest.


> 
> > +	For V4L2 hardware, this is also known as V4L2 main driver.  
> 
> Do we use the term V4L2 main driver in the V4L2 spec ?

Right now, I don't think we use, but this is something that we'll
need to, in order to define hardware controls.

Anyway, I'll remove the reference for a V4L2 hardware from this patch,
moving to the one that talks about vdev-centric/mc-centric.

> 
> > +    Consumer Electronics Control API
> > +	An API designed to receive and transmit data via a HDMI
> > +	CEC interface.  
> 
> So the definition of "Consumer Electronics Control" is CEC ? :-) It would be 
> more useful to do it the other way around, define CEC as Consumer Electronics 
> Control, and explain what it is.

Just like I answered to Hans with regards to Digital TV API, this is just
a boilerplate for CEC-related stuff.

The terms used by CEC should be added on a future patch.

> 
> > +	See :ref:`cec`.
> > +
> > +    Device Node
> > +	A character device node in the file system used to control and do
> > +	input/output data transfers from/to a Kernel driver.  
> 
> Maybe "and transfer data in and out of a kernel driver" ?

Works for me.

> 
> > +
> > +    Digital TV API - DVB API  
> 
> Is DVB the same as Digital TV ? The digital video API (https://linuxtv.org/
> downloads/v4l-dvb-apis-new/uapi/v4l/dv-timings.html) is sometimes referred to 
> digital TV too. How about standardizing on DVB and avoiding digital TV 
> completely in the specification ?

Actually, we did the reverse. This was known as DVB API, but, as DVB
is a specific TV standard, used mainly in Europe, and the API was
extended to work also with non-European standards, we replaced

	DVB -> Digital TV (or DTV) 

at the docs at the places it wouldn't be breaking userspace or
when it refers to the European standard.

> 
> > +	An API designed to control the media device components related to
> > +	digital TV, including frontends, demuxes, streaming, conditional
> > +	access, etc.
> > +
> > +	See :ref:`dvbapi`.
> > +
> > +    Digital Signal Processor - DSP  
> 
> Here and below I would put the abbreviation first. If someone looks up a term 
> in the glossary because they don't know what it means, they're more likely to 
> search for the abbreviation, not the full term.

Makes sense.

> 
> > +	A specialized microprocessor, with its architecture optimized for
> > +	the operational needs of digital signal processing.  
> 
> Stupid question, do we need this entry in the glossary ? The term DSP doesn't 
> seem to be used anywhere in the documentation, and in a video context, I 
> expect the definition of ISP to be more relevant.

It is used inside the glossary to define other terms. Also, we may
need to use it when talking about codecs.

> 
> I also wonder whether we shouldn't drop terms that are defined by the industry 
> (such as DSP, FPGA, I2C, IC, IP core, ISP, Microprocessor, SMBus and SPI), and 
> only focus on terms that have a custom definition in the Linux media 
> subsystem.

I don't think it hurts to have definitions for them. IMO, if we use a term,
we need to define it, in order to let clear about what we're talking about.
That also helps new Kernel developers to start understanding our documentation.

IMHO, it is complex enough to justify such glossary.

> 
> > +    Driver
> > +	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 some hardware components
> > +	like sub-device hardware components.
> > +
> > +	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 API
> > +	A set of userspace APIs used to control a media hardware.  
> 
> How about explcitly listing the APIs that the umbrella term "Media API" covers 
> ?

Makes sense. I'll add.

> 
> > +	See :ref:`media_uapi`.
> > +
> > +    Media Controller
> > +	An API designed to expose and control devices and sub-devices'
> > +	relationships to applications.  
> 
> What do you mean by "relationships to applications" ?

This was proposed by Sakari. Hans proposed a new definition for it:

    Media Controller
        An API designed to expose and control the relationships between
        devices and sub-devices.

        See :ref:`media_controller`.

> 
> > +	See :ref:`media_controller`.
> > +
> > +    Media Hardware
> > +	Subset of a hardware that is supported by the Linux Media API.
> > +
> > +	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.
> > +
> > +
> > +	See :ref:`media_uapi`.
> > +
> > +  
> 
> Extra blank space ?

Yes, already removed.

> 
> > +    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.
> > +
> > +    Remote Controller API
> > +	An API designed to receive and transmit data from remote
> > +	controllers.
> > +
> > +	See :ref:`remote_controllers`.
> > +
> > +    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 a
> > +	V4L2 main driver.
> > +
> > +    V4L2 userspace API - V4L2 API
> > +       The userspace API defined at :ref:`v4l2spec`, with is used to  
> 
> s/at/in/

ok.

> 
> > control
> > +       a V4L2 hardware.
> > +
> > +    V4L2 hardware
> > +       Part of a media hardware with is supported by the V4L2
> > +       userspace API.  
> 
> That's kind of a circular definition, isn't it ?

I don't think so. The only thing that defines a "V4L2 hardware"
(or whatever other term it would be used to describe a hardware
subset that is used by V4L2) is really the API.

There are *lots* of cases where the same IC has support for
V4L2, RC, ALSA and DVB, all integrated. On several cases, the
hardware it just a microcontroller (or FPGA) with I/O pins and
the needed logic to control audio, video streaming and remote
controllers.

For example, an em28xx chip has internally a firmware that uses 
an 8051-based CPU, having pins that are used for RC, analog and
digital TV.

[1] http://standwell.cn/Uploadfiles/20151022154755309.pdf

> > +    V4L2 main driver
> > +	A V4L2 device driver that implements the main logic to talk with
> > +	a V4L2 hardware.
> > +
> > +    V4L2 sub-device
> > +	Part of a media hardware that it is implemented by a device  
> 
> s/it is/is/

Ok.

> 
> > +	driver that is not part of the main V4L2 driver.  
> 
> I don't think that's correct a V4L2 subdev is a software object, not a piece 
> of hardware.

It is a software object used to control part of the hardware.

Also, usually, it is a way easier to identify what part of
the hardware is controlled by a V4L2 subdev than what part
is controlled by a main driver.

Think for example on a sensor subdev - with controls 
something that it is physically distinct from an IP block
inside some SoC.

Do you have a better definition?


> 
> > +	See :ref:`subdev`.  
> 



Thanks,
Mauro

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

[Mauro Carvalho Chehab]

Em Thu, 4 Oct 2018 10:27:06 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:


> > > +	For V4L2 hardware, this is also known as V4L2 main driver.    
> > 
> > Do we use the term V4L2 main driver in the V4L2 spec ?  
> 
> Right now, I don't think we use, but this is something that we'll
> need to, in order to define hardware controls.
> 
> Anyway, I'll remove the reference for a V4L2 hardware from this patch,
> moving to the one that talks about vdev-centric/mc-centric.

In time: I'll remove the reference for *V4L2 main driver*, with is
what you asked for


Thanks,
Mauro