Re: [PATCH RFC] media: open.rst: document devnode-centric and mc-centric types

[Sakari Ailus]

Hi Mauro,

Thanks for the patch! Something like this was long due.

I cc'd Hans and Laurent to get their attention, too.

On Sat, Aug 19, 2017 at 07:04:40AM -0300, 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 never made it clear, at the V4L2 spec,
> about the differences between both types.
> 
> Let's document them with the current implementation.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>
> ---
> 
> This patch is a result of this week's discussion we had with regards to merging
> a patch series from Sakari documenting the need of propagating streaming
> control between sub-devices on some complex mc-centric devices.
> 
> One big gap on our documentation popped up: while we have distinct behavior
> for mc-centric and devnode-centric types of V4L2 devices, we never clearly
> documented about that.
> 
> This RFC patch is a first attempt to have a definition of those types, and to
> standardize the names we use to distinguish between those types.
> 
> Comments are welcome.
> 
> 
>  Documentation/media/uapi/v4l/open.rst | 37 +++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index afd116edb40d..9cf4f74c466a 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -6,6 +6,43 @@
>  Opening and Closing Devices
>  ***************************
>  
> +Types of V4L2 devices
> +=====================
> +
> +V4L2 devices are usually complex: they're implemented via a main driver and

Not all such as UVC webcams. How about:

s/implemented/often implemented/

> +several other drivers. The main driver always exposes a V4L2 device node
> +(see :ref:`v4l2_device_naming`). The other devices are called **sub-devices**.
> +They are usually controlled via a serial bus (I2C or SMBus).

The main driver also often exposes sub-devices.

The practice has been that the video nodes are registered by the driver
that generally orchestrates things for the complete device but I don't
think there's anything that would exclude doing this otherwise if there are
two struct devices involved that do DMA.

> +
> +When V4L2 started, there was only one type of device, fully controlled via
> +V4L2 device nodes. We call those devices as **devnode-centric devices**.

As device nodes can refer to any types of device nodes (such as sub-device
nodes), how about calling these "video node centric"? To make it more
explicit, I'd use "V4L2 video node centric" here. Perhaps "video node
centric" later to make it shorter.

> +Since the end of 2010, a new type of V4L2 device was added, in order to
> +support complex devices that are common on embedded systems. Those devices
> +are controlled mainly via the media controller. So, they're called:

s/://

> +**mc-centric devices**.

"Media controller (MC) centric devices" and "MC-centric devices" later?

> +
> +On a **devnode-centric device**, the device and their corresponding hardware
> +pipelines are controlled via the V4L2 device node. They may optionally
> +expose the hardware pipelines via the
> +:ref:`media controller API <media_controller>`.
> +
> +On a **mc-centric device**, before using the V4L2 device, it is required to
> +set the hardware pipelines via the
> +:ref:`media controller API <media_controller>`. On those devices, the
> +sub-devices' configuration can be controlled via the
> +:ref:`sub-device API <subdev>`, with creates one device node per sub device.
> +On such devices, the V4L2 device node is mainly responsible for controlling
> +the streaming features, while the media controller and the subdevices device
> +nodes are responsible for configuring the hardware.

What would you think of using wording that conveys the message that in this
case V4L2 video device nodes essentially are a data interface only whilst
V4L2 sub-device nodes and MC are control interfaces? This is the grounding
difference between the two in my opinion, and makes it easy to understand
for the reader.

> +
> +.. note::
> +
> +   Currently, it is forbidden for a **devnode-centric device** to expose
> +   subdevices via :ref:`sub-device API <subdev>`, although this might
> +   change in the future.

I'd leave out this note. One of the purposes of MC was to find device
nodes, and finding a subdev node related to, say, a video node is a pain
without MC. Less variance in interface availability is better for the user
space, and unlike between video node centric vs. MC-centric, there are
hardly technical reasons (or at least I can't remember one) for doing this.

I remember we had a few of these drivers and the agreement was to add MC
interface to those.

> +
> +
> +.. _v4l2_device_naming:
>  
>  Device Naming
>  =============

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@xxxxxx