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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
