Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

On Thu, Oct 05, 2017 at 09:26:51AM -0300, Mauro Carvalho Chehab wrote:
> > > > > +
> > > > > + See :ref:`media_controller`.
> > > > > +
> > > > > +MC-centric
> > > > > + V4L2 hardware that requires a Media controller.
> > > > > +
> > > > > + See :ref:`v4l2_hardware_control`.
> > > > > +
> > > > > +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
> > > > 
> > > > We don't have "Bus" in I²C, I'd leave it out here, too.  
> > > 
> > > I2C is a serial bus (and it is implemented as a bus inside the Kernel).
> > > Take a look at Documentation/i2c/summary.  
> > 
> > I don't disagree with that, but at the same time this is not related to my
> > suggestion.
> > 
> > "Bus" is not part of the abbreviation SPI, therefore we should not suggest
> > that here.
> 
> Ah, so you proposal here is just to replace:
> 
>   Serial Peripheral Interface Bus - SPI
> 
> To
>   Serial Peripheral Interface - SPI
> 
> Right? If so, it sounds OK.

Yes, please. That's exactly what I had in mind.

...

> > > > > +V4L2 hardware
> > > > > + A hardware used to on a media device supported by the V4L2
> > > > > + subsystem.
> > > > > +
> > > > > +V4L2 hardware control
> > > > > + The type of hardware control that a device supports.
> > > > > +
> > > > > + See :ref:`v4l2_hardware_control`.
> > > > > +
> > > > > +V4L2 main driver
> > > > > + The V4L2 device driver that implements the main logic to talk 
> > > > > with
> > > > > + the V4L2 hardware.
> > > > > +
> > > > > + Also known as bridge driver.
> > > > 
> > > > Is UVC driver a bridge driver? How about instead:  
> > > 
> > > Yes, sure: UVC driver is a bridge driver/main driver. It is the UVC driver
> > > that sends/receives data from the USB bus and send to the sensors.
> > > It also sends data via URB to the USB host driver, with, in turn send it
> > > to send to CPU (usually via DMA - although some USB drivers actually 
> > > implement direct I/O for short messages).
> > >   
> > > > Bridge and ISP drivers typically are V4L2 main drivers.  
> > > 
> > > We don't have a concept of an "ISP driver". Adding it sounds very  
> > 
> > I think we do have that roughly as much as we do have bridge driver. We
> > definitely also support devices that are called ISPs, therefore we do have
> > ISP drivers.
> 
> We have drivers for things implemented via ISP. However, right now,
> there's no distinction at the driver if the functionality is implemented
> on software (ISP) or in hardware. 
> 
> > 
> > > confusing, as an ISP hardware may actually implement different
> > > functions - so it ends by being supported by multiple drivers.  
> > 
> > Typically ISPs are controlled by a single driver as the sub-blocks in an
> > ISP usually can only be found in that very ISP.
> 
> I'm almost sure that this is not true for Exynos drivers. There are
> m2m drivers and normal drivers for the same ISP (doing different things,
> like format conversion, scaling, etc).

I don't know the Exynos hardware. There are exceptions but they tend to be
increasingly rare as extra memory hops hurt performance and increase power
consumption in common use cases.

If there is a split to multiple devices, then usually the first device is
CSI-2 receiver plus DMA (bridge) and the second is the ISP (i.e. where the
processing happens).

-- 
Regards,

Sakari Ailus
e-mail: sakari.ai...@iki.fi
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

