[RFC PATCH 0/6] DocBook media: fixes

[RFC PATCH 0/6] DocBook media: fixes

[Hans Verkuil]

This patch series corrects a number of things that have annoyed me for
a long time, particularly at the start of the common.xml file where a
lot of the V4L2 basic behavior is described that is by now very much
out of date.

In addition the old incorrect packed RGB table is finally replaced by
the fixed version in the last patch: the original table is really,
really wrong and any driver that still follows that (none that I am
aware of) should be fixed.

Regards,

	Hans

[RFC PATCH 1/6] DocBook media: fix email addresses.

[Hans Verkuil]

From: Hans Verkuil <hans.verkuil@cisco.com>

Mauro's old redhat email address is no longer valid, update to the
current email address.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/dvb/dvbapi.xml | 2 +-
 Documentation/DocBook/media/v4l/v4l2.xml   | 2 +-
 Documentation/DocBook/media_api.tmpl       | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
index 0197bcc..49f46e8 100644
--- a/Documentation/DocBook/media/dvb/dvbapi.xml
+++ b/Documentation/DocBook/media/dvb/dvbapi.xml
@@ -18,7 +18,7 @@
 <firstname>Mauro</firstname>
 <othername role="mi">Carvalho</othername>
 <surname>Chehab</surname>
-<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
+<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
 <contrib>Ported document to Docbook XML.</contrib>
 </author>
 </authorgroup>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 8469fe1..53f5306 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -70,7 +70,7 @@ MPEG stream embedded, sliced VBI data format in this specification.
 Remote Controller chapter.</contrib>
 	<affiliation>
 	  <address>
-	    <email>mchehab@redhat.com</email>
+	    <email>m.chehab@samsung.com</email>
 	  </address>
 	</affiliation>
       </author>
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl
index 4c8d282..df6db3a 100644
--- a/Documentation/DocBook/media_api.tmpl
+++ b/Documentation/DocBook/media_api.tmpl
@@ -91,7 +91,7 @@ Foundation. A copy of the license is included in the chapter entitled
 <firstname>Mauro</firstname>
 <surname>Chehab</surname>
 <othername role="mi">Carvalho</othername>
-<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
+<affiliation><address><email>m.chehab@samsung.com</email></address></affiliation>
 <contrib>Initial version.</contrib>
 </author>
 </authorgroup>
-- 
1.8.5.2

[RFC PATCH 2/6] DocBook media: update copyright years and Introduction.

[Hans Verkuil]

From: Hans Verkuil <hans.verkuil@cisco.com>

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/dvb/dvbapi.xml |  2 +-
 Documentation/DocBook/media/v4l/v4l2.xml   |  1 +
 Documentation/DocBook/media_api.tmpl       | 13 +++++++------
 3 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
index 49f46e8..4c15396 100644
--- a/Documentation/DocBook/media/dvb/dvbapi.xml
+++ b/Documentation/DocBook/media/dvb/dvbapi.xml
@@ -28,7 +28,7 @@
 	<holder>Convergence GmbH</holder>
 </copyright>
 <copyright>
-	<year>2009-2012</year>
+	<year>2009-2014</year>
 	<holder>Mauro Carvalho Chehab</holder>
 </copyright>
 
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 53f5306..520b2a1 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -125,6 +125,7 @@ Remote Controller chapter.</contrib>
       <year>2011</year>
       <year>2012</year>
       <year>2013</year>
+      <year>2014</year>
       <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
 Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
 	Pawel Osciak</holder>
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl
index df6db3a..ba1d704 100644
--- a/Documentation/DocBook/media_api.tmpl
+++ b/Documentation/DocBook/media_api.tmpl
@@ -37,7 +37,7 @@
 <title>LINUX MEDIA INFRASTRUCTURE API</title>
 
 <copyright>
-	<year>2009-2012</year>
+	<year>2009-2014</year>
 	<holder>LinuxTV Developers</holder>
 </copyright>
 
@@ -58,12 +58,13 @@ Foundation. A copy of the license is included in the chapter entitled
 	<title>Introduction</title>
 
 	<para>This document covers the Linux Kernel to Userspace API's used by
-		video and radio straming devices, including video cameras,
+		video and radio streaming devices, including video cameras,
 		analog and digital TV receiver cards, AM/FM receiver cards,
-		streaming capture devices.</para>
+		streaming capture and output devices, codec devices and remote
+		controllers.</para>
 	<para>It is divided into four parts.</para>
-	<para>The first part covers radio, capture,
-		cameras and analog TV devices.</para>
+	<para>The first part covers radio, video capture and output,
+		cameras, analog TV devices and codecs.</para>
 	<para>The second part covers the
 		API used for digital TV and Internet reception via one of the
 		several digital tv standards. While it is called as DVB API,
@@ -96,7 +97,7 @@ Foundation. A copy of the license is included in the chapter entitled
 </author>
 </authorgroup>
 <copyright>
-	<year>2009-2012</year>
+	<year>2009-2014</year>
 	<holder>Mauro Carvalho Chehab</holder>
 </copyright>
 
-- 
1.8.5.2

[RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Hans Verkuil]

From: Hans Verkuil <hans.verkuil@cisco.com>

This section was horribly out of date. A lot of references to old and
obsolete behavior have been dropped.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/common.xml | 188 ++++++++++-------------------
 1 file changed, 67 insertions(+), 121 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index 1ddf354..da08df9 100644
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -38,70 +38,41 @@ the basic concepts applicable to all devices.</para>
 
       <para>V4L2 drivers are implemented as kernel modules, loaded
 manually by the system administrator or automatically when a device is
-first opened. The driver modules plug into the "videodev" kernel
+first discovered. The driver modules plug into the "videodev" kernel
 module. It provides helper functions and a common application
 interface specified in this document.</para>
 
       <para>Each driver thus loaded registers one or more device nodes
-with major number 81 and a minor number between 0 and 255. Assigning
-minor numbers to V4L2 devices is entirely up to the system administrator,
-this is primarily intended to solve conflicts between devices.<footnote>
-	  <para>Access permissions are associated with character
-device special files, hence we must ensure device numbers cannot
-change with the module load order. To this end minor numbers are no
-longer automatically assigned by the "videodev" module as in V4L but
-requested by the driver. The defaults will suffice for most people
-unless two drivers compete for the same minor numbers.</para>
-	</footnote> The module options to select minor numbers are named
-after the device special file with a "_nr" suffix. For example "video_nr"
-for <filename>/dev/video</filename> video capture devices. The number is
-an offset to the base minor number associated with the device type.
-<footnote>
-	  <para>In earlier versions of the V4L2 API the module options
-where named after the device special file with a "unit_" prefix, expressing
-the minor number itself, not an offset. Rationale for this change is unknown.
-Lastly the naming and semantics are just a convention among driver writers,
-the point to note is that minor numbers are not supposed to be hardcoded
-into drivers.</para>
-	</footnote> When the driver supports multiple devices of the same
-type more than one minor number can be assigned, separated by commas:
-<informalexample>
+with major number 81 and a minor number between 0 and 255. Minor numbers
+are allocated dynamically unless the kernel is compiled with the kernel
+option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
+allocated in ranges depending on the device node type (video, radio, etc.).</para>
+
+      <para>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:
+	<informalexample>
 	  <screen>
-&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
+&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
 	</informalexample></para>
 
       <para>In <filename>/etc/modules.conf</filename> this may be
 written as: <informalexample>
 	  <screen>
-alias char-major-81-0 mydriver
-alias char-major-81-1 mydriver
-alias char-major-81-64 mydriver              <co id="alias" />
-options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
+options mydriver video_nr=0,1 radio_nr=0,1
 	  </screen>
