Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1721598 > unrolled thread

[PATCH v5 0/7] document types of hardware control for V4L2

Back to article view | Back to linux.kernel

Contents

  [PATCH v5 0/7] document types of hardware control for V4L2 Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-08-28 15:00 +0200
    [PATCH v5 2/7] media: open.rst: better document device node naming Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-08-28 15:00 +0200
      Re: [PATCH v5 2/7] media: open.rst: better document device node  naming Sakari Ailus <sakari.ailus@iki.fi> - 2017-08-29 10:40 +0200
        Re: [PATCH v5 2/7] media: open.rst: better document device node  naming Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-08-29 11:10 +0200

#1721598 — [PATCH v5 0/7] document types of hardware control for V4L2

On Kernel 2.6.39, the omap3 driver was introduced together with a new way
to control complex V4L2 devices used on embedded systems, but this was
never documented, as the original idea were to have "soon" support for
standard apps to use it as well, via libv4l, but that didn't happen so far.

Also, it is not possible for an userspace applicatin to detect the kind of
control a device supports.

This series fill the gap, by documenting the new type of hardware
control and adding a way for userspace to detect if the device can be
used or not by an standard V4L2 application.

Notes:
====

1) For the sake of better review, this series start with the addition of a
glossary, as requested by Laurent. Please notice, however, that
the glossary there references some new captions that will only be added
by subsequent patches. So, when this series get applied, the glossary
patch should actually be merged after the patches that introduce those
new captions, in order to avoid warnings for non-existing references.

2) This series doesn't contain patches that actually use the new flag.
This will be added after such patch gets reviewed.

v5:
- Added more terms to the glossary
- Adjusted some wording as proposed by Hans on a few patches
  and added his ack on others

v4:

- Addressed Hans comments for v2;
- Fixed broken references at the glossary.rst

v3:

- Add a glossary to be used by the new documentation about hardware control;
- Add a patch removing minor number range
- Use glossary terms at open.rst
- Split the notice about subdev-API on vdev-centric, as this change
   will require further discussions.

v2:

- added a patch at the beginning of the series better defining the
  device node naming rules;
- better defined the differenes between device hardware and V4L2 device node
  as suggested by Laurent and with changes proposed by Hans and Sakari
- changed the caps flag to indicate MC-centric devices
- removed the final patch that would use the new caps flag. I'll write it
  once we agree on the new caps flag.


Mauro Carvalho Chehab (7):
  media: add glossary.rst with a glossary of terms used at V4L2 spec
  media: open.rst: better document device node naming
  media: open.rst: remove the minor number range
  media: open.rst: document devnode-centric and mc-centric types
  media: open.rst: Adjust some terms to match the glossary
  media: videodev2: add a flag for MC-centric devices
  media: open.rst: add a notice about subdev-API on vdev-centric

 Documentation/media/uapi/v4l/glossary.rst        | 147 +++++++++++++++++++++++
 Documentation/media/uapi/v4l/open.rst            | 114 +++++++++++++++---
 Documentation/media/uapi/v4l/v4l2.rst            |   1 +
 Documentation/media/uapi/v4l/vidioc-querycap.rst |   5 +
 Documentation/media/videodev2.h.rst.exceptions   |   1 +
 include/uapi/linux/videodev2.h                   |   2 +
 6 files changed, 256 insertions(+), 14 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/glossary.rst

-- 
2.13.5

[toc] | [next] | [standalone]

#1721599 — [PATCH v5 2/7] media: open.rst: better document device node naming

Right now, only kAPI documentation describes the device naming.
However, such description is needed at the uAPI too. Add it,
and describe how to get an unique identify for a given device.

Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 Documentation/media/uapi/v4l/open.rst | 39 ++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
index afd116edb40d..fc0037091814 100644
--- a/Documentation/media/uapi/v4l/open.rst
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -7,12 +7,14 @@ Opening and Closing Devices
 ***************************
 
 
-Device Naming
-=============
+.. _v4l2_device_naming:
+
+V4L2 Device Node Naming
+=======================
 
 V4L2 drivers are implemented as kernel modules, loaded manually by the
 system administrator or automatically when a device is first discovered.