On Thu, Oct 05, 2017 at 03:39:29PM -0300, Mauro Carvalho Chehab wrote:
> Em Thu, 5 Oct 2017 11:21:07 +0300
> Sakari Ailus  escreveu:
> 
> > Hi Mauro,
> > 
> > My apologies for the late reply.
> > 
> > On Tue, Aug 29, 2017 at 10:07:50AM -0300, Mauro Carvalho Chehab wrote:
> > > Em Tue, 29 Aug 2017 10:47:48 +0300
> > > Sakari Ailus  escreveu:
> > >   
> > > > Hi Mauro,
> > > > 
> > > > Thanks for the update. A few comments below.
> > > > 
> > > > On Mon, Aug 28, 2017 at 09:53:55AM -0300, Mauro Carvalho Chehab wrote:  
> > > > > Add a glossary of terms for V4L2, as several concepts are complex
> > > > > enough to cause misunderstandings.
> > > > > 
> > > > > Signed-off-by: Mauro Carvalho Chehab 
> > > > > ---
> > > > >  Documentation/media/uapi/v4l/glossary.rst | 147 
> > > > > ++
> > > > >  Documentation/media/uapi/v4l/v4l2.rst |   1 +
> > > > >  2 files changed, 148 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 ..0b6ab5adec81
> > > > > --- /dev/null
> > > > > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > > > > @@ -0,0 +1,147 @@
> > > > > +
> > > > > +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.
> > > > 
> > > > I'd leave the WiP part out.  
> > > 
> > > IMO, it is important to mention it, as the glossary, right now, covers
> > > only what's used on the first two sections of the API book. There are
> > > a lot more to be covered.  
> > 
> > Works for me.
> > 
> > >   
> > > >   
> > > > > +
> > > > > +.. Please keep the glossary entries in alphabetical order
> > > > > +
> > > > > +.. glossary::
> > > > > +
> > > > > +Bridge driver
> > > > > + The same as V4L2 main driver.
> > > > 
> > > > I've understood bridges being essentially a bus receiver + DMA. Most 
> > > > ISPs
> > > > contain both but have more than that. How about:
> > > > 
> > > > A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge 
> > > > drivers
> > > > typically act as V4L2 main drivers.  
> > > 
> > > No, only on some drivers the bridge driver has DMA. A vast amount of
> > > drivers (USB ones) don't implement any DMA inside the driver, as it is
> > > up to the USB host driver to implement support for DMA.
> > > 
> > > There are even some USB host drivers that don't always use DMA for I/O 
> > > transfers, using direct I/O if the message is smaller than a threshold
> > > or not multiple of the bus word. This is pretty common on SoC USB host
> > > drivers.
> > > 
> > > In any case, for the effect of this spec, and for all discussions we
> > > ever had about it, bridge driver == V4L2 main driver. I don't
> > > see any reason why to distinguish between them.  
> > 
> > I think you should precisely define what a bridge driver means. Generally
> > ISP drivers aren't referred to as bridge drivers albeit they, too, function
> > as V4L2 main drivers.
> 
> Btw, this is already defined, currently, at v4l2-subdev.h:
> 
>  * Sub-devices are devices that are connected somehow to the main bridge
>  * device. These devices are usually audio/video muxers/encoders/decoders or
>  * sensors and webcam controllers.
>  *
>  * Usually these devices are controlled through an i2c bus, but other busses
>  * may also be used.
> 
> Please notice that there it says: "main bridge" :-)
> 
> Such definition was added since the beginning of the subdev concept, back in
> 2008 and was reviewed by several V4L core developers:

A lot has happened since 2008. :-)

Anyway, I'll review the latest set.

-- 
Sakari Ailus
e-mail: sakari.ai...@iki.fi
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Thu, 5 Oct 2017 11:21:07 +0300
Sakari Ailus  escreveu:

> Hi Mauro,
> 
> My apologies for the late reply.
> 
> On Tue, Aug 29, 2017 at 10:07:50AM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 29 Aug 2017 10:47:48 +0300
> > Sakari Ailus  escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > Thanks for the update. A few comments below.
> > > 
> > > On Mon, Aug 28, 2017 at 09:53:55AM -0300, Mauro Carvalho Chehab wrote:  
> > > > Add a glossary of terms for V4L2, as several concepts are complex
> > > > enough to cause misunderstandings.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab 
> > > > ---
> > > >  Documentation/media/uapi/v4l/glossary.rst | 147 
> > > > ++
> > > >  Documentation/media/uapi/v4l/v4l2.rst |   1 +
> > > >  2 files changed, 148 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 ..0b6ab5adec81
> > > > --- /dev/null
> > > > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > > > @@ -0,0 +1,147 @@
> > > > +
> > > > +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.
> > > 
> > > I'd leave the WiP part out.  
> > 
> > IMO, it is important to mention it, as the glossary, right now, covers
> > only what's used on the first two sections of the API book. There are
> > a lot more to be covered.  
> 
> Works for me.
> 
> >   
> > >   
> > > > +
> > > > +.. Please keep the glossary entries in alphabetical order
> > > > +
> > > > +.. glossary::
> > > > +
> > > > +Bridge driver
> > > > +   The same as V4L2 main driver.
> > > 
> > > I've understood bridges being essentially a bus receiver + DMA. Most ISPs
> > > contain both but have more than that. How about:
> > > 
> > > A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers
> > > typically act as V4L2 main drivers.  
> > 
> > No, only on some drivers the bridge driver has DMA. A vast amount of
> > drivers (USB ones) don't implement any DMA inside the driver, as it is
> > up to the USB host driver to implement support for DMA.
> > 
> > There are even some USB host drivers that don't always use DMA for I/O 
> > transfers, using direct I/O if the message is smaller than a threshold
> > or not multiple of the bus word. This is pretty common on SoC USB host
> > drivers.
> > 
> > In any case, for the effect of this spec, and for all discussions we
> > ever had about it, bridge driver == V4L2 main driver. I don't
> > see any reason why to distinguish between them.  
> 
> I think you should precisely define what a bridge driver means. Generally
> ISP drivers aren't referred to as bridge drivers albeit they, too, function
> as V4L2 main drivers.