-	  <calloutlist>
-	    <callout arearefs="alias">
-	      <para>When an application attempts to open a device
-special file with major number 81 and minor number 0, 1, or 64, load
-"mydriver" (and the "videodev" module it depends upon).</para>
-	    </callout>
-	    <callout arearefs="options">
-	      <para>Register the first two video capture devices with
-minor number 0 and 1 (base number is 0), the first two radio device
-with minor number 64 and 65 (base 64).</para>
-	    </callout>
-	  </calloutlist>
-	</informalexample> When no minor number is given as module
-option the driver supplies a default. <xref linkend="devices" />
-recommends the base minor numbers to be used for the various device
-types. Obviously minor numbers must be unique. When the number is
-already in use the <emphasis>offending device</emphasis> will not be
-registered. <!-- Blessed by Linus Torvalds on
-linux-kernel@vger.kernel.org, 2002-11-20. --></para>
-
-      <para>By convention system administrators create various
-character device special files with these major and minor numbers in
-the <filename>/dev</filename> directory. The names recommended for the
-different V4L2 device types are listed in <xref linkend="devices" />.
+	</informalexample> When no device node number is given as module
+option the driver supplies a default.</para>
+
+      <para>Normally udev will create the device nodes in /dev automatically
+for you. If udev is not installed, then you need to enable the
+CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
+relate a minor number to a device node number. I.e., you need to be certain
+that minor number 5 maps to device node name video5. With this kernel option
+different device types have different minor number ranges. These ranges are
+listed in <xref linkend="devices" />.
 </para>
 
       <para>The creation of character special files (with
@@ -110,63 +81,40 @@ devices cannot be opened by major and minor number. That means
 applications cannot <emphasis>reliable</emphasis> scan for loaded or
 installed drivers. The user must enter a device name, or the
 application can try the conventional device names.</para>
-
-      <para>Under the device filesystem (devfs) the minor number
-options are ignored. V4L2 drivers (or by proxy the "videodev" module)
-automatically create the required device files in the
-<filename>/dev/v4l</filename> directory using the conventional device
-names above.</para>
     </section>
 
     <section id="related">
       <title>Related Devices</title>
 
-      <para>Devices can support several related functions. For example
-video capturing, video overlay and VBI capturing are related because
-these functions share, amongst other, the same video input and tuner
-frequency. V4L and earlier versions of V4L2 used the same device name
-and minor number for video capturing and overlay, but different ones
-for VBI. Experience showed this approach has several problems<footnote>
-	  <para>Given a device file name one cannot reliable find
-related devices. For once names are arbitrary and in a system with
-multiple devices, where only some support VBI capturing, a
-<filename>/dev/video2</filename> is not necessarily related to
-<filename>/dev/vbi2</filename>. The V4L
-<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
-device file with a particular major and minor number.</para>
-	</footnote>, and to make things worse the V4L videodev module
-used to prohibit multiple opens of a device.</para>
-
-      <para>As a remedy the present version of the V4L2 API relaxed the
-concept of device types with specific names and minor numbers. For
-compatibility with old applications drivers must still register different
-minor numbers to assign a default function to the device. But if related
-functions are supported by the driver they must be available under all
-registered minor numbers. The desired function can be selected after
-opening the device as described in <xref linkend="devices" />.</para>
-
-      <para>Imagine a driver supporting video capturing, video
-overlay, raw VBI capturing, and FM radio reception. It registers three
-devices with minor number 0, 64 and 224 (this numbering scheme is
-inherited from the V4L API). Regardless if
-<filename>/dev/video</filename> (81, 0) or
-<filename>/dev/vbi</filename> (81, 224) is opened the application can
-select any one of the video capturing, overlay or VBI capturing
-functions. Without programming (e.&nbsp;g. reading from the device
-with <application>dd</application> or <application>cat</application>)
-<filename>/dev/video</filename> captures video images, while
-<filename>/dev/vbi</filename> captures raw VBI data.
-<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
-unrelated to the video functions. Being unrelated does not imply the
-devices can be used at the same time, however. The &func-open;
-function may very well return an &EBUSY;.</para>
+      <para>Devices can support several functions. For example
+video capturing, VBI capturing and radio support.</para>
+
+      <para>The V4L2 API creates different nodes for each of these functions.
+One exception to this rule is the overlay function: this is shared
+with the video capture node (or video output node for output overlays).</para>
+
+      <para>The V4L2 API was designed with the idea that one device node could support
+all functions. However, in practice this never worked: this 'feature'
+was never used by applications and many drivers did not support it and if
+they did it was certainly never tested. In addition, switching a device
+node between different functions only works when using the streaming I/O
+API, not with the read()/write() API.</para>
+
+      <para>Today each device node supports just one function, with the
+exception of overlay support.</para>
 
       <para>Besides video input or output the hardware may also
 support audio sampling or playback. If so, these functions are
-implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
-audio mixer. The V4L2 API makes no provisions yet to find these
-related devices. If you have an idea please write to the linux-media
-mailing list: &v4l-ml;.</para>
+implemented as ALSA PCM devices with optional ALSA audio mixer
+devices.</para>
+
+      <para>One problem with all these devices is that the V4L2 API
+makes no provisions to find these related devices. Some really
+complex devices use the Media Controller (see <xref linkend="media_controller" />)
+which can be used for this purpose. But most drivers do not use it,
+and while some code exists that uses sysfs to discover related devices,
+there is no standard library yet. If you want to work on this please write
+to the linux-media mailing list: &v4l-ml;.</para>
     </section>
 
     <section>
@@ -176,19 +124,22 @@ mailing list: &v4l-ml;.</para>
 When this is supported by the driver, users can for example start a
 "panel" application to change controls like brightness or audio
 volume, while another application captures video and audio. In other words, panel
-applications are comparable to an OSS or ALSA audio mixer application.
-When a device supports multiple functions like capturing and overlay
-<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
-use of the device by forked processes or specialized applications.</para>
-
-      <para>Multiple opens are optional, although drivers should
-permit at least concurrent accesses without data exchange, &ie; panel
-applications. This implies &func-open; can return an &EBUSY; when the
-device is already in use, as well as &func-ioctl; functions initiating
-data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
-and &func-write; functions.</para>
-
-      <para>Mere opening a V4L2 device does not grant exclusive
+applications are comparable to an ALSA audio mixer application.
+Just opening a V4L2 device should not change the state of the device.
+Unfortunately, opening a radio device often switches the state of the
+device to radio mode in many drivers.</para>
+
+      <para>Almost all drivers allow multiple opens although there are
+still some old drivers that have not been updated to allow this.
+This implies &func-open; can return an &EBUSY; when the
+device is already in use.</para>
+
+      <para>It is never possible to start streaming when
+streaming is already in progress. So &func-ioctl; functions initiating
+data exchange (e.g. the &VIDIOC-STREAMON; ioctl), and the &func-read;
+and &func-write; functions can return an &EBUSY;.</para>
+
+      <para>Merely opening a V4L2 device does not grant exclusive
 access.<footnote>
 	  <para>Drivers could recognize the
 <constant>O_EXCL</constant> open flag. Presently this is not required,
@@ -206,12 +157,7 @@ additional access privileges using the priority mechanism described in
       <para>V4L2 drivers should not support multiple applications
 reading or writing the same data stream on a device by copying
 buffers, time multiplexing or similar means. This is better handled by
-a proxy application in user space. When the driver supports stream
-sharing anyway it must be implemented transparently. The V4L2 API does
-not specify how conflicts are solved. <!-- For example O_EXCL when the
-application does not want to be preempted, PROT_READ mmapped buffers
-which can be mapped twice, what happens when image formats do not
-match etc.--></para>
+a proxy application in user space.</para>
     </section>
 
     <section>
-- 
1.8.5.2

Re: [RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Mauro Carvalho Chehab]

Em Tue,  7 Jan 2014 14:06:54 +0100
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> From: Hans Verkuil <hans.verkuil@cisco.com>
> 
> This section was horribly out of date. A lot of references to old and
> obsolete behavior have been dropped.
> 
> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
> ---
>  Documentation/DocBook/media/v4l/common.xml | 188 ++++++++++-------------------
>  1 file changed, 67 insertions(+), 121 deletions(-)
> 
> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
> index 1ddf354..da08df9 100644
> --- a/Documentation/DocBook/media/v4l/common.xml
> +++ b/Documentation/DocBook/media/v4l/common.xml
> @@ -38,70 +38,41 @@ the basic concepts applicable to all devices.</para>
>  
>        <para>V4L2 drivers are implemented as kernel modules, loaded
>  manually by the system administrator or automatically when a device is
> -first opened. The driver modules plug into the "videodev" kernel
> +first discovered. The driver modules plug into the "videodev" kernel
>  module. It provides helper functions and a common application
>  interface specified in this document.</para>
>  
>        <para>Each driver thus loaded registers one or more device nodes
> -with major number 81 and a minor number between 0 and 255. Assigning
> -minor numbers to V4L2 devices is entirely up to the system administrator,
> -this is primarily intended to solve conflicts between devices.<footnote>
> -	  <para>Access permissions are associated with character
> -device special files, hence we must ensure device numbers cannot
> -change with the module load order. To this end minor numbers are no
> -longer automatically assigned by the "videodev" module as in V4L but
> -requested by the driver. The defaults will suffice for most people
> -unless two drivers compete for the same minor numbers.</para>
> -	</footnote> The module options to select minor numbers are named
> -after the device special file with a "_nr" suffix. For example "video_nr"
> -for <filename>/dev/video</filename> video capture devices. The number is
> -an offset to the base minor number associated with the device type.
> -<footnote>
> -	  <para>In earlier versions of the V4L2 API the module options
> -where named after the device special file with a "unit_" prefix, expressing
> -the minor number itself, not an offset. Rationale for this change is unknown.
> -Lastly the naming and semantics are just a convention among driver writers,
> -the point to note is that minor numbers are not supposed to be hardcoded
> -into drivers.</para>
> -	</footnote> When the driver supports multiple devices of the same
> -type more than one minor number can be assigned, separated by commas:
> -<informalexample>
> +with major number 81 and a minor number between 0 and 255. Minor numbers
> +are allocated dynamically unless the kernel is compiled with the kernel
> +option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
> +allocated in ranges depending on the device node type (video, radio, etc.).</para>
> +
> +      <para>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:
> +	<informalexample>
>  	  <screen>
> -&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
> +&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
>  	</informalexample></para>
>  
>        <para>In <filename>/etc/modules.conf</filename> this may be
>  written as: <informalexample>
>  	  <screen>
> -alias char-major-81-0 mydriver
> -alias char-major-81-1 mydriver
> -alias char-major-81-64 mydriver              <co id="alias" />
> -options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
> +options mydriver video_nr=0,1 radio_nr=0,1
>  	  </screen>
> -	  <calloutlist>
> -	    <callout arearefs="alias">
> -	      <para>When an application attempts to open a device
> -special file with major number 81 and minor number 0, 1, or 64, load
> -"mydriver" (and the "videodev" module it depends upon).</para>
> -	    </callout>
> -	    <callout arearefs="options">
> -	      <para>Register the first two video capture devices with
> -minor number 0 and 1 (base number is 0), the first two radio device
> -with minor number 64 and 65 (base 64).</para>
> -	    </callout>
> -	  </calloutlist>
> -	</informalexample> When no minor number is given as module
> -option the driver supplies a default. <xref linkend="devices" />
> -recommends the base minor numbers to be used for the various device
> -types. Obviously minor numbers must be unique. When the number is
> -already in use the <emphasis>offending device</emphasis> will not be
> -registered. <!-- Blessed by Linus Torvalds on
> -linux-kernel@vger.kernel.org, 2002-11-20. --></para>
> -
> -      <para>By convention system administrators create various
> -character device special files with these major and minor numbers in
> -the <filename>/dev</filename> directory. The names recommended for the
> -different V4L2 device types are listed in <xref linkend="devices" />.
> +	</informalexample> When no device node number is given as module
> +option the driver supplies a default.</para>
> +
> +      <para>Normally udev will create the device nodes in /dev automatically
> +for you. If udev is not installed, then you need to enable the
> +CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
> +relate a minor number to a device node number. I.e., you need to be certain
> +that minor number 5 maps to device node name video5. With this kernel option
> +different device types have different minor number ranges. These ranges are
> +listed in <xref linkend="devices" />.
>  </para>
>  
>        <para>The creation of character special files (with
> @@ -110,63 +81,40 @@ devices cannot be opened by major and minor number. That means
>  applications cannot <emphasis>reliable</emphasis> scan for loaded or
>  installed drivers. The user must enter a device name, or the
>  application can try the conventional device names.</para>
> -
> -      <para>Under the device filesystem (devfs) the minor number
> -options are ignored. V4L2 drivers (or by proxy the "videodev" module)
> -automatically create the required device files in the
> -<filename>/dev/v4l</filename> directory using the conventional device
> -names above.</para>
>      </section>
>  
>      <section id="related">
>        <title>Related Devices</title>
>  
> -      <para>Devices can support several related functions. For example
> -video capturing, video overlay and VBI capturing are related because
> -these functions share, amongst other, the same video input and tuner
> -frequency. V4L and earlier versions of V4L2 used the same device name
> -and minor number for video capturing and overlay, but different ones
> -for VBI. Experience showed this approach has several problems<footnote>
> -	  <para>Given a device file name one cannot reliable find
> -related devices. For once names are arbitrary and in a system with
> -multiple devices, where only some support VBI capturing, a
> -<filename>/dev/video2</filename> is not necessarily related to
> -<filename>/dev/vbi2</filename>. The V4L
> -<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
> -device file with a particular major and minor number.</para>
> -	</footnote>, and to make things worse the V4L videodev module
> -used to prohibit multiple opens of a device.</para>
> -
> -      <para>As a remedy the present version of the V4L2 API relaxed the
> -concept of device types with specific names and minor numbers. For
> -compatibility with old applications drivers must still register different
> -minor numbers to assign a default function to the device. But if related
> -functions are supported by the driver they must be available under all
> -registered minor numbers. The desired function can be selected after
> -opening the device as described in <xref linkend="devices" />.</para>
> -
> -      <para>Imagine a driver supporting video capturing, video
> -overlay, raw VBI capturing, and FM radio reception. It registers three
> -devices with minor number 0, 64 and 224 (this numbering scheme is
> -inherited from the V4L API). Regardless if
> -<filename>/dev/video</filename> (81, 0) or
> -<filename>/dev/vbi</filename> (81, 224) is opened the application can
> -select any one of the video capturing, overlay or VBI capturing
> -functions. Without programming (e.&nbsp;g. reading from the device
> -with <application>dd</application> or <application>cat</application>)
> -<filename>/dev/video</filename> captures video images, while
> -<filename>/dev/vbi</filename> captures raw VBI data.
> -<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
> -unrelated to the video functions. Being unrelated does not imply the
> -devices can be used at the same time, however. The &func-open;
> -function may very well return an &EBUSY;.</para>
> +      <para>Devices can support several functions. For example
> +video capturing, VBI capturing and radio support.</para>

"function" seems to be a poor choice of word here. Ok, it comes from the
original text, but it is still not clear.

I would use another word, like "broadcast type", in order to refer to
radio, software defined radio, VBI and video.

> +
> +      <para>The V4L2 API creates different nodes for each of these functions.
> +One exception to this rule is the overlay function: this is shared
> +with the video capture node (or video output node for output overlays).</para>

The mention to overlay here is completely out of context, and proofs
my point that "function" is a very bad choice: overlay is not a
broadcast type. It is just one of the ways to output the data. The same
device node can support multiple "delivery types":
	- overlay;
	- dma-buf;
	- mmap;
	- read or write.

Let's not mix those two concepts in the new text.

Also, the delivery type has nothing to do with "Opening and closing devices".

> +
> +      <para>The V4L2 API was designed with the idea that one device node could support
> +all functions. However, in practice this never worked: this 'feature'
> +was never used by applications and many drivers did not support it and if
> +they did it was certainly never tested. In addition, switching a device
> +node between different functions only works when using the streaming I/O
> +API, not with the read()/write() API.</para>
> +
> +      <para>Today each device node supports just one function, with the
> +exception of overlay support.</para>
>  
>        <para>Besides video input or output the hardware may also
>  support audio sampling or playback. If so, these functions are
> -implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
> -audio mixer. The V4L2 API makes no provisions yet to find these
> -related devices. If you have an idea please write to the linux-media
> -mailing list: &v4l-ml;.</para>
> +implemented as ALSA PCM devices with optional ALSA audio mixer
> +devices.</para>
> +
> +      <para>One problem with all these devices is that the V4L2 API
> +makes no provisions to find these related devices. Some really
> +complex devices use the Media Controller (see <xref linkend="media_controller" />)
> +which can be used for this purpose. But most drivers do not use it,
> +and while some code exists that uses sysfs to discover related devices,
> +there is no standard library yet. If you want to work on this please write
> +to the linux-media mailing list: &v4l-ml;.</para>

Not true. It is there at v4l-utils. Ok, patches are always welcome.

>      </section>
>  
>      <section>
> @@ -176,19 +124,22 @@ mailing list: &v4l-ml;.</para>
>  When this is supported by the driver, users can for example start a
>  "panel" application to change controls like brightness or audio
>  volume, while another application captures video and audio. In other words, panel
> -applications are comparable to an OSS or ALSA audio mixer application.
> -When a device supports multiple functions like capturing and overlay
> -<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
> -use of the device by forked processes or specialized applications.</para>
> -
> -      <para>Multiple opens are optional, although drivers should
> -permit at least concurrent accesses without data exchange, &ie; panel
> -applications. This implies &func-open; can return an &EBUSY; when the
> -device is already in use, as well as &func-ioctl; functions initiating
> -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
> -and &func-write; functions.</para>
> -
> -      <para>Mere opening a V4L2 device does not grant exclusive
> +applications are comparable to an ALSA audio mixer application.
> +Just opening a V4L2 device should not change the state of the device.
> +Unfortunately, opening a radio device often switches the state of the
> +device to radio mode in many drivers.</para>

This is an API spec document. It should say what is the expected behavior,
and not mention non-compliant stuff.

> +
> +      <para>Almost all drivers allow multiple opens although there are
> +still some old drivers that have not been updated to allow this.
> +This implies &func-open; can return an &EBUSY; when the
> +device is already in use.</para>

What drivers? We should fix the driver, not the API doc.

Also, we need more discussions. It could make sense to return EBUSY
even on new drivers, for example, if they're already in usage by some
other broadcast type?

> +
> +      <para>It is never possible to start streaming when
> +streaming is already in progress. So &func-ioctl; functions initiating
> +data exchange (e.g. the &VIDIOC-STREAMON; ioctl), and the &func-read;
> +and &func-write; functions can return an &EBUSY;.</para>

Here, the Overlay is a somewhat an exception, not in the sense that 
they'll call streamon latter, but in the sense that overlay ioctls
can happen after streaming. I don't remember well how DMA buf works,
but I think you can also start to use a mmaped copy of the dma buffers
after start streaming.

> +
> +      <para>Merely opening a V4L2 device does not grant exclusive
>  access.<footnote>
>  	  <para>Drivers could recognize the
>  <constant>O_EXCL</constant> open flag. Presently this is not required,
> @@ -206,12 +157,7 @@ additional access privileges using the priority mechanism described in
>        <para>V4L2 drivers should not support multiple applications
>  reading or writing the same data stream on a device by copying
>  buffers, time multiplexing or similar means. This is better handled by
> -a proxy application in user space. When the driver supports stream
> -sharing anyway it must be implemented transparently. The V4L2 API does
> -not specify how conflicts are solved. <!-- For example O_EXCL when the
> -application does not want to be preempted, PROT_READ mmapped buffers
> -which can be mapped twice, what happens when image formats do not
> -match etc.--></para>
> +a proxy application in user space.</para>
>      </section>
>  
>      <section>


-- 

Cheers,
Mauro

Re: [RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Hans Verkuil]

On 01/13/2014 04:20 PM, Mauro Carvalho Chehab wrote:
> Em Tue,  7 Jan 2014 14:06:54 +0100
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> From: Hans Verkuil <hans.verkuil@cisco.com>
>>
>> This section was horribly out of date. A lot of references to old and
>> obsolete behavior have been dropped.
>>
>> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
>> ---
>>  Documentation/DocBook/media/v4l/common.xml | 188 ++++++++++-------------------
>>  1 file changed, 67 insertions(+), 121 deletions(-)
>>
>> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
>> index 1ddf354..da08df9 100644
>> --- a/Documentation/DocBook/media/v4l/common.xml
>> +++ b/Documentation/DocBook/media/v4l/common.xml
>> @@ -38,70 +38,41 @@ the basic concepts applicable to all devices.</para>
>>  
>>        <para>V4L2 drivers are implemented as kernel modules, loaded
>>  manually by the system administrator or automatically when a device is
>> -first opened. The driver modules plug into the "videodev" kernel
>> +first discovered. The driver modules plug into the "videodev" kernel
>>  module. It provides helper functions and a common application
>>  interface specified in this document.</para>
>>  
>>        <para>Each driver thus loaded registers one or more device nodes
>> -with major number 81 and a minor number between 0 and 255. Assigning
>> -minor numbers to V4L2 devices is entirely up to the system administrator,
>> -this is primarily intended to solve conflicts between devices.<footnote>
>> -	  <para>Access permissions are associated with character
>> -device special files, hence we must ensure device numbers cannot
>> -change with the module load order. To this end minor numbers are no
>> -longer automatically assigned by the "videodev" module as in V4L but
>> -requested by the driver. The defaults will suffice for most people
>> -unless two drivers compete for the same minor numbers.</para>
>> -	</footnote> The module options to select minor numbers are named
>> -after the device special file with a "_nr" suffix. For example "video_nr"
>> -for <filename>/dev/video</filename> video capture devices. The number is
>> -an offset to the base minor number associated with the device type.
>> -<footnote>
>> -	  <para>In earlier versions of the V4L2 API the module options
>> -where named after the device special file with a "unit_" prefix, expressing
>> -the minor number itself, not an offset. Rationale for this change is unknown.
>> -Lastly the naming and semantics are just a convention among driver writers,
>> -the point to note is that minor numbers are not supposed to be hardcoded
>> -into drivers.</para>
>> -	</footnote> When the driver supports multiple devices of the same
>> -type more than one minor number can be assigned, separated by commas:
>> -<informalexample>
>> +with major number 81 and a minor number between 0 and 255. Minor numbers
>> +are allocated dynamically unless the kernel is compiled with the kernel
>> +option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
>> +allocated in ranges depending on the device node type (video, radio, etc.).</para>
>> +
>> +      <para>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:
>> +	<informalexample>
>>  	  <screen>
>> -&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
>> +&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
>>  	</informalexample></para>
>>  
>>        <para>In <filename>/etc/modules.conf</filename> this may be
>>  written as: <informalexample>
>>  	  <screen>
>> -alias char-major-81-0 mydriver
>> -alias char-major-81-1 mydriver
>> -alias char-major-81-64 mydriver              <co id="alias" />
>> -options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
>> +options mydriver video_nr=0,1 radio_nr=0,1
>>  	  </screen>
>> -	  <calloutlist>
>> -	    <callout arearefs="alias">
>> -	      <para>When an application attempts to open a device
>> -special file with major number 81 and minor number 0, 1, or 64, load
>> -"mydriver" (and the "videodev" module it depends upon).</para>
>> -	    </callout>
>> -	    <callout arearefs="options">
>> -	      <para>Register the first two video capture devices with
>> -minor number 0 and 1 (base number is 0), the first two radio device
>> -with minor number 64 and 65 (base 64).</para>
>> -	    </callout>
>> -	  </calloutlist>
>> -	</informalexample> When no minor number is given as module
>> -option the driver supplies a default. <xref linkend="devices" />
>> -recommends the base minor numbers to be used for the various device
>> -types. Obviously minor numbers must be unique. When the number is
>> -already in use the <emphasis>offending device</emphasis> will not be
>> -registered. <!-- Blessed by Linus Torvalds on
>> -linux-kernel@vger.kernel.org, 2002-11-20. --></para>
>> -
>> -      <para>By convention system administrators create various
>> -character device special files with these major and minor numbers in
>> -the <filename>/dev</filename> directory. The names recommended for the
>> -different V4L2 device types are listed in <xref linkend="devices" />.
>> +	</informalexample> When no device node number is given as module
>> +option the driver supplies a default.</para>
>> +
>> +      <para>Normally udev will create the device nodes in /dev automatically
>> +for you. If udev is not installed, then you need to enable the
>> +CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
>> +relate a minor number to a device node number. I.e., you need to be certain
>> +that minor number 5 maps to device node name video5. With this kernel option
>> +different device types have different minor number ranges. These ranges are
>> +listed in <xref linkend="devices" />.
>>  </para>
>>  
>>        <para>The creation of character special files (with
>> @@ -110,63 +81,40 @@ devices cannot be opened by major and minor number. That means
>>  applications cannot <emphasis>reliable</emphasis> scan for loaded or
>>  installed drivers. The user must enter a device name, or the
>>  application can try the conventional device names.</para>
>> -
>> -      <para>Under the device filesystem (devfs) the minor number
>> -options are ignored. V4L2 drivers (or by proxy the "videodev" module)
>> -automatically create the required device files in the
>> -<filename>/dev/v4l</filename> directory using the conventional device
>> -names above.</para>
>>      </section>
>>  
>>      <section id="related">
>>        <title>Related Devices</title>
>>  
>> -      <para>Devices can support several related functions. For example
>> -video capturing, video overlay and VBI capturing are related because
>> -these functions share, amongst other, the same video input and tuner
>> -frequency. V4L and earlier versions of V4L2 used the same device name
>> -and minor number for video capturing and overlay, but different ones
>> -for VBI. Experience showed this approach has several problems<footnote>
>> -	  <para>Given a device file name one cannot reliable find
>> -related devices. For once names are arbitrary and in a system with
>> -multiple devices, where only some support VBI capturing, a
>> -<filename>/dev/video2</filename> is not necessarily related to
>> -<filename>/dev/vbi2</filename>. The V4L
>> -<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
>> -device file with a particular major and minor number.</para>
>> -	</footnote>, and to make things worse the V4L videodev module
>> -used to prohibit multiple opens of a device.</para>
>> -
>> -      <para>As a remedy the present version of the V4L2 API relaxed the
>> -concept of device types with specific names and minor numbers. For
>> -compatibility with old applications drivers must still register different
>> -minor numbers to assign a default function to the device. But if related
>> -functions are supported by the driver they must be available under all
>> -registered minor numbers. The desired function can be selected after
>> -opening the device as described in <xref linkend="devices" />.</para>
>> -
>> -      <para>Imagine a driver supporting video capturing, video
>> -overlay, raw VBI capturing, and FM radio reception. It registers three
>> -devices with minor number 0, 64 and 224 (this numbering scheme is
>> -inherited from the V4L API). Regardless if
>> -<filename>/dev/video</filename> (81, 0) or
>> -<filename>/dev/vbi</filename> (81, 224) is opened the application can
>> -select any one of the video capturing, overlay or VBI capturing
>> -functions. Without programming (e.&nbsp;g. reading from the device
>> -with <application>dd</application> or <application>cat</application>)
>> -<filename>/dev/video</filename> captures video images, while
>> -<filename>/dev/vbi</filename> captures raw VBI data.
>> -<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
>> -unrelated to the video functions. Being unrelated does not imply the
>> -devices can be used at the same time, however. The &func-open;
>> -function may very well return an &EBUSY;.</para>
>> +      <para>Devices can support several functions. For example
>> +video capturing, VBI capturing and radio support.</para>
> 
> "function" seems to be a poor choice of word here. Ok, it comes from the
> original text, but it is still not clear.
> 
> I would use another word, like "broadcast type", in order to refer to
> radio, software defined radio, VBI and video.

I agree that it is not the best word, but neither is (IMHO) "broadcast type".
This would be something for a follow-up patch.

> 
>> +
>> +      <para>The V4L2 API creates different nodes for each of these functions.
>> +One exception to this rule is the overlay function: this is shared
>> +with the video capture node (or video output node for output overlays).</para>
> 
> The mention to overlay here is completely out of context, and proofs
> my point that "function" is a very bad choice: overlay is not a
> broadcast type. It is just one of the ways to output the data. The same
> device node can support multiple "delivery types":
> 	- overlay;
> 	- dma-buf;
> 	- mmap;
> 	- read or write.
> 
> Let's not mix those two concepts in the new text.
> 
> Also, the delivery type has nothing to do with "Opening and closing devices".

I like the word "delivery type" in this context and I agree with you here.
I'll see if I can improve this text.

> 
>> +
>> +      <para>The V4L2 API was designed with the idea that one device node could support
>> +all functions. However, in practice this never worked: this 'feature'
>> +was never used by applications and many drivers did not support it and if
>> +they did it was certainly never tested. In addition, switching a device
>> +node between different functions only works when using the streaming I/O
>> +API, not with the read()/write() API.</para>
>> +
>> +      <para>Today each device node supports just one function, with the
>> +exception of overlay support.</para>
>>  
>>        <para>Besides video input or output the hardware may also
>>  support audio sampling or playback. If so, these functions are
>> -implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
>> -audio mixer. The V4L2 API makes no provisions yet to find these
>> -related devices. If you have an idea please write to the linux-media
>> -mailing list: &v4l-ml;.</para>
>> +implemented as ALSA PCM devices with optional ALSA audio mixer
>> +devices.</para>
>> +
>> +      <para>One problem with all these devices is that the V4L2 API
>> +makes no provisions to find these related devices. Some really
>> +complex devices use the Media Controller (see <xref linkend="media_controller" />)
>> +which can be used for this purpose. But most drivers do not use it,
>> +and while some code exists that uses sysfs to discover related devices,
>> +there is no standard library yet. If you want to work on this please write
>> +to the linux-media mailing list: &v4l-ml;.</para>
> 
> Not true. It is there at v4l-utils. Ok, patches are always welcome.

Well, sort of. That library only handles sysfs, not the mc. I know Laurent
has been working on a better replacement, but that's been stalled for ages.
In other words, someone needs to spend time on this and create a proper
library for this.

> 
>>      </section>
>>  
>>      <section>
>> @@ -176,19 +124,22 @@ mailing list: &v4l-ml;.</para>
>>  When this is supported by the driver, users can for example start a
>>  "panel" application to change controls like brightness or audio
>>  volume, while another application captures video and audio. In other words, panel
>> -applications are comparable to an OSS or ALSA audio mixer application.
>> -When a device supports multiple functions like capturing and overlay
>> -<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
>> -use of the device by forked processes or specialized applications.</para>
>> -
>> -      <para>Multiple opens are optional, although drivers should
>> -permit at least concurrent accesses without data exchange, &ie; panel
>> -applications. This implies &func-open; can return an &EBUSY; when the
>> -device is already in use, as well as &func-ioctl; functions initiating
>> -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
>> -and &func-write; functions.</para>
>> -
>> -      <para>Mere opening a V4L2 device does not grant exclusive
>> +applications are comparable to an ALSA audio mixer application.
>> +Just opening a V4L2 device should not change the state of the device.
>> +Unfortunately, opening a radio device often switches the state of the
>> +device to radio mode in many drivers.</para>
> 
> This is an API spec document. It should say what is the expected behavior,
> and not mention non-compliant stuff.

How about putting this in a footnote? I do agree with you, but the fact is
that most if not all drivers that support both radio and video behave this
way. So one could argue that it is the spec that is non-compliant :-)

That said, at some point this should be fixed.

> 
>> +
>> +      <para>Almost all drivers allow multiple opens although there are
>> +still some old drivers that have not been updated to allow this.
>> +This implies &func-open; can return an &EBUSY; when the
>> +device is already in use.</para>
> 
> What drivers? We should fix the driver, not the API doc.

vino.c (I do have fixes for this in an old branch), timblogiw.c, fsl-viu.c.
There are probably a few more. Generally such drivers are old and/or obscure.

Since I am still working (slowly) on converting drivers to the modern frameworks
I'll come across these eventually.

> Also, we need more discussions. It could make sense to return EBUSY
> even on new drivers, for example, if they're already in usage by some
> other broadcast type?

You are not using it until you actually start streaming (or allocating buffers,
or whatever). There is no reason within the current framework to return EBUSY
for just opening a device node.

Not being able to open a device node a second time makes it impossible to
create e.g. monitoring applications that do something when an event happens.

> 
>> +
>> +      <para>It is never possible to start streaming when
>> +streaming is already in progress. So &func-ioctl; functions initiating
>> +data exchange (e.g. the &VIDIOC-STREAMON; ioctl), and the &func-read;
>> +and &func-write; functions can return an &EBUSY;.</para>
> 
> Here, the Overlay is a somewhat an exception, not in the sense that 
> they'll call streamon latter, but in the sense that overlay ioctls
> can happen after streaming.

I'll make a note of that.

> I don't remember well how DMA buf works,
> but I think you can also start to use a mmaped copy of the dma buffers
> after start streaming.

Possibly, but that has nothing to do with this paragraph. Once a file
handle calls STREAMON, then no other file handle of the same device node
can call STREAMON, unless the owner stops streaming and releases all
resources (REQBUFS(0)).

> 
>> +
>> +      <para>Merely opening a V4L2 device does not grant exclusive
>>  access.<footnote>
>>  	  <para>Drivers could recognize the
>>  <constant>O_EXCL</constant> open flag. Presently this is not required,
>> @@ -206,12 +157,7 @@ additional access privileges using the priority mechanism described in
>>        <para>V4L2 drivers should not support multiple applications
>>  reading or writing the same data stream on a device by copying
>>  buffers, time multiplexing or similar means. This is better handled by
>> -a proxy application in user space. When the driver supports stream
>> -sharing anyway it must be implemented transparently. The V4L2 API does
>> -not specify how conflicts are solved. <!-- For example O_EXCL when the
>> -application does not want to be preempted, PROT_READ mmapped buffers
>> -which can be mapped twice, what happens when image formats do not
>> -match etc.--></para>
>> +a proxy application in user space.</para>
>>      </section>
>>  
>>      <section>
> 
> 

Thanks!

	Hans

Re: [RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Mauro Carvalho Chehab]

Em Mon, 13 Jan 2014 17:15:40 +0100
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> On 01/13/2014 04:20 PM, Mauro Carvalho Chehab wrote:
> > Em Tue,  7 Jan 2014 14:06:54 +0100
> > Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> > 
> >> From: Hans Verkuil <hans.verkuil@cisco.com>
> >>
> >> This section was horribly out of date. A lot of references to old and
> >> obsolete behavior have been dropped.

Forgot to mention, put patches 1 and 2 are ok. I'll review the patches 4-6
later this week.

> >>
> >> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
> >> ---
> >>  Documentation/DocBook/media/v4l/common.xml | 188 ++++++++++-------------------
> >>  1 file changed, 67 insertions(+), 121 deletions(-)
> >>
> >> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
> >> index 1ddf354..da08df9 100644
> >> --- a/Documentation/DocBook/media/v4l/common.xml
> >> +++ b/Documentation/DocBook/media/v4l/common.xml
> >> @@ -38,70 +38,41 @@ the basic concepts applicable to all devices.</para>
> >>  
> >>        <para>V4L2 drivers are implemented as kernel modules, loaded
> >>  manually by the system administrator or automatically when a device is
> >> -first opened. The driver modules plug into the "videodev" kernel
> >> +first discovered. The driver modules plug into the "videodev" kernel
> >>  module. It provides helper functions and a common application
> >>  interface specified in this document.</para>
> >>  
> >>        <para>Each driver thus loaded registers one or more device nodes
> >> -with major number 81 and a minor number between 0 and 255. Assigning
> >> -minor numbers to V4L2 devices is entirely up to the system administrator,
> >> -this is primarily intended to solve conflicts between devices.<footnote>
> >> -	  <para>Access permissions are associated with character
> >> -device special files, hence we must ensure device numbers cannot
> >> -change with the module load order. To this end minor numbers are no
> >> -longer automatically assigned by the "videodev" module as in V4L but
> >> -requested by the driver. The defaults will suffice for most people
> >> -unless two drivers compete for the same minor numbers.</para>
> >> -	</footnote> The module options to select minor numbers are named
> >> -after the device special file with a "_nr" suffix. For example "video_nr"
> >> -for <filename>/dev/video</filename> video capture devices. The number is
> >> -an offset to the base minor number associated with the device type.
> >> -<footnote>
> >> -	  <para>In earlier versions of the V4L2 API the module options
> >> -where named after the device special file with a "unit_" prefix, expressing
> >> -the minor number itself, not an offset. Rationale for this change is unknown.
> >> -Lastly the naming and semantics are just a convention among driver writers,
> >> -the point to note is that minor numbers are not supposed to be hardcoded
> >> -into drivers.</para>
> >> -	</footnote> When the driver supports multiple devices of the same
> >> -type more than one minor number can be assigned, separated by commas:
> >> -<informalexample>
> >> +with major number 81 and a minor number between 0 and 255. Minor numbers
> >> +are allocated dynamically unless the kernel is compiled with the kernel
> >> +option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
> >> +allocated in ranges depending on the device node type (video, radio, etc.).</para>
> >> +
> >> +      <para>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:
> >> +	<informalexample>
> >>  	  <screen>
> >> -&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
> >> +&gt; modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
> >>  	</informalexample></para>
> >>  
> >>        <para>In <filename>/etc/modules.conf</filename> this may be
> >>  written as: <informalexample>
> >>  	  <screen>
> >> -alias char-major-81-0 mydriver
> >> -alias char-major-81-1 mydriver
> >> -alias char-major-81-64 mydriver              <co id="alias" />
> >> -options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
> >> +options mydriver video_nr=0,1 radio_nr=0,1
> >>  	  </screen>
> >> -	  <calloutlist>
> >> -	    <callout arearefs="alias">
> >> -	      <para>When an application attempts to open a device
> >> -special file with major number 81 and minor number 0, 1, or 64, load
> >> -"mydriver" (and the "videodev" module it depends upon).</para>
> >> -	    </callout>
> >> -	    <callout arearefs="options">
> >> -	      <para>Register the first two video capture devices with
> >> -minor number 0 and 1 (base number is 0), the first two radio device
> >> -with minor number 64 and 65 (base 64).</para>
> >> -	    </callout>
> >> -	  </calloutlist>
> >> -	</informalexample> When no minor number is given as module
> >> -option the driver supplies a default. <xref linkend="devices" />
> >> -recommends the base minor numbers to be used for the various device
> >> -types. Obviously minor numbers must be unique. When the number is
> >> -already in use the <emphasis>offending device</emphasis> will not be
> >> -registered. <!-- Blessed by Linus Torvalds on
> >> -linux-kernel@vger.kernel.org, 2002-11-20. --></para>
> >> -
> >> -      <para>By convention system administrators create various
> >> -character device special files with these major and minor numbers in
> >> -the <filename>/dev</filename> directory. The names recommended for the
> >> -different V4L2 device types are listed in <xref linkend="devices" />.
> >> +	</informalexample> When no device node number is given as module
> >> +option the driver supplies a default.</para>
> >> +
> >> +      <para>Normally udev will create the device nodes in /dev automatically
> >> +for you. If udev is not installed, then you need to enable the
> >> +CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
> >> +relate a minor number to a device node number. I.e., you need to be certain
> >> +that minor number 5 maps to device node name video5. With this kernel option
> >> +different device types have different minor number ranges. These ranges are
> >> +listed in <xref linkend="devices" />.
> >>  </para>
> >>  
> >>        <para>The creation of character special files (with
> >> @@ -110,63 +81,40 @@ devices cannot be opened by major and minor number. That means
> >>  applications cannot <emphasis>reliable</emphasis> scan for loaded or
> >>  installed drivers. The user must enter a device name, or the
> >>  application can try the conventional device names.</para>
> >> -
> >> -      <para>Under the device filesystem (devfs) the minor number
> >> -options are ignored. V4L2 drivers (or by proxy the "videodev" module)
> >> -automatically create the required device files in the
> >> -<filename>/dev/v4l</filename> directory using the conventional device
> >> -names above.</para>
> >>      </section>
> >>  
> >>      <section id="related">
> >>        <title>Related Devices</title>
> >>  
> >> -      <para>Devices can support several related functions. For example
> >> -video capturing, video overlay and VBI capturing are related because
> >> -these functions share, amongst other, the same video input and tuner
> >> -frequency. V4L and earlier versions of V4L2 used the same device name
> >> -and minor number for video capturing and overlay, but different ones
> >> -for VBI. Experience showed this approach has several problems<footnote>
> >> -	  <para>Given a device file name one cannot reliable find
> >> -related devices. For once names are arbitrary and in a system with
> >> -multiple devices, where only some support VBI capturing, a
> >> -<filename>/dev/video2</filename> is not necessarily related to
> >> -<filename>/dev/vbi2</filename>. The V4L
> >> -<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
> >> -device file with a particular major and minor number.</para>
> >> -	</footnote>, and to make things worse the V4L videodev module
> >> -used to prohibit multiple opens of a device.</para>
> >> -
> >> -      <para>As a remedy the present version of the V4L2 API relaxed the
> >> -concept of device types with specific names and minor numbers. For
> >> -compatibility with old applications drivers must still register different
> >> -minor numbers to assign a default function to the device. But if related
> >> -functions are supported by the driver they must be available under all
> >> -registered minor numbers. The desired function can be selected after
> >> -opening the device as described in <xref linkend="devices" />.</para>
> >> -
> >> -      <para>Imagine a driver supporting video capturing, video
> >> -overlay, raw VBI capturing, and FM radio reception. It registers three
> >> -devices with minor number 0, 64 and 224 (this numbering scheme is
> >> -inherited from the V4L API). Regardless if
> >> -<filename>/dev/video</filename> (81, 0) or
> >> -<filename>/dev/vbi</filename> (81, 224) is opened the application can
> >> -select any one of the video capturing, overlay or VBI capturing
> >> -functions. Without programming (e.&nbsp;g. reading from the device
> >> -with <application>dd</application> or <application>cat</application>)
> >> -<filename>/dev/video</filename> captures video images, while
> >> -<filename>/dev/vbi</filename> captures raw VBI data.
> >> -<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
> >> -unrelated to the video functions. Being unrelated does not imply the
> >> -devices can be used at the same time, however. The &func-open;
> >> -function may very well return an &EBUSY;.</para>
> >> +      <para>Devices can support several functions. For example
> >> +video capturing, VBI capturing and radio support.</para>
> > 
> > "function" seems to be a poor choice of word here. Ok, it comes from the
> > original text, but it is still not clear.
> > 
> > I would use another word, like "broadcast type", in order to refer to
> > radio, software defined radio, VBI and video.
> 
> I agree that it is not the best word, but neither is (IMHO) "broadcast type".
> This would be something for a follow-up patch.

I think we should use the right word here on this fix. Other suggestions:
	"stream type", "media type".

In any case, we should enumerate all those types here, maybe even putting
them into a table, in order to define precisely to what we're referring to.

> >> +
> >> +      <para>The V4L2 API creates different nodes for each of these functions.
> >> +One exception to this rule is the overlay function: this is shared
> >> +with the video capture node (or video output node for output overlays).</para>
> > 
> > The mention to overlay here is completely out of context, and proofs
> > my point that "function" is a very bad choice: overlay is not a
> > broadcast type. It is just one of the ways to output the data. The same
> > device node can support multiple "delivery types":
> > 	- overlay;
> > 	- dma-buf;
> > 	- mmap;
> > 	- read or write.
> > 
> > Let's not mix those two concepts in the new text.
> > 
> > Also, the delivery type has nothing to do with "Opening and closing devices".
> 
> I like the word "delivery type" in this context and I agree with you here.
> I'll see if I can improve this text.

Thanks!
 
> > 
> >> +
> >> +      <para>The V4L2 API was designed with the idea that one device node could support
> >> +all functions. However, in practice this never worked: this 'feature'
> >> +was never used by applications and many drivers did not support it and if
> >> +they did it was certainly never tested. In addition, switching a device
> >> +node between different functions only works when using the streaming I/O
> >> +API, not with the read()/write() API.</para>
> >> +
> >> +      <para>Today each device node supports just one function, with the
> >> +exception of overlay support.</para>
> >>  
> >>        <para>Besides video input or output the hardware may also
> >>  support audio sampling or playback. If so, these functions are
> >> -implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
> >> -audio mixer. The V4L2 API makes no provisions yet to find these
> >> -related devices. If you have an idea please write to the linux-media
> >> -mailing list: &v4l-ml;.</para>
> >> +implemented as ALSA PCM devices with optional ALSA audio mixer
> >> +devices.</para>
> >> +
> >> +      <para>One problem with all these devices is that the V4L2 API
> >> +makes no provisions to find these related devices. Some really
> >> +complex devices use the Media Controller (see <xref linkend="media_controller" />)
> >> +which can be used for this purpose. But most drivers do not use it,
> >> +and while some code exists that uses sysfs to discover related devices,
> >> +there is no standard library yet. If you want to work on this please write
> >> +to the linux-media mailing list: &v4l-ml;.</para>
> > 
> > Not true. It is there at v4l-utils. Ok, patches are always welcome.
> 
> Well, sort of. That library only handles sysfs, not the mc.

Yes, but that covers almost all devices, as the ones that use mc (except for
uvc) have more serious issues, as libv4l still don't work with them. So, they
demand dedicated applications anyway.

> I know Laurent
> has been working on a better replacement, but that's been stalled for ages.
> In other words, someone needs to spend time on this and create a proper
> library for this.

True, but, again, media controller based devices also need the libv4l
pieces that Sakari is working (also stalled).

Let's not mix things: associating media devices via sysfs has already
a library. If you want to mention about that, please point to it.

A more generic work that will make libv4l and that library to also work
with media controllers is a work to be done/finished.

> 
> > 
> >>      </section>
> >>  
> >>      <section>
> >> @@ -176,19 +124,22 @@ mailing list: &v4l-ml;.</para>
> >>  When this is supported by the driver, users can for example start a
> >>  "panel" application to change controls like brightness or audio
> >>  volume, while another application captures video and audio. In other words, panel
> >> -applications are comparable to an OSS or ALSA audio mixer application.
> >> -When a device supports multiple functions like capturing and overlay
> >> -<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
> >> -use of the device by forked processes or specialized applications.</para>
> >> -
> >> -      <para>Multiple opens are optional, although drivers should
> >> -permit at least concurrent accesses without data exchange, &ie; panel
> >> -applications. This implies &func-open; can return an &EBUSY; when the
> >> -device is already in use, as well as &func-ioctl; functions initiating
> >> -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
> >> -and &func-write; functions.</para>
> >> -
> >> -      <para>Mere opening a V4L2 device does not grant exclusive
> >> +applications are comparable to an ALSA audio mixer application.
> >> +Just opening a V4L2 device should not change the state of the device.
> >> +Unfortunately, opening a radio device often switches the state of the
> >> +device to radio mode in many drivers.</para>
> > 
> > This is an API spec document. It should say what is the expected behavior,
> > and not mention non-compliant stuff.
> 
> How about putting this in a footnote? I do agree with you, but the fact is
> that most if not all drivers that support both radio and video behave this
> way. So one could argue that it is the spec that is non-compliant :-)

If so, let's then fix the API to reflect that opening a radio device will
change the behavior.
> 
> That said, at some point this should be fixed.

Yes. one way or the other.

> > 
> >> +
> >> +      <para>Almost all drivers allow multiple opens although there are
> >> +still some old drivers that have not been updated to allow this.
> >> +This implies &func-open; can return an &EBUSY; when the
> >> +device is already in use.</para>
> > 
> > What drivers? We should fix the driver, not the API doc.
> 
> vino.c (I do have fixes for this in an old branch), timblogiw.c, fsl-viu.c.
> There are probably a few more. Generally such drivers are old and/or obscure.

Maybe in this specific case, a footnote could be added, although the better
would be to simply fix or remove/move to staging those drivers.

> Since I am still working (slowly) on converting drivers to the modern frameworks
> I'll come across these eventually.
> 
> > Also, we need more discussions. It could make sense to return EBUSY
> > even on new drivers, for example, if they're already in usage by some
> > other broadcast type?
> 
> You are not using it until you actually start streaming (or allocating buffers,
> or whatever). There is no reason within the current framework to return EBUSY
> for just opening a device node.
> 
> Not being able to open a device node a second time makes it impossible to
> create e.g. monitoring applications that do something when an event happens.

Agreed.

> > 
> >> +
> >> +      <para>It is never possible to start streaming when
> >> +streaming is already in progress. So &func-ioctl; functions initiating
> >> +data exchange (e.g. the &VIDIOC-STREAMON; ioctl), and the &func-read;
> >> +and &func-write; functions can return an &EBUSY;.</para>
> > 
> > Here, the Overlay is a somewhat an exception, not in the sense that 
> > they'll call streamon latter, but in the sense that overlay ioctls
> > can happen after streaming.
> 
> I'll make a note of that.
> 
> > I don't remember well how DMA buf works,
> > but I think you can also start to use a mmaped copy of the dma buffers
> > after start streaming.
> 
> Possibly, but that has nothing to do with this paragraph. Once a file
> handle calls STREAMON, then no other file handle of the same device node
> can call STREAMON, unless the owner stops streaming and releases all
> resources (REQBUFS(0)).

Well, then the paragraph text is not quite right, as it mentions 
"initiating data exchange".

If one mmaps memory latter to use it on an already started DMA buffer,
it is initiating the "memory copy" data exchange with the mmap.

STREAMON is just one of the ways to initiate a data exchange.

> > 
> >> +
> >> +      <para>Merely opening a V4L2 device does not grant exclusive
> >>  access.<footnote>
> >>  	  <para>Drivers could recognize the
> >>  <constant>O_EXCL</constant> open flag. Presently this is not required,
> >> @@ -206,12 +157,7 @@ additional access privileges using the priority mechanism described in
> >>        <para>V4L2 drivers should not support multiple applications
> >>  reading or writing the same data stream on a device by copying
> >>  buffers, time multiplexing or similar means. This is better handled by
> >> -a proxy application in user space. When the driver supports stream
> >> -sharing anyway it must be implemented transparently. The V4L2 API does
> >> -not specify how conflicts are solved. <!-- For example O_EXCL when the
> >> -application does not want to be preempted, PROT_READ mmapped buffers
> >> -which can be mapped twice, what happens when image formats do not
> >> -match etc.--></para>
> >> +a proxy application in user space.</para>
> >>      </section>
> >>  
> >>      <section>
> > 
> > 
> 
> Thanks!
> 
> 	Hans


-- 

Cheers,
Mauro

Re: [RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Hans Verkuil]

Hi Mauro,

On 01/13/2014 06:23 PM, Mauro Carvalho Chehab wrote:
> Em Mon, 13 Jan 2014 17:15:40 +0100
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>> On 01/13/2014 04:20 PM, Mauro Carvalho Chehab wrote:
>>> Em Tue,  7 Jan 2014 14:06:54 +0100
>>> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
>>>
>>>> From: Hans Verkuil <hans.verkuil@cisco.com>
>>>>
>>>> This section was horribly out of date. A lot of references to old and
>>>> obsolete behavior have been dropped.
> 
> Forgot to mention, put patches 1 and 2 are ok. I'll review the patches 4-6
> later this week.
> 
>>>>
>>>> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
>>>> ---
>>>>  Documentation/DocBook/media/v4l/common.xml | 188 ++++++++++-------------------
>>>>  1 file changed, 67 insertions(+), 121 deletions(-)
>>>>
>>>> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
>>>> index 1ddf354..da08df9 100644
>>>> --- a/Documentation/DocBook/media/v4l/common.xml
>>>> +++ b/Documentation/DocBook/media/v4l/common.xml

<snip>

>>>> +      <para>Devices can support several functions. For example
>>>> +video capturing, VBI capturing and radio support.</para>
>>>
>>> "function" seems to be a poor choice of word here. Ok, it comes from the
>>> original text, but it is still not clear.
>>>
>>> I would use another word, like "broadcast type", in order to refer to
>>> radio, software defined radio, VBI and video.
>>
>> I agree that it is not the best word, but neither is (IMHO) "broadcast type".
>> This would be something for a follow-up patch.
> 
> I think we should use the right word here on this fix. Other suggestions:
> 	"stream type", "media type".
> 
> In any case, we should enumerate all those types here, maybe even putting
> them into a table, in order to define precisely to what we're referring to.

I'm not going to do this now. I need to think about this some more, and this
might also require changes in a lot of other places in the documentation.

So as far as I am concerned this is something for a future patch.

> 
>>>> +
>>>> +      <para>The V4L2 API creates different nodes for each of these functions.
>>>> +One exception to this rule is the overlay function: this is shared
>>>> +with the video capture node (or video output node for output overlays).</para>
>>>
>>> The mention to overlay here is completely out of context, and proofs
>>> my point that "function" is a very bad choice: overlay is not a
>>> broadcast type. It is just one of the ways to output the data. The same
>>> device node can support multiple "delivery types":
>>> 	- overlay;
>>> 	- dma-buf;
>>> 	- mmap;
>>> 	- read or write.
>>>
>>> Let's not mix those two concepts in the new text.
>>>
>>> Also, the delivery type has nothing to do with "Opening and closing devices".
>>
>> I like the word "delivery type" in this context and I agree with you here.
>> I'll see if I can improve this text.
> 
> Thanks!

I decided to just drop this paragraph. It doesn't belong here and it doesn't
add anything useful.

>  
>>>
>>>> +
>>>> +      <para>The V4L2 API was designed with the idea that one device node could support
>>>> +all functions. However, in practice this never worked: this 'feature'
>>>> +was never used by applications and many drivers did not support it and if
>>>> +they did it was certainly never tested. In addition, switching a device
>>>> +node between different functions only works when using the streaming I/O
>>>> +API, not with the read()/write() API.</para>
>>>> +
>>>> +      <para>Today each device node supports just one function, with the
>>>> +exception of overlay support.</para>
>>>>  
>>>>        <para>Besides video input or output the hardware may also
>>>>  support audio sampling or playback. If so, these functions are
>>>> -implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
>>>> -audio mixer. The V4L2 API makes no provisions yet to find these
>>>> -related devices. If you have an idea please write to the linux-media
>>>> -mailing list: &v4l-ml;.</para>
>>>> +implemented as ALSA PCM devices with optional ALSA audio mixer
>>>> +devices.</para>
>>>> +
>>>> +      <para>One problem with all these devices is that the V4L2 API
>>>> +makes no provisions to find these related devices. Some really
>>>> +complex devices use the Media Controller (see <xref linkend="media_controller" />)
>>>> +which can be used for this purpose. But most drivers do not use it,
>>>> +and while some code exists that uses sysfs to discover related devices,
>>>> +there is no standard library yet. If you want to work on this please write
>>>> +to the linux-media mailing list: &v4l-ml;.</para>
>>>
>>> Not true. It is there at v4l-utils. Ok, patches are always welcome.
>>
>> Well, sort of. That library only handles sysfs, not the mc.
> 
> Yes, but that covers almost all devices, as the ones that use mc (except for
> uvc) have more serious issues, as libv4l still don't work with them. So, they
> demand dedicated applications anyway.
> 
>> I know Laurent
>> has been working on a better replacement, but that's been stalled for ages.
>> In other words, someone needs to spend time on this and create a proper
>> library for this.
> 
> True, but, again, media controller based devices also need the libv4l
> pieces that Sakari is working (also stalled).
> 
> Let's not mix things: associating media devices via sysfs has already
> a library. If you want to mention about that, please point to it.

I clarified the situation and added a pointer to the library in v4l-utils.

> 
> A more generic work that will make libv4l and that library to also work
> with media controllers is a work to be done/finished.
> 
>>
>>>
>>>>      </section>
>>>>  
>>>>      <section>
>>>> @@ -176,19 +124,22 @@ mailing list: &v4l-ml;.</para>
>>>>  When this is supported by the driver, users can for example start a
>>>>  "panel" application to change controls like brightness or audio
>>>>  volume, while another application captures video and audio. In other words, panel
>>>> -applications are comparable to an OSS or ALSA audio mixer application.
>>>> -When a device supports multiple functions like capturing and overlay
>>>> -<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
>>>> -use of the device by forked processes or specialized applications.</para>
>>>> -
>>>> -      <para>Multiple opens are optional, although drivers should
>>>> -permit at least concurrent accesses without data exchange, &ie; panel
>>>> -applications. This implies &func-open; can return an &EBUSY; when the
>>>> -device is already in use, as well as &func-ioctl; functions initiating
>>>> -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
>>>> -and &func-write; functions.</para>
>>>> -
>>>> -      <para>Mere opening a V4L2 device does not grant exclusive
>>>> +applications are comparable to an ALSA audio mixer application.
>>>> +Just opening a V4L2 device should not change the state of the device.
>>>> +Unfortunately, opening a radio device often switches the state of the
>>>> +device to radio mode in many drivers.</para>
>>>
>>> This is an API spec document. It should say what is the expected behavior,
>>> and not mention non-compliant stuff.
>>
>> How about putting this in a footnote? I do agree with you, but the fact is
>> that most if not all drivers that support both radio and video behave this
>> way. So one could argue that it is the spec that is non-compliant :-)
> 
> If so, let's then fix the API to reflect that opening a radio device will
> change the behavior.

I've put this in a footnote together with a mention that this situation needs
to be fixed.

>>
>> That said, at some point this should be fixed.
> 
> Yes. one way or the other.
> 
>>>
>>>> +
>>>> +      <para>Almost all drivers allow multiple opens although there are
>>>> +still some old drivers that have not been updated to allow this.
>>>> +This implies &func-open; can return an &EBUSY; when the
>>>> +device is already in use.</para>
>>>
>>> What drivers? We should fix the driver, not the API doc.
>>
>> vino.c (I do have fixes for this in an old branch), timblogiw.c, fsl-viu.c.
>> There are probably a few more. Generally such drivers are old and/or obscure.
> 
> Maybe in this specific case, a footnote could be added, although the better
> would be to simply fix or remove/move to staging those drivers.

I moved this to a footnote.

> 
>> Since I am still working (slowly) on converting drivers to the modern frameworks
>> I'll come across these eventually.
>>
>>> Also, we need more discussions. It could make sense to return EBUSY
>>> even on new drivers, for example, if they're already in usage by some
>>> other broadcast type?
>>
>> You are not using it until you actually start streaming (or allocating buffers,
>> or whatever). There is no reason within the current framework to return EBUSY
>> for just opening a device node.
>>
>> Not being able to open a device node a second time makes it impossible to
>> create e.g. monitoring applications that do something when an event happens.
> 
> Agreed.
> 
>>>
>>>> +
>>>> +      <para>It is never possible to start streaming when
>>>> +streaming is already in progress. So &func-ioctl; functions initiating
>>>> +data exchange (e.g. the &VIDIOC-STREAMON; ioctl), and the &func-read;
>>>> +and &func-write; functions can return an &EBUSY;.</para>
>>>
>>> Here, the Overlay is a somewhat an exception, not in the sense that 
>>> they'll call streamon latter, but in the sense that overlay ioctls
>>> can happen after streaming.
>>
>> I'll make a note of that.
>>
>>> I don't remember well how DMA buf works,
>>> but I think you can also start to use a mmaped copy of the dma buffers
>>> after start streaming.
>>
>> Possibly, but that has nothing to do with this paragraph. Once a file
>> handle calls STREAMON, then no other file handle of the same device node
>> can call STREAMON, unless the owner stops streaming and releases all
>> resources (REQBUFS(0)).
> 
> Well, then the paragraph text is not quite right, as it mentions 
> "initiating data exchange".
> 
> If one mmaps memory latter to use it on an already started DMA buffer,
> it is initiating the "memory copy" data exchange with the mmap.
> 
> STREAMON is just one of the ways to initiate a data exchange.

I completely reworked this paragraph.

I'll post the revised version of this patch next.

Regards,

	Hans

Re: [RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Mauro Carvalho Chehab]

Em Fri, 17 Jan 2014 10:24:11 +0100
Hans Verkuil <hverkuil@xs4all.nl> escreveu:

> Hi Mauro,
> 
> On 01/13/2014 06:23 PM, Mauro Carvalho Chehab wrote:
> > Em Mon, 13 Jan 2014 17:15:40 +0100
> > Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> > 
> >> On 01/13/2014 04:20 PM, Mauro Carvalho Chehab wrote:
> >>> Em Tue,  7 Jan 2014 14:06:54 +0100
> >>> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> >>>
> >>>> From: Hans Verkuil <hans.verkuil@cisco.com>
> >>>>
> >>>> This section was horribly out of date. A lot of references to old and
> >>>> obsolete behavior have been dropped.
> > 
> > Forgot to mention, put patches 1 and 2 are ok. I'll review the patches 4-6
> > later this week.
> > 
> >>>>
> >>>> Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
> >>>> ---
> >>>>  Documentation/DocBook/media/v4l/common.xml | 188 ++++++++++-------------------
> >>>>  1 file changed, 67 insertions(+), 121 deletions(-)
> >>>>
> >>>> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
> >>>> index 1ddf354..da08df9 100644
> >>>> --- a/Documentation/DocBook/media/v4l/common.xml
> >>>> +++ b/Documentation/DocBook/media/v4l/common.xml
> 
> <snip>
> 
> >>>> +      <para>Devices can support several functions. For example
> >>>> +video capturing, VBI capturing and radio support.</para>
> >>>
> >>> "function" seems to be a poor choice of word here. Ok, it comes from the
> >>> original text, but it is still not clear.
> >>>
> >>> I would use another word, like "broadcast type", in order to refer to
> >>> radio, software defined radio, VBI and video.
> >>
> >> I agree that it is not the best word, but neither is (IMHO) "broadcast type".
> >> This would be something for a follow-up patch.
> > 
> > I think we should use the right word here on this fix. Other suggestions:
> > 	"stream type", "media type".
> > 
> > In any case, we should enumerate all those types here, maybe even putting
> > them into a table, in order to define precisely to what we're referring to.
> 
> I'm not going to do this now. I need to think about this some more, and this
> might also require changes in a lot of other places in the documentation.
> 
> So as far as I am concerned this is something for a future patch.
> 
> > 
> >>>> +
> >>>> +      <para>The V4L2 API creates different nodes for each of these functions.
> >>>> +One exception to this rule is the overlay function: this is shared
> >>>> +with the video capture node (or video output node for output overlays).</para>
> >>>
> >>> The mention to overlay here is completely out of context, and proofs
> >>> my point that "function" is a very bad choice: overlay is not a
> >>> broadcast type. It is just one of the ways to output the data. The same
> >>> device node can support multiple "delivery types":
> >>> 	- overlay;
> >>> 	- dma-buf;
> >>> 	- mmap;
> >>> 	- read or write.
> >>>
> >>> Let's not mix those two concepts in the new text.
> >>>
> >>> Also, the delivery type has nothing to do with "Opening and closing devices".
> >>
> >> I like the word "delivery type" in this context and I agree with you here.
> >> I'll see if I can improve this text.
> > 
> > Thanks!
> 
> I decided to just drop this paragraph. It doesn't belong here and it doesn't
> add anything useful.
> 
> >  
> >>>
> >>>> +
> >>>> +      <para>The V4L2 API was designed with the idea that one device node could support
> >>>> +all functions. However, in practice this never worked: this 'feature'
> >>>> +was never used by applications and many drivers did not support it and if
> >>>> +they did it was certainly never tested. In addition, switching a device
> >>>> +node between different functions only works when using the streaming I/O
> >>>> +API, not with the read()/write() API.</para>
> >>>> +
> >>>> +      <para>Today each device node supports just one function, with the
> >>>> +exception of overlay support.</para>
> >>>>  
> >>>>        <para>Besides video input or output the hardware may also
> >>>>  support audio sampling or playback. If so, these functions are
> >>>> -implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
> >>>> -audio mixer. The V4L2 API makes no provisions yet to find these
> >>>> -related devices. If you have an idea please write to the linux-media
> >>>> -mailing list: &v4l-ml;.</para>
> >>>> +implemented as ALSA PCM devices with optional ALSA audio mixer
> >>>> +devices.</para>
> >>>> +
> >>>> +      <para>One problem with all these devices is that the V4L2 API
> >>>> +makes no provisions to find these related devices. Some really
> >>>> +complex devices use the Media Controller (see <xref linkend="media_controller" />)
> >>>> +which can be used for this purpose. But most drivers do not use it,
> >>>> +and while some code exists that uses sysfs to discover related devices,
> >>>> +there is no standard library yet. If you want to work on this please write
> >>>> +to the linux-media mailing list: &v4l-ml;.</para>
> >>>
> >>> Not true. It is there at v4l-utils. Ok, patches are always welcome.
> >>
> >> Well, sort of. That library only handles sysfs, not the mc.
> > 
> > Yes, but that covers almost all devices, as the ones that use mc (except for
> > uvc) have more serious issues, as libv4l still don't work with them. So, they
> > demand dedicated applications anyway.
> > 
> >> I know Laurent
> >> has been working on a better replacement, but that's been stalled for ages.
> >> In other words, someone needs to spend time on this and create a proper
> >> library for this.
> > 
> > True, but, again, media controller based devices also need the libv4l
> > pieces that Sakari is working (also stalled).
> > 
> > Let's not mix things: associating media devices via sysfs has already
> > a library. If you want to mention about that, please point to it.
> 
> I clarified the situation and added a pointer to the library in v4l-utils.
> 
> > 
> > A more generic work that will make libv4l and that library to also work
> > with media controllers is a work to be done/finished.
> > 
> >>
> >>>
> >>>>      </section>
> >>>>  
> >>>>      <section>
> >>>> @@ -176,19 +124,22 @@ mailing list: &v4l-ml;.</para>
> >>>>  When this is supported by the driver, users can for example start a
> >>>>  "panel" application to change controls like brightness or audio
> >>>>  volume, while another application captures video and audio. In other words, panel
> >>>> -applications are comparable to an OSS or ALSA audio mixer application.
> >>>> -When a device supports multiple functions like capturing and overlay
> >>>> -<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
> >>>> -use of the device by forked processes or specialized applications.</para>
> >>>> -
> >>>> -      <para>Multiple opens are optional, although drivers should
> >>>> -permit at least concurrent accesses without data exchange, &ie; panel
> >>>> -applications. This implies &func-open; can return an &EBUSY; when the
> >>>> -device is already in use, as well as &func-ioctl; functions initiating
> >>>> -data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
> >>>> -and &func-write; functions.</para>
> >>>> -
> >>>> -      <para>Mere opening a V4L2 device does not grant exclusive
> >>>> +applications are comparable to an ALSA audio mixer application.
> >>>> +Just opening a V4L2 device should not change the state of the device.
> >>>> +Unfortunately, opening a radio device often switches the state of the
> >>>> +device to radio mode in many drivers.</para>
> >>>
> >>> This is an API spec document. It should say what is the expected behavior,
> >>> and not mention non-compliant stuff.
> >>
> >> How about putting this in a footnote? I do agree with you, but the fact is
> >> that most if not all drivers that support both radio and video behave this
> >> way. So one could argue that it is the spec that is non-compliant :-)
> > 
> > If so, let's then fix the API to reflect that opening a radio device will
> > change the behavior.
> 
> I've put this in a footnote together with a mention that this situation needs
> to be fixed.
> 
> >>
> >> That said, at some point this should be fixed.
> > 
> > Yes. one way or the other.
> > 
> >>>
> >>>> +
> >>>> +      <para>Almost all drivers allow multiple opens although there are
> >>>> +still some old drivers that have not been updated to allow this.
> >>>> +This implies &func-open; can return an &EBUSY; when the
> >>>> +device is already in use.</para>
> >>>
> >>> What drivers? We should fix the driver, not the API doc.
> >>
> >> vino.c (I do have fixes for this in an old branch), timblogiw.c, fsl-viu.c.
> >> There are probably a few more. Generally such drivers are old and/or obscure.
> > 
> > Maybe in this specific case, a footnote could be added, although the better
> > would be to simply fix or remove/move to staging those drivers.
> 
> I moved this to a footnote.
> 
> > 
> >> Since I am still working (slowly) on converting drivers to the modern frameworks
> >> I'll come across these eventually.
> >>
> >>> Also, we need more discussions. It could make sense to return EBUSY
> >>> even on new drivers, for example, if they're already in usage by some
> >>> other broadcast type?
> >>
> >> You are not using it until you actually start streaming (or allocating buffers,
> >> or whatever). There is no reason within the current framework to return EBUSY
> >> for just opening a device node.
> >>
> >> Not being able to open a device node a second time makes it impossible to
> >> create e.g. monitoring applications that do something when an event happens.
> > 
> > Agreed.
> > 
> >>>
> >>>> +
> >>>> +      <para>It is never possible to start streaming when
> >>>> +streaming is already in progress. So &func-ioctl; functions initiating
> >>>> +data exchange (e.g. the &VIDIOC-STREAMON; ioctl), and the &func-read;
> >>>> +and &func-write; functions can return an &EBUSY;.</para>
> >>>
> >>> Here, the Overlay is a somewhat an exception, not in the sense that 
> >>> they'll call streamon latter, but in the sense that overlay ioctls
> >>> can happen after streaming.
> >>
> >> I'll make a note of that.
> >>
> >>> I don't remember well how DMA buf works,
> >>> but I think you can also start to use a mmaped copy of the dma buffers
> >>> after start streaming.
> >>
> >> Possibly, but that has nothing to do with this paragraph. Once a file
> >> handle calls STREAMON, then no other file handle of the same device node
> >> can call STREAMON, unless the owner stops streaming and releases all
> >> resources (REQBUFS(0)).
> > 
> > Well, then the paragraph text is not quite right, as it mentions 
> > "initiating data exchange".
> > 
> > If one mmaps memory latter to use it on an already started DMA buffer,
> > it is initiating the "memory copy" data exchange with the mmap.
> > 
> > STREAMON is just one of the ways to initiate a data exchange.
> 
> I completely reworked this paragraph.
> 
> I'll post the revised version of this patch next.

