Re: [PATCH v8 4/7] media: open.rst: document vdevnode-centric and mc-centric types

[Hans Verkuil]

More word-smithing...

On 10/10/2017 01:45 PM, Mauro Carvalho Chehab wrote:
> When we added support for omap3, back in 2010, we added a new
> type of V4L2 devices that aren't fully controlled via the V4L2
> device node.
> 
> Yet, we have never clearly documented in the V4L2 specification
> the differences between the two types.
> 
> Let's document them based on the the current implementation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
> ---
>  Documentation/media/uapi/v4l/open.rst | 55 +++++++++++++++++++++++++++++++++++
>  1 file changed, 55 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index 46ef63e05696..1a8a9e1d0e84 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,6 +7,61 @@ Opening and Closing Devices
>  ***************************
>  
>  
> +.. _v4l2_hardware_control:
> +
> +
> +Types of V4L2 media hardware control
> +====================================
> +
> +A :term:`V4L2 hardware` is usually complex: support for it is

No 'A '.

> +implemented via a :term:`V4L2 main driver` and often by several

I prefer 'by' instead of 'via'.

> +additional :term:`drivers <driver>`.
> +The main driver always exposes one or more
> +:term:`V4L2 device nodes <v4l2 device node>`
> +(see :ref:`v4l2_device_naming`) with are responsible for implementing

with -> which

> +data streaming, if applicable.
> +
> +The other drivers are called :term:`V4L2 sub-devices <v4l2 sub-device>`

I'd say "V4L2 sub-device drivers"

> +and provide control to other
> +:term:`hardware components <hardware component>` are usually connected

:term:`hardware components <hardware component>`. Those component are usually controlled

> +via a serial bus (like :term:`IÂC`, :term:`SMBus` or :term:`SPI`).
> +Depending on the main driver, they can be implicitly
> +controlled directly by the main driver or explicitly via
> +the V4L2 sub-device API (see :ref:`subdev`).
> +
> +When **V4L2** was originally designed, the
> +:term:`V4L2 device nodes <v4l2 device node>` served the purpose of both
> +control and data interfaces and there was no separation
> +between the two interface-wise. V4L2 controls, setting inputs and outputs,

Instead of 'interface-wise' I'd use 'API-wise'. That reminds me: should we add
'API' to the glossary as well? (Can be done later)

> +format configuration and buffer related operations were all performed
> +through the same **V4L2 device nodes**. Devices offering such interface are
> +called **V4L2 device node centric**.
> +
> +Later on, support for the :term:`media controller` interface was added
> +to V4L2 in order to better support complex :term:`V4L2 hardware` where the
> +**V4L2** interface alone could no longer meaningfully serve as both a
> +control and a data interface. On such V4L2 hardware, **V4L2** interface

**V4L2** -> the **V4L2**

> +remains a data interface whereas control takes place through the
> +:term:`media controller` and :term:`V4L2 sub-device` interfaces. Stream
> +control is an exception to this: streaming is enabled and disabled
> +through the **V4L2** interface. These devices are called
> +**Media controller centric**.
> +
> +**MC-centric** V4L2 hardware provide more versatile control of the

provide -> provides

> +hardware than **V4L2 device node centric** devices at the expense of
> +requiring device-specific userspace settings.
> +
> +On **MC-centric** V4L2 hardware, the **V4L2 sub-device nodes**
> +represent specific parts of the V4L2 hardware, to which they enable
> +control.

I'd rephrase this:

On **MC-centric** V4L2 hardware, the **V4L2 sub-device nodes**
provide control of the specific part of the V4L2 hardware represented
by each node.

> +
> +Also, the additional versatility of **MC-centric** V4L2 hardware comes
> +with additional responsibilities, the main one of which is the requirements

...of which the main one is the requirement...

> +of the user configuring the device pipeline before starting streaming. This
> +typically involves configuring the links using the **Media controller**
> +interface and the media bus formats on pads (at both ends of the links)
> +using the **V4L2 sub-device** interface.
> +
>  .. _v4l2_device_naming:
>  
>  V4L2 Device Node Naming
> 

Regards,

	Hans