Btw, this is already defined, currently, at v4l2-subdev.h:

 * Sub-devices are devices that are connected somehow to the main bridge
 * device. These devices are usually audio/video muxers/encoders/decoders or
 * sensors and webcam controllers.
 *
 * Usually these devices are controlled through an i2c bus, but other busses
 * may also be used.

Please notice that there it says: "main bridge" :-)

Such definition was added since the beginning of the subdev concept, back in
2008 and was reviewed by several V4L core developers:

commit 2a1fcdf08230522bd5024f91da24aaa6e8d81f59
Author: Hans Verkuil 
Date:   Sat Nov 29 21:36:58 2008 -0300

V4L/DVB (9820): v4l2: add v4l2_device and v4l2_subdev structs to the v4l2 
framework.

Start implementing a proper v4l2 framework as discussed during the
Linux Plumbers Conference 2008.

Introduces v4l2_device (for device instances) and v4l2_subdev (representing
sub-device instances).

Signed-off-by: Hans Verkuil 
Reviewed-by: Laurent Pinchart 
Reviewed-by: Guennadi Liakhovetski 
Reviewed-by: Andy Walls 
Reviewed-by: David Brownell 
Signed-off-by: Mauro Carvalho Chehab 


Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Thu, 5 Oct 2017 11:21:07 +0300
Sakari Ailus  escreveu:

> Hi Mauro,
> 
> My apologies for the late reply.
> 
> On Tue, Aug 29, 2017 at 10:07:50AM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 29 Aug 2017 10:47:48 +0300
> > Sakari Ailus  escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > Thanks for the update. A few comments below.
> > > 
> > > On Mon, Aug 28, 2017 at 09:53:55AM -0300, Mauro Carvalho Chehab wrote:  
> > > > Add a glossary of terms for V4L2, as several concepts are complex
> > > > enough to cause misunderstandings.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab 
> > > > ---
> > > >  Documentation/media/uapi/v4l/glossary.rst | 147 
> > > > ++
> > > >  Documentation/media/uapi/v4l/v4l2.rst |   1 +
> > > >  2 files changed, 148 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 ..0b6ab5adec81
> > > > --- /dev/null
> > > > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > > > @@ -0,0 +1,147 @@
> > > > +
> > > > +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.
> > > 
> > > I'd leave the WiP part out.  
> > 
> > IMO, it is important to mention it, as the glossary, right now, covers
> > only what's used on the first two sections of the API book. There are
> > a lot more to be covered.  
> 
> Works for me.
> 
> >   
> > >   
> > > > +
> > > > +.. Please keep the glossary entries in alphabetical order
> > > > +
> > > > +.. glossary::
> > > > +
> > > > +Bridge driver
> > > > +   The same as V4L2 main driver.
> > > 
> > > I've understood bridges being essentially a bus receiver + DMA. Most ISPs
> > > contain both but have more than that. How about:
> > > 
> > > A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers
> > > typically act as V4L2 main drivers.  
> > 
> > No, only on some drivers the bridge driver has DMA. A vast amount of
> > drivers (USB ones) don't implement any DMA inside the driver, as it is
> > up to the USB host driver to implement support for DMA.
> > 
> > There are even some USB host drivers that don't always use DMA for I/O 
> > transfers, using direct I/O if the message is smaller than a threshold
> > or not multiple of the bus word. This is pretty common on SoC USB host
> > drivers.
> > 
> > In any case, for the effect of this spec, and for all discussions we
> > ever had about it, bridge driver == V4L2 main driver. I don't
> > see any reason why to distinguish between them.  
> 
> I think you should precisely define what a bridge driver means. Generally
> ISP drivers aren't referred to as bridge drivers albeit they, too, function
> as V4L2 main drivers.

It would be more productive if you could reply to the v7 of this patch
series with your suggestion for such definition.

IMHO, a bridge driver is a driver for a piece of hardware that allows
sending/receiving I2C control messages to a media hardware component,
but I'm likely ok with any other definition you have in mind.