Weird, I'm not seeing the revised version of this patch posted.

Anyway, from your original patch:

> +      <para>Today each device node supports just one function, with the
> +exception of overlay support.</para>

It is still mixing overlay with "function" (where "function" means
VBI, radio, video).

I'll drop this one from the series I'm applying. Please review and submit
latter a new version of this one to the ML for easier review.

> 
> Regards,
> 
> 	Hans
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html


-- 

Cheers,
Mauro

Re: [RFC PATCH 3/6] DocBook media: partial rewrite of "Opening and Closing Devices"

[Hans Verkuil]

On 02/04/14 13:20, Mauro Carvalho Chehab wrote:
> Em Fri, 17 Jan 2014 10:24:11 +0100
> Hans Verkuil <hverkuil@xs4all.nl> escreveu:
> 
>>
>> I'll post the revised version of this patch next.
> 
> Weird, I'm not seeing the revised version of this patch posted.

https://patchwork.linuxtv.org/patch/21620/

> 
> Anyway, from your original patch:
> 
>> +      <para>Today each device node supports just one function, with the
>> +exception of overlay support.</para>
> 
> It is still mixing overlay with "function" (where "function" means
> VBI, radio, video).

Yes, I want to tackle that separately.

> 
> I'll drop this one from the series I'm applying. Please review and submit
> latter a new version of this one to the ML for easier review.