-The driver modules plug into the "videodev" kernel module. It provides
+The driver modules plug into the ``videodev`` kernel module. It provides
 helper functions and a common application interface specified in this
 document.
 
@@ -23,6 +25,37 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
 are allocated in ranges depending on the device node type (video, radio,
 etc.).
 
+The existing V4L2 device node types are:
+
+======================== ======================================================
+Default device node name Usage
+======================== ======================================================
+``/dev/videoX``		 Video input/output devices
+``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
+``/dev/radioX``		 Radio tuners and modulators
+``/dev/swradioX``	 Software Defined Radio tuners and modulators
+``/dev/v4l-touchX``	 Touch sensors
+======================== ======================================================
+
+Where ``X`` is a non-negative number.
+
+.. note::
+
+   1. The actual device node name is system-dependent, as udev rules may apply.
+   2. There is no warranty that ``X`` will remain the same for the same
+      device, as the number depends on the device driver's probe order.
+      If you need an unique name, udev default rules produce
+      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directoiries containing
+      links that can be used uniquely to identify a V4L2 device node::
+
+	$ tree /dev/v4l
+	/dev/v4l
+	├── by-id
+	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
+	└── by-path
+	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
+
+
 Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
 options to select specific video/radio/vbi node numbers. This allows the
 user to request that the device node is named e.g. /dev/video5 instead
-- 
2.13.5

[toc] | [prev] | [next] | [standalone]

#1722221 — Re: [PATCH v5 2/7] media: open.rst: better document device node naming

Hi Mauro,

On Mon, Aug 28, 2017 at 09:53:56AM -0300, Mauro Carvalho Chehab wrote:
> Right now, only kAPI documentation describes the device naming.
> However, such description is needed at the uAPI too. Add it,
> and describe how to get an unique identify for a given device.
> 
> Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
>  Documentation/media/uapi/v4l/open.rst | 39 ++++++++++++++++++++++++++++++++---
>  1 file changed, 36 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> index afd116edb40d..fc0037091814 100644
> --- a/Documentation/media/uapi/v4l/open.rst
> +++ b/Documentation/media/uapi/v4l/open.rst
> @@ -7,12 +7,14 @@ Opening and Closing Devices
>  ***************************
>  
>  
> -Device Naming
> -=============
> +.. _v4l2_device_naming:
> +
> +V4L2 Device Node Naming
> +=======================
>  
>  V4L2 drivers are implemented as kernel modules, loaded manually by the
>  system administrator or automatically when a device is first discovered.
> -The driver modules plug into the "videodev" kernel module. It provides
> +The driver modules plug into the ``videodev`` kernel module. It provides
>  helper functions and a common application interface specified in this
>  document.
>  
> @@ -23,6 +25,37 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
>  are allocated in ranges depending on the device node type (video, radio,
>  etc.).
>  
> +The existing V4L2 device node types are:
> +
> +======================== ======================================================
> +Default device node name Usage
> +======================== ======================================================
> +``/dev/videoX``		 Video input/output devices
> +``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
> +``/dev/radioX``		 Radio tuners and modulators
> +``/dev/swradioX``	 Software Defined Radio tuners and modulators
> +``/dev/v4l-touchX``	 Touch sensors

Should we document V4L2 sub-device nodes here as well? They are implemented
by the V4L2 core as well as the other device node types.

Their purpose is somewhat different, though, and I think we'll need to make
that explicit somehow.

> +======================== ======================================================
> +
> +Where ``X`` is a non-negative number.
> +
> +.. note::
> +
> +   1. The actual device node name is system-dependent, as udev rules may apply.
> +   2. There is no warranty that ``X`` will remain the same for the same

s/warranty/guarantee/

> +      device, as the number depends on the device driver's probe order.
> +      If you need an unique name, udev default rules produce
> +      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directoiries containing

"directories"

> +      links that can be used uniquely to identify a V4L2 device node::
> +
> +	$ tree /dev/v4l
> +	/dev/v4l
> +	├── by-id
> +	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
> +	└── by-path
> +	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
> +
> +
>  Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
>  options to select specific video/radio/vbi node numbers. This allows the
>  user to request that the device node is named e.g. /dev/video5 instead