> 
> >   
> > >   
> > > > +
> > > > +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.
> > > > +
> > > > +Hardware component
> > > > +   A subset of the media hardware. For example an I²C or SPI 
> > > > device,
> > > > +   or an IP block inside an SoC or FPGA.
> > > > +
> > > > +Hardware peripheral
> > > > +   A group of hardware components that together make a larger
> > > > +   user-facing functional peripheral. For instance the SoC ISP IP
> > > > +   cores and external camera sensors together make a
> > > > +   camera hardware peripheral.
> > > > +
> > > > +   Also known as peripheral.
> > > 
> > > Aren't peripherals usually understood to be 

Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Sakari Ailus]

Hi Mauro,

My apologies for the late reply.

On Tue, Aug 29, 2017 at 10:07:50AM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 29 Aug 2017 10:47:48 +0300
> Sakari Ailus  escreveu:
> 
> > Hi Mauro,
> > 
> > Thanks for the update. A few comments below.
> > 
> > On Mon, Aug 28, 2017 at 09:53:55AM -0300, Mauro Carvalho Chehab wrote:
> > > Add a glossary of terms for V4L2, as several concepts are complex
> > > enough to cause misunderstandings.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab 
> > > ---
> > >  Documentation/media/uapi/v4l/glossary.rst | 147 
> > > ++
> > >  Documentation/media/uapi/v4l/v4l2.rst |   1 +
> > >  2 files changed, 148 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 ..0b6ab5adec81
> > > --- /dev/null
> > > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > > @@ -0,0 +1,147 @@
> > > +
> > > +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.  
> > 
> > I'd leave the WiP part out.
> 
> IMO, it is important to mention it, as the glossary, right now, covers
> only what's used on the first two sections of the API book. There are
> a lot more to be covered.

Works for me.

> 
> > 
> > > +
> > > +.. Please keep the glossary entries in alphabetical order
> > > +
> > > +.. glossary::
> > > +
> > > +Bridge driver
> > > + The same as V4L2 main driver.  
> > 
> > I've understood bridges being essentially a bus receiver + DMA. Most ISPs
> > contain both but have more than that. How about:
> > 
> > A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers
> > typically act as V4L2 main drivers.
> 
> No, only on some drivers the bridge driver has DMA. A vast amount of
> drivers (USB ones) don't implement any DMA inside the driver, as it is
> up to the USB host driver to implement support for DMA.
> 
> There are even some USB host drivers that don't always use DMA for I/O 
> transfers, using direct I/O if the message is smaller than a threshold
> or not multiple of the bus word. This is pretty common on SoC USB host
> drivers.
> 
> In any case, for the effect of this spec, and for all discussions we
> ever had about it, bridge driver == V4L2 main driver. I don't
> see any reason why to distinguish between them.

I think you should precisely define what a bridge driver means. Generally
ISP drivers aren't referred to as bridge drivers albeit they, too, function
as V4L2 main drivers.

> 
> > 
> > > +
> > > +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.
> > > +
> > > +Hardware component
> > > + A subset of the media hardware. For example an I²C or SPI device,
> > > + or an IP block inside an SoC or FPGA.
> > > +
> > > +Hardware peripheral
> > > + A group of hardware components that together make a larger
> > > + user-facing functional peripheral. For instance the SoC ISP IP
> > > + cores and external camera sensors together make a
> > > + camera hardware peripheral.
> > > +
> > > + Also known as peripheral.  
> > 
> > Aren't peripherals usually understood to be devices that you can plug into
> > a computer? Such as a printer, or a... floppy drive?
> 
> That is the common sense, although, technically, peripherals are any
> I/O component. It is "peripheral" in the sense that it is not part of
> the CPU's internal circuits. Instead, it is a data that should be sent
> in or out the CPU. 
> 
> On such concept, even an I/O hardware integrated inside a SoC is a
> peripheral.
> 
> Yet, Hans argued already against using it. I opened a separate
> thread for us to discuss about it.
> 
> > I certainly wouldn't call this a peripheral. How about "aggregate device"?
> > We haven't used that before, but I think it relatively well catches the
> > meaning without being excessively elaborate.
> 
> "aggregate device" means nothing to me ;-) I propose "media hardware" instead.