Please just take this as is. The 'function' terminology was there in the
original, so it is not something this patch has introduced. Yes, it should be
changed, but it's something I need to think about some more. This patch may
not solve everything, but at least it greatly improves it.

Regards,

	Hans

[RFC PATCH 4/6] DocBook media: update four more sections

[Hans Verkuil]

From: Hans Verkuil <hans.verkuil@cisco.com>

Updates sections "Querying Capabilities", "Application Priority",
"Video Inputs and Outputs" and "Audio Inputs and Outputs".

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/common.xml | 89 ++++++++++++------------------
 1 file changed, 35 insertions(+), 54 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index da08df9..f1e4307 100644
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -186,15 +186,15 @@ methods</link> supported by the device.</para>
 
     <para>Starting with kernel version 3.1, VIDIOC-QUERYCAP will return the
 V4L2 API version used by the driver, with generally matches the Kernel version.
-There's no need of using &VIDIOC-QUERYCAP; to check if an specific ioctl is
-supported, the V4L2 core now returns ENOIOCTLCMD if a driver doesn't provide
+There's no need of using &VIDIOC-QUERYCAP; to check if a specific ioctl is
+supported, the V4L2 core now returns ENOTTY if a driver doesn't provide
 support for an ioctl.</para>
 
     <para>Other features can be queried
 by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
 to learn about the number, types and names of video connectors on the
 device. Although abstraction is a major objective of this API, the
