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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Fri, 8 May 2020 15:46:50 +0200
Hans Verkuil <hverkuil-cisco@xs4all.nl> escreveu:

> On 08/05/2020 15:10, Mauro Carvalho Chehab wrote:
> > Now that we have a chapter describing hardware control, let's
> > add the terms used there to the glossary.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  .../userspace-api/media/glossary.rst          | 42 ++++++++++++++++---
> >  1 file changed, 37 insertions(+), 5 deletions(-)
> > 
> > diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst
> > index 18a1ace00159..8cdb7900e994 100644
> > --- a/Documentation/userspace-api/media/glossary.rst
> > +++ b/Documentation/userspace-api/media/glossary.rst
> > @@ -69,6 +69,20 @@ Glossary
> >  
> >  	See https://en.wikipedia.org/wiki/Field-programmable_gate_array.
> >  
> > +    Hardware Component
> > +	A subset of the :term:`media hardware`. For example an :term:`I²C` or
> > +	:term:`SPI` device, or an :term:`IP block` inside a  
> 
> inside a -> inside an
> 
> > +	:term:`SoC` or :term:`FPGA`.
> > +
> > +    Hardware Peripheral
> > +	A group of :term:`hardware components <hardware component>` that
> > +	together make a larger user-facing functional peripheral. For
> > +	instance the :term:`SoC` :term:`ISP` :term:`IP	block <ip block>`  
> 
> Are there some commas missing here after 'SoC' and 'ISP'?

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

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

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

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

> 
> > +	and external camera sensors together make a camera hardware
> > +	peripheral.
> > +
> > +	Also known as :term:`peripheral`.
> > +
> >      I²C
> >  	**Inter-Integrated Circuit**
> >  
> > @@ -126,6 +140,14 @@ Glossary
> >  
> >  	See :ref:`media_controller`.
> >  
> > +    MC-Centric
> > +	:term:`V4L2 hardware` that requires a :term:`MC API`.  
> 
> a -> the
> 
> > +
> > +	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset  
> 
> They have that capability set, not unset.

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

> 
> > +	(see :ref:`VIDIOC_QUERYCAP`).
> > +
> > +	See :ref:`v4l2_hardware_control` for more details.
> > +
> >      Media Hardware
> >  	Subset of the hardware that is supported by the Linux Media API.
> >  
> > @@ -139,6 +161,9 @@ Glossary
> >  	control and input/output (I/O) operations specified by the
> >  	instructions on a single integrated circuit.
> >  
> > +    Peripheral
> > +	The same as :term:`hardware peripheral`.
> > +
> >      RC API
> >  	**Remote Controller API**
> >  
> > @@ -168,15 +193,22 @@ Glossary
> >  	The userspace API defined in :ref:`v4l2spec`, which is used to
> >  	control a V4L2 hardware.
> >  
> > +    V4L2 Device Node
> > +	A :term:`device node` that is associated to a V4L driver.
> > +
> > +	The V4L2 device node naming is specified at :ref:`v4l2_device_naming`.
> > +
> >      V4L2 Hardware
> >  	Part of a media hardware with is supported by the :term:`V4L2 API`.
> >  
> >      V4L2 Sub-device
> >  	V4L2 hardware components that aren't controlled by a
> > -	:term:`bridge driver`.
> > +	:term:`bridge driver`. See :ref:`subdev`.
> >  
> > -    V4L2 Sub-device API
> > -	Part of the :term:`V4L2 API` which control
> > -	:term:`V4L2 sub-devices <V4L2 Sub-device>`.
> > +    Video-node-Centric  
> 
> Either Video-Node-Centric or Video-node-centric, but not Video-node-Centric,
> that's inconsistent use of capitals.

Ok.

> 
> > +	V4L2 hardware that doesn't require a media controller to be used.  
> 
> a media controller to be used -> the MC API.
> 
> >  
> > -	See :ref:`subdev`.
> > +	Such hardware have ``V4L2_CAP_IO_MC`` device_caps field unset
> > +	(see :ref:`VIDIOC_QUERYCAP`).
> > +
> > +	See :ref:`v4l2_hardware_control` for more details.
> >   
> 
> Regards,
> 
> 	Hans



Thanks,
Mauro