-- 
Kind regards,

Sakari Ailus
e-mail: sakari.ailus@iki.fi

[toc] | [prev] | [next] | [standalone]

#1722251 — Re: [PATCH v5 2/7] media: open.rst: better document device node naming

Hi Sakari,

Em Tue, 29 Aug 2017 11:34:06 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Mon, Aug 28, 2017 at 09:53:56AM -0300, Mauro Carvalho Chehab wrote:
> > Right now, only kAPI documentation describes the device naming.
> > However, such description is needed at the uAPI too. Add it,
> > and describe how to get an unique identify for a given device.
> > 
> > Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  Documentation/media/uapi/v4l/open.rst | 39 ++++++++++++++++++++++++++++++++---
> >  1 file changed, 36 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
> > index afd116edb40d..fc0037091814 100644
> > --- a/Documentation/media/uapi/v4l/open.rst
> > +++ b/Documentation/media/uapi/v4l/open.rst
> > @@ -7,12 +7,14 @@ Opening and Closing Devices
> >  ***************************
> >  
> >  
> > -Device Naming
> > -=============
> > +.. _v4l2_device_naming:
> > +
> > +V4L2 Device Node Naming
> > +=======================
> >  
> >  V4L2 drivers are implemented as kernel modules, loaded manually by the
> >  system administrator or automatically when a device is first discovered.
> > -The driver modules plug into the "videodev" kernel module. It provides
> > +The driver modules plug into the ``videodev`` kernel module. It provides
> >  helper functions and a common application interface specified in this
> >  document.
> >  
> > @@ -23,6 +25,37 @@ option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
> >  are allocated in ranges depending on the device node type (video, radio,
> >  etc.).
> >  
> > +The existing V4L2 device node types are:
> > +
> > +======================== ======================================================
> > +Default device node name Usage
> > +======================== ======================================================
> > +``/dev/videoX``		 Video input/output devices
> > +``/dev/vbiX``		 Vertical blank data (i.e. closed captions, teletext)
> > +``/dev/radioX``		 Radio tuners and modulators
> > +``/dev/swradioX``	 Software Defined Radio tuners and modulators
> > +``/dev/v4l-touchX``	 Touch sensors  
> 
> Should we document V4L2 sub-device nodes here as well? They are implemented
> by the V4L2 core as well as the other device node types.
> 
> Their purpose is somewhat different, though, and I think we'll need to make
> that explicit somehow.

Actually, what we're calling as "V4L2 Device node" are the vdev-centric
device nodes. That should not include /dev/v4l-subdevX.

What we can do here is to explicitly rule out the subdev interfaces,
with something like:

.. note::

	3. **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) provide a
	   different API and aren't considered as V4L2 device nodes.
	   They are covered at :ref:`subdev`.

> 
> > +======================== ======================================================
> > +
> > +Where ``X`` is a non-negative number.
> > +
> > +.. note::
> > +
> > +   1. The actual device node name is system-dependent, as udev rules may apply.
> > +   2. There is no warranty that ``X`` will remain the same for the same  
> 
> s/warranty/guarantee/

OK.

> 
> > +      device, as the number depends on the device driver's probe order.
> > +      If you need an unique name, udev default rules produce
> > +      ``/dev/v4l/by-id/`` and ``/dev/v4l/by-path/`` directoiries containing  
> 
> "directories"

OK.

> 
> > +      links that can be used uniquely to identify a V4L2 device node::
> > +
> > +	$ tree /dev/v4l
> > +	/dev/v4l
> > +	├── by-id
> > +	│   └── usb-OmniVision._USB_Camera-B4.04.27.1-video-index0 -> ../../video0
> > +	└── by-path
> > +	    └── pci-0000:00:14.0-usb-0:2:1.0-video-index0 -> ../../video0
> > +
> > +
> >  Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
> >  options to select specific video/radio/vbi node numbers. This allows the
> >  user to request that the device node is named e.g. /dev/video5 instead  
> 



Thanks,
Mauro

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web