-ioctl also allows driver specific applications to reliable identify
+&VIDIOC-QUERYCAP; ioctl also allows driver specific applications to reliably identify
 the driver.</para>
 
     <para>All V4L2 drivers must support
@@ -224,9 +224,7 @@ Applications requiring a different priority will usually call
 the &VIDIOC-QUERYCAP; ioctl.</para>
 
     <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
-return an &EBUSY; after another application obtained higher priority.
-An event mechanism to notify applications about asynchronous property
-changes has been proposed but not added yet.</para>
+return an &EBUSY; after another application obtained higher priority.</para>
   </section>
 
   <section id="video">
@@ -234,9 +232,9 @@ changes has been proposed but not added yet.</para>
 
     <para>Video inputs and outputs are physical connectors of a
 device. These can be for example RF connectors (antenna/cable), CVBS
-a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
-capture devices have inputs, output devices have outputs, at least one
-each. Radio devices have no video inputs or outputs.</para>
+a.k.a. Composite Video, S-Video or RGB connectors. Video and VBI
+capture devices have inputs. Video and VBI output devices have outputs,
+at least one each. Radio devices have no video inputs or outputs.</para>
 
     <para>To learn about the number and attributes of the
 available inputs and outputs applications can enumerate them with the
@@ -245,30 +243,13 @@ available inputs and outputs applications can enumerate them with the
 ioctl also contains signal status information applicable when the
 current video input is queried.</para>
 
