Re: [PATCH v9 1/5] media: open.rst: better document device node naming

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Fri, 8 May 2020 15:24:33 +0200
Hans Verkuil <hverkuil-cisco@xs4all.nl> escreveu:

> On 08/05/2020 15:10, 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.  
> 
> identifier
> 
> > 
> > Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  .../userspace-api/media/v4l/open.rst          | 43 +++++++++++++++++--
> >  1 file changed, 40 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/userspace-api/media/v4l/open.rst b/Documentation/userspace-api/media/v4l/open.rst
> > index 38046ef20141..86816b247a17 100644
> > --- a/Documentation/userspace-api/media/v4l/open.rst
> > +++ b/Documentation/userspace-api/media/v4l/open.rst
> > @@ -14,12 +14,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.
> >  
> > @@ -30,6 +32,41 @@ 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 device nodes supported by the Video4Linux subsystem are:
> > +
> > +======================== ======================================================
> > +Default device node name Usage
> > +======================== ======================================================
> > +``/dev/videoX``		 Video input/output devices  
> 
> Also metadata input/output devices.
> 
> I would prefer capture/output given the traditional names that V4L2 uses.
> 
> > +``/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
> > +``/dev/v4l-sudevX``	 Video sub-devices (used by sensors and other I2C  
> 
> sudevX -> subdevX
> 
> You made this typo in more places, it's best to search and replace.
> 
> > +			 devices)\ [#]_  
> 
> That suggests that subdevs are i2c devices, they can be any processing block on
> any bus.

For all the above: Ok. Will address at the next version.


> 
> > +======================== ======================================================
> > +
> > +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 guarantee 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/`` directories 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
> > +
> > +.. [#] **V4L2 sub-device nodes** (e. g. ``/dev/v4l-sudevX``) use a different
> > +       set of system calls, as covered at :ref:`subdev`.
> > +
> >  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  
> 
> It looks like there is a missing period at the end of the sentence.

The full sentence here is:

	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
	of leaving it to chance. When the driver supports multiple devices of
	the same type more than one device node number can be assigned,
	separated by commas:

This paragraph (untouched by this patch) sounds ok to me ;-)

Thanks,
Mauro