Re: [PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

Em Tue, 29 Aug 2017 10:47:48 +0300
Sakari Ailus  escreveu:

> Hi Mauro,
> 
> Thanks for the update. A few comments below.
> 
> On Mon, Aug 28, 2017 at 09:53:55AM -0300, Mauro Carvalho Chehab wrote:
> > Add a glossary of terms for V4L2, as several concepts are complex
> > enough to cause misunderstandings.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/media/uapi/v4l/glossary.rst | 147 
> > ++
> >  Documentation/media/uapi/v4l/v4l2.rst |   1 +
> >  2 files changed, 148 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 ..0b6ab5adec81
> > --- /dev/null
> > +++ b/Documentation/media/uapi/v4l/glossary.rst
> > @@ -0,0 +1,147 @@
> > +
> > +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.  
> 
> I'd leave the WiP part out.

IMO, it is important to mention it, as the glossary, right now, covers
only what's used on the first two sections of the API book. There are
a lot more to be covered.

> 
> > +
> > +.. Please keep the glossary entries in alphabetical order
> > +
> > +.. glossary::
> > +
> > +Bridge driver
> > +   The same as V4L2 main driver.  
> 
> I've understood bridges being essentially a bus receiver + DMA. Most ISPs
> contain both but have more than that. How about:
> 
> A driver for a bus (e.g. parallel, CSI-2) receiver and DMA. Bridge drivers
> typically act as V4L2 main drivers.

No, only on some drivers the bridge driver has DMA. A vast amount of
drivers (USB ones) don't implement any DMA inside the driver, as it is
up to the USB host driver to implement support for DMA.

There are even some USB host drivers that don't always use DMA for I/O 
transfers, using direct I/O if the message is smaller than a threshold
or not multiple of the bus word. This is pretty common on SoC USB host
drivers.

In any case, for the effect of this spec, and for all discussions we
ever had about it, bridge driver == V4L2 main driver. I don't
see any reason why to distinguish between them.

> 
> > +
> > +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.
> > +
> > +Hardware component
> > +   A subset of the media hardware. For example an I²C or SPI device,
> > +   or an IP block inside an SoC or FPGA.
> > +
> > +Hardware peripheral
> > +   A group of hardware components that together make a larger
> > +   user-facing functional peripheral. For instance the SoC ISP IP
> > +   cores and external camera sensors together make a
> > +   camera hardware peripheral.
> > +
> > +   Also known as peripheral.  
> 
> Aren't peripherals usually understood to be devices that you can plug into
> a computer? Such as a printer, or a... floppy drive?

That is the common sense, although, technically, peripherals are any
I/O component. It is "peripheral" in the sense that it is not part of
the CPU's internal circuits. Instead, it is a data that should be sent
in or out the CPU. 

On such concept, even an I/O hardware integrated inside a SoC is a
peripheral.

Yet, Hans argued already against using it. I opened a separate
thread for us to discuss about it.

> I certainly wouldn't call this a peripheral. How about "aggregate device"?
> We haven't used that before, but I think it relatively well catches the
> meaning without being excessively elaborate.

"aggregate device" means nothing to me ;-) I propose "media hardware" instead.

> 
> > +
> > +Hardware peripheral control
> > +   Type of control for a hardware peripheral supported by V4L2 drivers.
> > +
> > +   See :ref:`v4l2_hardware_control`.
> > +
> > +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

[PATCH v5 1/7] media: add glossary.rst with a glossary of terms used at V4L2 spec

[Mauro Carvalho Chehab]

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

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/media/uapi/v4l/glossary.rst | 147 ++
 Documentation/media/uapi/v4l/v4l2.rst |   1 +
 2 files changed, 148 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 ..0b6ab5adec81
--- /dev/null
+++ b/Documentation/media/uapi/v4l/glossary.rst
@@ -0,0 +1,147 @@
+
+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.
+
+Hardware component
+   A subset of the media hardware. For example an I²C or SPI device,
+   or an IP block inside an SoC or FPGA.
+
+Hardware peripheral
+   A group of hardware components that together make a larger
+   user-facing functional peripheral. For instance the SoC ISP IP
+   cores and external camera sensors together make a
+   camera hardware peripheral.
+
+   Also known as peripheral.
+
+Hardware peripheral control
+   Type of control for a hardware peripheral supported by V4L2 drivers.
+
+   See :ref:`v4l2_hardware_control`.
+
+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 processor - ISP
+   A specialized digital signal processor used for image processing
+   in digital cameras, mobile phones or other devices.
+
+Peripheral
+   The same as hardware peripheral.
+
+Media Controller
+   An API used to identify the hardware components and (optionally)
+   change the links between hardware components.
+
+   See :ref:`media_controller`.
+
+MC-centric
+   V4L2 hardware that requires a Media controller.
+
+   See :ref:`v4l2_hardware_control`.
+
+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 device node
+   A device node that is associated to a V4L2 main driver,
+   as specified in :ref:`v4l2_device_naming`.
+
+V4L2 hardware
+   A hardware used to on a media device supported by the V4L2
+   subsystem.
+
+V4L2 hardware control
+   The type of hardware control that a device supports.
+
+   See :ref:`v4l2_hardware_control`.
+
+V4L2 main driver
+   The