-    <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
+    <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctls return the
 index of the current video input or output. To select a different
 input or output applications call the &VIDIOC-S-INPUT; and
-&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
+&VIDIOC-S-OUTPUT; ioctls. Drivers must implement all the input ioctls
 when the device has one or more inputs, all the output ioctls when the
 device has one or more outputs.</para>
 
-    <!--
-    <figure id=io-tree>
-      <title>Input and output enumeration is the root of most device properties.</title>
-      <mediaobject>
-	<imageobject>
-	  <imagedata fileref="links.pdf" format="ps" />
-	</imageobject>
-	<imageobject>
-	  <imagedata fileref="links.gif" format="gif" />
-	</imageobject>
-	<textobject>
-	  <phrase>Links between various device property structures.</phrase>
-	</textobject>
-      </mediaobject>
-    </figure>
-    -->
-
     <example>
       <title>Information about the current video input</title>
 
@@ -276,20 +257,20 @@ device has one or more outputs.</para>
 &v4l2-input; input;
 int index;
 
-if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
-	perror ("VIDIOC_G_INPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;index)) {
+	perror("VIDIOC_G_INPUT");
+	exit(EXIT_FAILURE);
 }
 
-memset (&amp;input, 0, sizeof (input));
+memset(&amp;input, 0, sizeof(input));
 input.index = index;
 
-if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
-	perror ("VIDIOC_ENUMINPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
+	perror("VIDIOC_ENUMINPUT");
+	exit(EXIT_FAILURE);
 }
 
-printf ("Current input: %s\n", input.name);
+printf("Current input: %s\n", input.name);
       </programlisting>
     </example>
 
@@ -301,9 +282,9 @@ int index;
 
 index = 0;
 
-if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
-	perror ("VIDIOC_S_INPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-S-INPUT;, &amp;index)) {
+	perror("VIDIOC_S_INPUT");
+	exit(EXIT_FAILURE);
 }
       </programlisting>
     </example>
@@ -343,7 +324,7 @@ available inputs and outputs applications can enumerate them with the
 also contains signal status information applicable when the current
 audio input is queried.</para>
 
-    <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
+    <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctls report
 the current audio input and output, respectively. Note that, unlike
 &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
 as <constant>VIDIOC_ENUMAUDIO</constant> and
@@ -354,11 +335,11 @@ applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
 output (which presently has no changeable properties) applications
 call the &VIDIOC-S-AUDOUT; ioctl.</para>
 
