| Message ID | f3435f2eb6417a4b16e036a492fc5044915892d1.1506550930.git.mchehab@s-opensource.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On 09/27/17 15:23, Mauro Carvalho Chehab wrote: > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> > --- > Documentation/media/uapi/v4l/open.rst | 40 +++++++++++++++++++++++++++++++++++ > 1 file changed, 40 insertions(+) > > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst > index 18030131ef77..f603bc9b49a0 100644 > --- a/Documentation/media/uapi/v4l/open.rst > +++ b/Documentation/media/uapi/v4l/open.rst > @@ -7,6 +7,46 @@ Opening and Closing Devices > *************************** > > > +.. _v4l2_hardware_control: > + > + > +Types of V4L2 media hardware control > +==================================== > + > +V4L2 hardware periferal is usually complex: support for it is peripheral (in several places...) > +implemented via a V4L2 main driver and often by several additional drivers. > +The main driver always exposes one or more **V4L2 device nodes** > +(see :ref:`v4l2_device_naming`) with are responsible for implementing > +data streaming, if applicable. > + > +The other drivers are called **V4L2 sub-devices** and provide control to > +other hardware components usually connected via a serial bus (like > +I²C, SMBus or 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, there was only one type of > +media hardware control: via the **V4L2 device nodes**. We refer to this kind > +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**"). > + > +Later (kernel 2.6.39), a new type of periferal control was > +added in order to support complex media hardware that are common for embedded > +systems. This type of periferal is controlled mainly via the media > +controller and V4L2 sub-devices. So, it is called > +**Media controller centric** (or, simply, "**MC-centric**") control. > + > +For **vdevnode-centric** media hardware control, the media hardware is > +controlled via the **V4L2 device nodes**. They may optionally support the > +:ref:`media controller API <media_controller>` as well, > +in order to inform the application which device nodes are available > +(see :ref:`related`). > + > +For **MC-centric** media hardware control it is required to configure > +the pipelines via the :ref:`media controller API <media_controller>` before > +the periferal can be used. For such devices, the sub-devices' configuration > +can be controlled via the :ref:`sub-device API <subdev>`, which creates one > +device node per sub-device. > + > .. _v4l2_device_naming: > > V4L2 Device Node Naming >
Hi Randy, Em Wed, 27 Sep 2017 15:32:12 -0700 Randy Dunlap <rdunlap@infradead.org> escreveu: > > +Types of V4L2 media hardware control > > +==================================== > > + > > +V4L2 hardware periferal is usually complex: support for it is > > peripheral (in several places...) Thanks for noticing! My brain is hardwired to automatically replace ph -> f, as "ph" only exists on archaic Brazilian Portuguese ;-) Just fixed everything with: $ git filter-branch -f --tree-filter 'for i in $(git grep -l periferal Documentation/media); do sed s,periferal,peripheral,g -i $i; done' v4.14-rc1.. And pushed to my development's tree: https://git.linuxtv.org/mchehab/experimental.git/log/?h=mc-centric-flag-v7 Thanks, Mauro
Hi Mauro, On Wed, Sep 27, 2017 at 07:23:46PM -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 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@s-opensource.com> > --- > Documentation/media/uapi/v4l/open.rst | 40 +++++++++++++++++++++++++++++++++++ > 1 file changed, 40 insertions(+) > > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst > index 18030131ef77..f603bc9b49a0 100644 > --- a/Documentation/media/uapi/v4l/open.rst > +++ b/Documentation/media/uapi/v4l/open.rst > @@ -7,6 +7,46 @@ Opening and Closing Devices > *************************** > > > +.. _v4l2_hardware_control: > + > + > +Types of V4L2 media hardware control > +==================================== > + > +V4L2 hardware periferal is usually complex: support for it is > +implemented via a V4L2 main driver and often by several additional drivers. > +The main driver always exposes one or more **V4L2 device nodes** > +(see :ref:`v4l2_device_naming`) with are responsible for implementing > +data streaming, if applicable. > + > +The other drivers are called **V4L2 sub-devices** and provide control to s/drivers/devices/ > +other hardware components usually connected via a serial bus (like > +I²C, SMBus or 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, there was only one type of > +media hardware control: via the **V4L2 device nodes**. We refer to this kind > +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**"). I think this could be easier understood if we start with the differences instead of what we call the types. I'd also refer to interfaces rather than their instances. How about (pending finalising discussion on naming): When **V4L2** was originally designed, the **V4L2 device** 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, 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 **Media controller** interface was added to V4L2 in order to better support complex **V4L2 aggregate devices** where the **V4L2** interface alone could no longer meaningfully serve as both a control and a data interface. On such aggregate devices, **V4L2** interface remains a data interface whereas control takes place through the **Media controller** and **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** aggregate devices provide more versatile control of the hardware than **V4L2 device node centric** devices. On **MC-centric** aggregate devices the **V4L2 sub-device nodes** represent specific parts of the **V4L2 aggregate device**, to which they enable control. Also, the additional versatility of **MC-centric** aggregate devices comes with additional responsibilities, the main one of which is the requirements 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. > + > +Later (kernel 2.6.39), a new type of periferal control was > +added in order to support complex media hardware that are common for embedded > +systems. This type of periferal is controlled mainly via the media > +controller and V4L2 sub-devices. So, it is called > +**Media controller centric** (or, simply, "**MC-centric**") control. > + > +For **vdevnode-centric** media hardware control, the media hardware is > +controlled via the **V4L2 device nodes**. They may optionally support the > +:ref:`media controller API <media_controller>` as well, > +in order to inform the application which device nodes are available > +(see :ref:`related`). > + > +For **MC-centric** media hardware control it is required to configure > +the pipelines via the :ref:`media controller API <media_controller>` before > +the periferal can be used. For such devices, the sub-devices' configuration > +can be controlled via the :ref:`sub-device API <subdev>`, which creates one > +device node per sub-device. > + > .. _v4l2_device_naming: > > V4L2 Device Node Naming
Em Fri, 6 Oct 2017 15:24:27 +0300 Sakari Ailus <sakari.ailus@iki.fi> escreveu: > > +When V4L2 was originally designed, there was only one type of > > +media hardware control: via the **V4L2 device nodes**. We refer to this kind > > +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**"). > > I think this could be easier understood if we start with the differences > instead of what we call the types. I'd also refer to interfaces rather than > their instances. > > How about (pending finalising discussion on naming): > > When **V4L2** was originally designed, the **V4L2 device** 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, > 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 **Media controller** interface was added to V4L2 > in order to better support complex **V4L2 aggregate devices** where the > **V4L2** interface alone could no longer meaningfully serve as both a > control and a data interface. On such aggregate devices, **V4L2** interface > remains a data interface whereas control takes place through the **Media > controller** and **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** aggregate devices provide more versatile control of the > hardware than **V4L2 device node centric** devices. On **MC-centric** > aggregate devices the **V4L2 sub-device nodes** represent specific parts of > the **V4L2 aggregate device**, to which they enable control. > > Also, the additional versatility of **MC-centric** aggregate devices comes > with additional responsibilities, the main one of which is the requirements > 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. Works for me. Except that I didn't like the idea of "aggregate devices". So, I kept the previously agreed term "V4L2 hardware". Also, as everything comes with a price, I added it on this paragraph: **MC-centric** V4L2 hardware provide more versatile control of the hardware than **V4L2 device node centric** devices at the expense of requiring device-specific userspace settings. Finally, I'm now using :term:`foo` Sphinx directive on the patchset (I'll send a new version soon) at the first time a term appears inside a section[1]. [1] We might repeat that on every occurrence of a term, but: a) it sounded overkill to me; b) if we decide to change some term, there will be a lot more stuff to be fixed, specially for terms in plural, as a plural for :term:`device` would be :term:`devices <device>`. Once we set this patchset into a stone, it could make sense to run some script that would replace every other occurrence of the glossary terms within Documentation/media/uapi/v4l to link to the glossary reference - but let's postpone this to be applied on a separate patchset. Btw, it probably makes sense to make the glossary as a general media book glossary - but again, this is out of topic for this patchset. With this, the version I'm adding is: <snippet> 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, 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 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 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. Also, the additional versatility of **MC-centric** V4L2 hardware comes with additional responsibilities, the main one of which is the requirements 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. </snippet> Thanks, Mauro
diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst index 18030131ef77..f603bc9b49a0 100644 --- a/Documentation/media/uapi/v4l/open.rst +++ b/Documentation/media/uapi/v4l/open.rst @@ -7,6 +7,46 @@ Opening and Closing Devices *************************** +.. _v4l2_hardware_control: + + +Types of V4L2 media hardware control +==================================== + +V4L2 hardware periferal is usually complex: support for it is +implemented via a V4L2 main driver and often by several additional drivers. +The main driver always exposes one or more **V4L2 device nodes** +(see :ref:`v4l2_device_naming`) with are responsible for implementing +data streaming, if applicable. + +The other drivers are called **V4L2 sub-devices** and provide control to +other hardware components usually connected via a serial bus (like +I²C, SMBus or 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, there was only one type of +media hardware control: via the **V4L2 device nodes**. We refer to this kind +of control as **V4L2 device node centric** (or, simply, "**vdevnode-centric**"). + +Later (kernel 2.6.39), a new type of periferal control was +added in order to support complex media hardware that are common for embedded +systems. This type of periferal is controlled mainly via the media +controller and V4L2 sub-devices. So, it is called +**Media controller centric** (or, simply, "**MC-centric**") control. + +For **vdevnode-centric** media hardware control, the media hardware is +controlled via the **V4L2 device nodes**. They may optionally support the +:ref:`media controller API <media_controller>` as well, +in order to inform the application which device nodes are available +(see :ref:`related`). + +For **MC-centric** media hardware control it is required to configure +the pipelines via the :ref:`media controller API <media_controller>` before +the periferal can be used. For such devices, the sub-devices' configuration +can be controlled via the :ref:`sub-device API <subdev>`, which creates one +device node per sub-device. + .. _v4l2_device_naming: V4L2 Device Node Naming
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@s-opensource.com> --- Documentation/media/uapi/v4l/open.rst | 40 +++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+)