-    <para>Drivers must implement all input ioctls when the device
-has one or more inputs, all output ioctls when the device has one
-or more outputs. When the device has any audio inputs or outputs the
-driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
-&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
+    <para>Drivers must implement all audio input ioctls when the device
+has multiple selectable audio inputs, all audio output ioctls when the
+device has multiple selectable audio outputs. When the device has any
+audio inputs or outputs the driver must set the <constant>V4L2_CAP_AUDIO</constant>
+flag in the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
 
     <example>
       <title>Information about the current audio input</title>
@@ -366,14 +347,14 @@ driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
       <programlisting>
 &v4l2-audio; audio;
 
-memset (&amp;audio, 0, sizeof (audio));
+memset(&amp;audio, 0, sizeof(audio));
 
-if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
-	perror ("VIDIOC_G_AUDIO");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
+	perror("VIDIOC_G_AUDIO");
+	exit(EXIT_FAILURE);
 }
 
-printf ("Current input: %s\n", audio.name);
+printf("Current input: %s\n", audio.name);
       </programlisting>
     </example>
 
@@ -383,13 +364,13 @@ printf ("Current input: %s\n", audio.name);
       <programlisting>
 &v4l2-audio; audio;
 
-memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
+memset(&amp;audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
 
 audio.index = 0;
 
-if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
-	perror ("VIDIOC_S_AUDIO");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
+	perror("VIDIOC_S_AUDIO");
+	exit(EXIT_FAILURE);
 }
       </programlisting>
     </example>
-- 
1.8.5.2

[RFC PATCH 5/6] DocBook media: update three sections

[Hans Verkuil]

From: Hans Verkuil <hans.verkuil@cisco.com>

Updates for the "Tuners and Modulators", "Video Standards" and
"Digital Video (DV) Timings" sections.

Besides lots of trivial little fixes the main changes are:

- Remove two footnotes from "Video Standards": the first is a discussion
  of alternative methods of setting standards, which is pretty pointless
  since the standards API is effectively frozen anyway, and the second
  points to 'rationale' that makes little or no sense to me.

- Clarify a few things in the "Digital Video (DV) Timings" section.
  It was awkwardly formatted as well: there used to be a list with
  multiple bullets that has been reduced to a single item, so drop the
  list and rewrite that text.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 Documentation/DocBook/media/v4l/common.xml | 132 ++++++++++++-----------------
 1 file changed, 53 insertions(+), 79 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index f1e4307..48e8e76 100644
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -395,7 +395,7 @@ the tuner.</para>
 video inputs.</para>
 
       <para>To query and change tuner properties applications use the
-&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
+&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctls, respectively. The
 &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
 contains signal status information applicable when the tuner of the
 current video or radio input is queried. Note that
@@ -460,7 +460,7 @@ standards or variations of standards. Each video input and output may
 support another set of standards. This set is reported by the
 <structfield>std</structfield> field of &v4l2-input; and
 &v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
-&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
+&VIDIOC-ENUMOUTPUT; ioctls, respectively.</para>
 
     <para>V4L2 defines one bit for each analog video standard
 currently in use worldwide, and sets aside bits for driver defined
@@ -491,28 +491,10 @@ automatically.</para>
     <para>To query and select the standard used by the current video
 input or output applications call the &VIDIOC-G-STD; and
 &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
-standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote>
-	<para>An alternative to the current scheme is to use pointers
-to indices as arguments of <constant>VIDIOC_G_STD</constant> and
-<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
-&v4l2-output; <structfield>std</structfield> field would be a set of
-indices like <structfield>audioset</structfield>.</para>
-	<para>Indices are consistent with the rest of the API
-and identify the standard unambiguously. In the present scheme of
-things an enumerated standard is looked up by &v4l2-std-id;. Now the
-standards supported by the inputs of a device can overlap. Just
-assume the tuner and composite input in the example above both
-exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
-a choice which does not exist. We cannot merge or omit sets, because
-applications would be unable to find the standards reported by
-<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
-for each input. Also selecting a standard by &v4l2-std-id; can be
-ambiguous. Advantage of this method is that applications need not
-identify the standard indirectly, after enumerating.</para><para>So in
-summary, the lookup itself is unavoidable. The difference is only
-whether the lookup is necessary to find an enumerated standard or to
-switch to a standard by &v4l2-std-id;.</para>
-      </footnote> Drivers must implement all video standard ioctls
+standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the
+parameter of all these ioctls is a pointer to a &v4l2-std-id; type
+(a standard set), <emphasis>not</emphasis> an index into the standard
+enumeration. Drivers must implement all video standard ioctls
 when the device has one or more video inputs or outputs.</para>
 
     <para>Special rules apply to devices such as USB cameras where the notion of video
@@ -531,17 +513,10 @@ to zero and the <constant>VIDIOC_G_STD</constant>,
 <constant>VIDIOC_S_STD</constant>,
 <constant>VIDIOC_QUERYSTD</constant> and
 <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
-&ENOTTY;.<footnote>
-	<para>See <xref linkend="buffer" /> for a rationale.</para>
+&ENOTTY; or the &EINVAL;.</para>
 	<para>Applications can make use of the <xref linkend="input-capabilities" /> and
 <xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls
-are available for the device.</para>
-
-	<para>See <xref linkend="buffer" /> for a rationale. Probably
-even USB cameras follow some well known video standard. It might have
-been better to explicitly indicate elsewhere if a device cannot live
-up to normal expectations, instead of this exception.</para>
-	    </footnote></para>
+can be used with the given input or output.</para>
 
     <example>
       <title>Information about the current video standard</title>
@@ -550,22 +525,22 @@ up to normal expectations, instead of this exception.</para>
 &v4l2-std-id; std_id;
 &v4l2-standard; standard;
 
-if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
+if (-1 == ioctl(fd, &VIDIOC-G-STD;, &amp;std_id)) {
 	/* Note when VIDIOC_ENUMSTD always returns ENOTTY this
 	   is no video device or it falls under the USB exception,
 	   and VIDIOC_G_STD returning ENOTTY is no error. */
 
-	perror ("VIDIOC_G_STD");
-	exit (EXIT_FAILURE);
+	perror("VIDIOC_G_STD");
+	exit(EXIT_FAILURE);
 }
 
-memset (&amp;standard, 0, sizeof (standard));
+memset(&amp;standard, 0, sizeof(standard));
 standard.index = 0;
 
-while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
+while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
 	if (standard.id &amp; std_id) {
-	       printf ("Current video standard: %s\n", standard.name);
-	       exit (EXIT_SUCCESS);
+	       printf("Current video standard: %s\n", standard.name);
+	       exit(EXIT_SUCCESS);
 	}
 
 	standard.index++;
@@ -575,8 +550,8 @@ while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
    empty unless this device falls under the USB exception. */
 
 if (errno == EINVAL || standard.index == 0) {
-	perror ("VIDIOC_ENUMSTD");
-	exit (EXIT_FAILURE);
+	perror("VIDIOC_ENUMSTD");
+	exit(EXIT_FAILURE);
 }
       </programlisting>
     </example>
@@ -589,26 +564,26 @@ input</title>
 &v4l2-input; input;
 &v4l2-standard; standard;
 
-memset (&amp;input, 0, sizeof (input));
+memset(&amp;input, 0, sizeof(input));
 
-if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
-	perror ("VIDIOC_G_INPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
+	perror("VIDIOC_G_INPUT");
+	exit(EXIT_FAILURE);
 }
 
-if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
-	perror ("VIDIOC_ENUM_INPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
+	perror("VIDIOC_ENUM_INPUT");
+	exit(EXIT_FAILURE);
 }
 
-printf ("Current input %s supports:\n", input.name);
+printf("Current input %s supports:\n", input.name);
 
-memset (&amp;standard, 0, sizeof (standard));
+memset(&amp;standard, 0, sizeof(standard));
 standard.index = 0;
 
-while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
+while (0 == ioctl(fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
 	if (standard.id &amp; input.std)
-		printf ("%s\n", standard.name);
+		printf("%s\n", standard.name);
 
 	standard.index++;
 }
@@ -617,8 +592,8 @@ while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
    empty unless this device falls under the USB exception. */
 
 if (errno != EINVAL || standard.index == 0) {
-	perror ("VIDIOC_ENUMSTD");
-	exit (EXIT_FAILURE);
+	perror("VIDIOC_ENUMSTD");
+	exit(EXIT_FAILURE);
 }
       </programlisting>
     </example>
@@ -630,21 +605,21 @@ if (errno != EINVAL || standard.index == 0) {
 &v4l2-input; input;
 &v4l2-std-id; std_id;
 
-memset (&amp;input, 0, sizeof (input));
+memset(&amp;input, 0, sizeof(input));
 
-if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
-	perror ("VIDIOC_G_INPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
+	perror("VIDIOC_G_INPUT");
+	exit(EXIT_FAILURE);
 }
 
-if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
-	perror ("VIDIOC_ENUM_INPUT");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
+	perror("VIDIOC_ENUM_INPUT");
+	exit(EXIT_FAILURE);
 }
 
 if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
-	fprintf (stderr, "Oops. B/G PAL is not supported.\n");
-	exit (EXIT_FAILURE);
+	fprintf(stderr, "Oops. B/G PAL is not supported.\n");
+	exit(EXIT_FAILURE);
 }
 
 /* Note this is also supposed to work when only B
@@ -652,9 +627,9 @@ if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
 
 std_id = V4L2_STD_PAL_BG;
 
-if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
-	perror ("VIDIOC_S_STD");
-	exit (EXIT_FAILURE);
+if (-1 == ioctl(fd, &VIDIOC-S-STD;, &amp;std_id)) {
+	perror("VIDIOC_S_STD");
+	exit(EXIT_FAILURE);
 }
       </programlisting>
     </example>
@@ -667,26 +642,25 @@ corresponding video timings. Today there are many more different hardware interf
 such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
 video signals and there is a need to extend the API to select the video timings
 for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
-the limited bits available, a new set of IOCTLs was added to set/get video timings at
-the input and output: </para><itemizedlist>
-	<listitem>
-	<para>DV Timings: This will allow applications to define detailed
-video timings for the interface. This includes parameters such as width, height,
-polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
+the limited bits available, a new set of ioctls was added to set/get video timings at
+the input and output.</para>
+
+	<para>These ioctls deal with the detailed digital video timings that define
+each video format. This includes parameters such as the active video width and height,
+signal polarities, frontporches, backporches, sync widths etc. The <filename>linux/v4l2-dv-timings.h</filename>
 header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
 <xref linkend="vesadmt" /> standards.
 	</para>
-	</listitem>
-	</itemizedlist>
-	<para>To enumerate and query the attributes of the DV timings supported by a device,
+
+	<para>To enumerate and query the attributes of the DV timings supported by a device
 	applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
-	To set DV timings for the device, applications use the
+	To set DV timings for the device applications use the
 &VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
 &VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
 use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
 	<para>Applications can make use of the <xref linkend="input-capabilities" /> and
-<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
-video timings for the device.</para>
+<xref linkend="output-capabilities"/> flags to determine whether the digital video ioctls
+can be used with the given input or output.</para>
   </section>
 
   &sub-controls;
-- 
1.8.5.2

[RFC PATCH 6/6] DocBook media: drop the old incorrect packed RGB table.

[Hans Verkuil]

From: Hans Verkuil <hans.verkuil@cisco.com>

The old table is most definitely wrong. All applications and all
drivers that I have ever tested follow the corrected table. Furthermore,
that's what all applications expect as well. Any drivers that do not
follow the corrected table are broken and should be fixed.

This patch drops the old table and replaces it with the corrected
table. This should prevent a lot of confusion.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
---
 .../DocBook/media/v4l/pixfmt-packed-rgb.xml        | 513 ++-------------------
 1 file changed, 49 insertions(+), 464 deletions(-)

diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
index 166c8d6..e1c4f8b 100644
--- a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
@@ -121,14 +121,14 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
 	    <entry>'RGB1'</entry>
 	    <entry></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
 	    <entry>r<subscript>2</subscript></entry>
 	    <entry>r<subscript>1</subscript></entry>
 	    <entry>r<subscript>0</subscript></entry>
+	    <entry>g<subscript>2</subscript></entry>
+	    <entry>g<subscript>1</subscript></entry>
+	    <entry>g<subscript>0</subscript></entry>
+	    <entry>b<subscript>1</subscript></entry>
+	    <entry>b<subscript>0</subscript></entry>
 	  </row>
 	  <row id="V4L2-PIX-FMT-RGB444">
 	    <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
@@ -159,18 +159,18 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry>g<subscript>2</subscript></entry>
 	    <entry>g<subscript>1</subscript></entry>
 	    <entry>g<subscript>0</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>a</entry>
 	    <entry>b<subscript>4</subscript></entry>
 	    <entry>b<subscript>3</subscript></entry>
 	    <entry>b<subscript>2</subscript></entry>
 	    <entry>b<subscript>1</subscript></entry>
 	    <entry>b<subscript>0</subscript></entry>
+	    <entry></entry>
+	    <entry>a</entry>
+	    <entry>r<subscript>4</subscript></entry>
+	    <entry>r<subscript>3</subscript></entry>
+	    <entry>r<subscript>2</subscript></entry>
+	    <entry>r<subscript>1</subscript></entry>
+	    <entry>r<subscript>0</subscript></entry>
 	    <entry>g<subscript>4</subscript></entry>
 	    <entry>g<subscript>3</subscript></entry>
 	  </row>
@@ -181,17 +181,17 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry>g<subscript>2</subscript></entry>
 	    <entry>g<subscript>1</subscript></entry>
 	    <entry>g<subscript>0</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry></entry>
 	    <entry>b<subscript>4</subscript></entry>
 	    <entry>b<subscript>3</subscript></entry>
 	    <entry>b<subscript>2</subscript></entry>
 	    <entry>b<subscript>1</subscript></entry>
 	    <entry>b<subscript>0</subscript></entry>
+	    <entry></entry>
+	    <entry>r<subscript>4</subscript></entry>
+	    <entry>r<subscript>3</subscript></entry>
+	    <entry>r<subscript>2</subscript></entry>
+	    <entry>r<subscript>1</subscript></entry>
+	    <entry>r<subscript>0</subscript></entry>
 	    <entry>g<subscript>5</subscript></entry>
 	    <entry>g<subscript>4</subscript></entry>
 	    <entry>g<subscript>3</subscript></entry>
@@ -201,32 +201,32 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry>'RGBQ'</entry>
 	    <entry></entry>
 	    <entry>a</entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
 	    <entry>r<subscript>4</subscript></entry>
 	    <entry>r<subscript>3</subscript></entry>
 	    <entry>r<subscript>2</subscript></entry>
 	    <entry>r<subscript>1</subscript></entry>
 	    <entry>r<subscript>0</subscript></entry>
-	  </row>
-	  <row id="V4L2-PIX-FMT-RGB565X">
-	    <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
-	    <entry>'RGBR'</entry>
+	    <entry>g<subscript>4</subscript></entry>
+	    <entry>g<subscript>3</subscript></entry>
 	    <entry></entry>
+	    <entry>g<subscript>2</subscript></entry>
+	    <entry>g<subscript>1</subscript></entry>
+	    <entry>g<subscript>0</subscript></entry>
 	    <entry>b<subscript>4</subscript></entry>
 	    <entry>b<subscript>3</subscript></entry>
 	    <entry>b<subscript>2</subscript></entry>
 	    <entry>b<subscript>1</subscript></entry>
 	    <entry>b<subscript>0</subscript></entry>
+	  </row>
+	  <row id="V4L2-PIX-FMT-RGB565X">
+	    <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
+	    <entry>'RGBR'</entry>
+	    <entry></entry>
+	    <entry>r<subscript>4</subscript></entry>
+	    <entry>r<subscript>3</subscript></entry>
+	    <entry>r<subscript>2</subscript></entry>
+	    <entry>r<subscript>1</subscript></entry>
+	    <entry>r<subscript>0</subscript></entry>
 	    <entry>g<subscript>5</subscript></entry>
 	    <entry>g<subscript>4</subscript></entry>
 	    <entry>g<subscript>3</subscript></entry>
@@ -234,11 +234,11 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry>g<subscript>2</subscript></entry>
 	    <entry>g<subscript>1</subscript></entry>
 	    <entry>g<subscript>0</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
+	    <entry>b<subscript>4</subscript></entry>
+	    <entry>b<subscript>3</subscript></entry>
+	    <entry>b<subscript>2</subscript></entry>
+	    <entry>b<subscript>1</subscript></entry>
+	    <entry>b<subscript>0</subscript></entry>
 	  </row>
 	  <row id="V4L2-PIX-FMT-BGR666">
 	    <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
@@ -385,6 +385,15 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
 	    <entry>'RGB4'</entry>
 	    <entry></entry>
+	    <entry>a<subscript>7</subscript></entry>
+	    <entry>a<subscript>6</subscript></entry>
+	    <entry>a<subscript>5</subscript></entry>
+	    <entry>a<subscript>4</subscript></entry>
+	    <entry>a<subscript>3</subscript></entry>
+	    <entry>a<subscript>2</subscript></entry>
+	    <entry>a<subscript>1</subscript></entry>
+	    <entry>a<subscript>0</subscript></entry>
+	    <entry></entry>
 	    <entry>r<subscript>7</subscript></entry>
 	    <entry>r<subscript>6</subscript></entry>
 	    <entry>r<subscript>5</subscript></entry>
@@ -411,25 +420,16 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
 	    <entry>b<subscript>2</subscript></entry>
 	    <entry>b<subscript>1</subscript></entry>
 	    <entry>b<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>a<subscript>7</subscript></entry>
-	    <entry>a<subscript>6</subscript></entry>
-	    <entry>a<subscript>5</subscript></entry>
-	    <entry>a<subscript>4</subscript></entry>
-	    <entry>a<subscript>3</subscript></entry>
-	    <entry>a<subscript>2</subscript></entry>
-	    <entry>a<subscript>1</subscript></entry>
-	    <entry>a<subscript>0</subscript></entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>
 
-    <para>Bit 7 is the most significant bit. The value of a = alpha
+    <para>Bit 7 is the most significant bit. The value of the a = alpha
 bits is undefined when reading from the driver, ignored when writing
 to the driver, except when alpha blending has been negotiated for a
 <link linkend="overlay">Video Overlay</link> or <link linkend="osd">
-Video Output Overlay</link> or when alpha component has been configured
+Video Output Overlay</link> or when the alpha component has been configured
 for a <link linkend="capture">Video Capture</link> by means of <link
 linkend="v4l2-alpha-component"> <constant>V4L2_CID_ALPHA_COMPONENT
 </constant> </link> control.</para>
@@ -512,421 +512,6 @@ image</title>
       </formalpara>
     </example>
 
-    <important>
-      <para>Drivers may interpret these formats differently.</para>
-    </important>
-
-    <para>Some RGB formats above are uncommon and were probably
-defined in error. Drivers may interpret them as in <xref
-	linkend="rgb-formats-corrected" />.</para>
-
-    <table pgwide="1" frame="none" id="rgb-formats-corrected">
-      <title>Packed RGB Image Formats (corrected)</title>
-      <tgroup cols="37" align="center">
-	<colspec colname="id" align="left" />
-	<colspec colname="fourcc" />
-	<colspec colname="bit" />
-
-	<colspec colnum="4" colname="b07" align="center" />
-	<colspec colnum="5" colname="b06" align="center" />
-	<colspec colnum="6" colname="b05" align="center" />
-	<colspec colnum="7" colname="b04" align="center" />
-	<colspec colnum="8" colname="b03" align="center" />
-	<colspec colnum="9" colname="b02" align="center" />
-	<colspec colnum="10" colname="b01" align="center" />
-	<colspec colnum="11" colname="b00" align="center" />
-
-	<colspec colnum="13" colname="b17" align="center" />
-	<colspec colnum="14" colname="b16" align="center" />
-	<colspec colnum="15" colname="b15" align="center" />
-	<colspec colnum="16" colname="b14" align="center" />
-	<colspec colnum="17" colname="b13" align="center" />
-	<colspec colnum="18" colname="b12" align="center" />
-	<colspec colnum="19" colname="b11" align="center" />
-	<colspec colnum="20" colname="b10" align="center" />
-
-	<colspec colnum="22" colname="b27" align="center" />
-	<colspec colnum="23" colname="b26" align="center" />
-	<colspec colnum="24" colname="b25" align="center" />
-	<colspec colnum="25" colname="b24" align="center" />
-	<colspec colnum="26" colname="b23" align="center" />
-	<colspec colnum="27" colname="b22" align="center" />
-	<colspec colnum="28" colname="b21" align="center" />
-	<colspec colnum="29" colname="b20" align="center" />
-
-	<colspec colnum="31" colname="b37" align="center" />
-	<colspec colnum="32" colname="b36" align="center" />
-	<colspec colnum="33" colname="b35" align="center" />
-	<colspec colnum="34" colname="b34" align="center" />
-	<colspec colnum="35" colname="b33" align="center" />
-	<colspec colnum="36" colname="b32" align="center" />
-	<colspec colnum="37" colname="b31" align="center" />
-	<colspec colnum="38" colname="b30" align="center" />
-
-	<spanspec namest="b07" nameend="b00" spanname="b0" />
-	<spanspec namest="b17" nameend="b10" spanname="b1" />
-	<spanspec namest="b27" nameend="b20" spanname="b2" />
-	<spanspec namest="b37" nameend="b30" spanname="b3" />
-	<thead>
-	  <row>
-	    <entry>Identifier</entry>
-	    <entry>Code</entry>
-	    <entry>&nbsp;</entry>
-	    <entry spanname="b0">Byte&nbsp;0 in memory</entry>
-	    <entry spanname="b1">Byte&nbsp;1</entry>
-	    <entry spanname="b2">Byte&nbsp;2</entry>
-	    <entry spanname="b3">Byte&nbsp;3</entry>
-	  </row>
-	  <row>
-	    <entry>&nbsp;</entry>
-	    <entry>&nbsp;</entry>
-	    <entry>Bit</entry>
-	    <entry>7</entry>
-	    <entry>6</entry>
-	    <entry>5</entry>
-	    <entry>4</entry>
-	    <entry>3</entry>
-	    <entry>2</entry>
-	    <entry>1</entry>
-	    <entry>0</entry>
-	    <entry>&nbsp;</entry>
-	    <entry>7</entry>
-	    <entry>6</entry>
-	    <entry>5</entry>
-	    <entry>4</entry>
-	    <entry>3</entry>
-	    <entry>2</entry>
-	    <entry>1</entry>
-	    <entry>0</entry>
-	    <entry>&nbsp;</entry>
-	    <entry>7</entry>
-	    <entry>6</entry>
-	    <entry>5</entry>
-	    <entry>4</entry>
-	    <entry>3</entry>
-	    <entry>2</entry>
-	    <entry>1</entry>
-	    <entry>0</entry>
-	    <entry>&nbsp;</entry>
-	    <entry>7</entry>
-	    <entry>6</entry>
-	    <entry>5</entry>
-	    <entry>4</entry>
-	    <entry>3</entry>
-	    <entry>2</entry>
-	    <entry>1</entry>
-	    <entry>0</entry>
-	  </row>
-	</thead>
-	<tbody valign="top">
-	  <row><!-- id="V4L2-PIX-FMT-RGB332" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
-	    <entry>'RGB1'</entry>
-	    <entry></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB444" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
-	    <entry>'R444'</entry>
-	    <entry></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>a<subscript>3</subscript></entry>
-	    <entry>a<subscript>2</subscript></entry>
-	    <entry>a<subscript>1</subscript></entry>
-	    <entry>a<subscript>0</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB555" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
-	    <entry>'RGBO'</entry>
-	    <entry></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>a</entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB565" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
-	    <entry>'RGBP'</entry>
-	    <entry></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB555X" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
-	    <entry>'RGBQ'</entry>
-	    <entry></entry>
-	    <entry>a</entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB565X" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
-	    <entry>'RGBR'</entry>
-	    <entry></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-BGR666" -->
-	    <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
-	    <entry>'BGRH'</entry>
-	    <entry></entry>
-	    <entry>b<subscript>5</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry>r<subscript>5</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	    <entry></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-BGR24" -->
-	    <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
-	    <entry>'BGR3'</entry>
-	    <entry></entry>
-	    <entry>b<subscript>7</subscript></entry>
-	    <entry>b<subscript>6</subscript></entry>
-	    <entry>b<subscript>5</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>7</subscript></entry>
-	    <entry>g<subscript>6</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>r<subscript>7</subscript></entry>
-	    <entry>r<subscript>6</subscript></entry>
-	    <entry>r<subscript>5</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB24" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
-	    <entry>'RGB3'</entry>
-	    <entry></entry>
-	    <entry>r<subscript>7</subscript></entry>
-	    <entry>r<subscript>6</subscript></entry>
-	    <entry>r<subscript>5</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>7</subscript></entry>
-	    <entry>g<subscript>6</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>b<subscript>7</subscript></entry>
-	    <entry>b<subscript>6</subscript></entry>
-	    <entry>b<subscript>5</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-BGR32" -->
-	    <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
-	    <entry>'BGR4'</entry>
-	    <entry></entry>
-	    <entry>b<subscript>7</subscript></entry>
-	    <entry>b<subscript>6</subscript></entry>
-	    <entry>b<subscript>5</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>7</subscript></entry>
-	    <entry>g<subscript>6</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>r<subscript>7</subscript></entry>
-	    <entry>r<subscript>6</subscript></entry>
-	    <entry>r<subscript>5</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>a<subscript>7</subscript></entry>
-	    <entry>a<subscript>6</subscript></entry>
-	    <entry>a<subscript>5</subscript></entry>
-	    <entry>a<subscript>4</subscript></entry>
-	    <entry>a<subscript>3</subscript></entry>
-	    <entry>a<subscript>2</subscript></entry>
-	    <entry>a<subscript>1</subscript></entry>
-	    <entry>a<subscript>0</subscript></entry>
-	  </row>
-	  <row><!-- id="V4L2-PIX-FMT-RGB32" -->
-	    <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
-	    <entry>'RGB4'</entry>
-	    <entry></entry>
-	    <entry>a<subscript>7</subscript></entry>
-	    <entry>a<subscript>6</subscript></entry>
-	    <entry>a<subscript>5</subscript></entry>
-	    <entry>a<subscript>4</subscript></entry>
-	    <entry>a<subscript>3</subscript></entry>
-	    <entry>a<subscript>2</subscript></entry>
-	    <entry>a<subscript>1</subscript></entry>
-	    <entry>a<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>r<subscript>7</subscript></entry>
-	    <entry>r<subscript>6</subscript></entry>
-	    <entry>r<subscript>5</subscript></entry>
-	    <entry>r<subscript>4</subscript></entry>
-	    <entry>r<subscript>3</subscript></entry>
-	    <entry>r<subscript>2</subscript></entry>
-	    <entry>r<subscript>1</subscript></entry>
-	    <entry>r<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>g<subscript>7</subscript></entry>
-	    <entry>g<subscript>6</subscript></entry>
-	    <entry>g<subscript>5</subscript></entry>
-	    <entry>g<subscript>4</subscript></entry>
-	    <entry>g<subscript>3</subscript></entry>
-	    <entry>g<subscript>2</subscript></entry>
-	    <entry>g<subscript>1</subscript></entry>
-	    <entry>g<subscript>0</subscript></entry>
-	    <entry></entry>
-	    <entry>b<subscript>7</subscript></entry>
-	    <entry>b<subscript>6</subscript></entry>
-	    <entry>b<subscript>5</subscript></entry>
-	    <entry>b<subscript>4</subscript></entry>
-	    <entry>b<subscript>3</subscript></entry>
-	    <entry>b<subscript>2</subscript></entry>
-	    <entry>b<subscript>1</subscript></entry>
-	    <entry>b<subscript>0</subscript></entry>
-	  </row>
-	</tbody>
-      </tgroup>
-    </table>
-
     <para>A test utility to determine which RGB formats a driver
 actually supports is available from the LinuxTV v4l-dvb repository.
 See &v4l-dvb; for access instructions.</para>
-- 
1.8.5.2