From 84e800a7ca6664a01b8b294b4acd673019c0a2a9 Mon Sep 17 00:00:00 2001
From: Hans Verkuil <hverkuil@xs4all.nl>
Date: Sat, 20 Jun 2009 10:49:43 +0200
Subject: v4l2-spec: finalize the RDS specification.

From: Hans Verkuil <hverkuil@xs4all.nl>

Priority: normal

Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
---
 v4l2-spec/biblio.sgml          |  65 ++++-----------
 v4l2-spec/compat.sgml          |  14 +++-
 v4l2-spec/dev-rds.sgml         | 174 ++++++++++++++++++++++++++++++++++-------
 v4l2-spec/v4l2.sgml            |   7 ++
 v4l2-spec/vidioc-g-tuner.sgml  |  17 +++-
 v4l2-spec/vidioc-querycap.sgml |   2 +-
 6 files changed, 195 insertions(+), 84 deletions(-)

(limited to 'v4l2-spec')

diff --git a/v4l2-spec/biblio.sgml b/v4l2-spec/biblio.sgml
index b013ece1d..afc8a0dd2 100644
--- a/v4l2-spec/biblio.sgml
+++ b/v4l2-spec/biblio.sgml
@@ -158,54 +158,23 @@ Signal - NTSC for Studio Applications"</title>
 1125-Line High-Definition Production"</title>
     </biblioentry>
 
-    <biblioentry id="v4l">
-      <abbrev>V4L</abbrev>
-      <authorgroup>
-	<author>
-	  <firstname>Alan</firstname>
-	  <surname>Cox</surname>
-	  <affiliation>
-	    <orgname>Red Hat, Inc.</orgname>
-	    <address>
-	      <email>alan@redhat.com</email>
-	    </address>
-	  </affiliation>
-	</author>
-      </authorgroup>
-      <title>Video4Linux API Specification</title>
-      <abstract>
-	<para>This file is part of the Linux kernel sources under
-<filename>Documentation/video4linux</filename>.</para>
-      </abstract>
-    </biblioentry>
-
-    <biblioentry id="v4lprog">
-      <abbrev>V4LPROG</abbrev>
-      <authorgroup>
-	<author>
-	  <firstname>Alan</firstname>
-	  <surname>Cox</surname>
-	  <affiliation>
-	    <orgname>Red Hat, Inc.</orgname>
-	    <address>
-	      <email>alan@redhat.com</email>
-	    </address>
-	  </affiliation>
-	</author>
-      </authorgroup>
-      <title>Video4Linux Programming (a.k.a. The Video4Linux
-Book)</title>
-      <abstract>
-	<para>About V4L <emphasis>driver</emphasis> programming. This
-book is part of the Linux kernel DocBook documentation, for example at
-<ulink url="http://kernelnewbies.org/documents/">
-http://kernelnewbies.org/documents/</ulink>. SGML sources are included
-in the kernel sources.</para>
-      </abstract>
-      <copyright>
-	<year>2000</year>
-	<holder>Alan Cox</holder>
-      </copyright>
+    <biblioentry id="en50067">
+      <abbrev>EN&nbsp;50067</abbrev>
+      <authorgroup>
+	<corpauthor>European Committee for Electrotechnical Standardization
+(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor>
+      </authorgroup>
+      <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting
+in the frequency range from 87,5 to 108,0 MHz</title>
+    </biblioentry>
+
+    <biblioentry id="nrsc4">
+      <abbrev>NRSC-4</abbrev>
+      <authorgroup>
+	<corpauthor>National Radio Systems Committee
+(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor>
+      </authorgroup>
+      <title>NTSC-4: United States RBDS Standard</title>
     </biblioentry>
 
   </bibliography>
diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml
index 94713023d..c1c725f35 100644
--- a/v4l2-spec/compat.sgml
+++ b/v4l2-spec/compat.sgml
@@ -1273,9 +1273,8 @@ also the size of the structure changed, which is encoded in the ioctl
 request code, thus older V4L2 devices will respond with an &EINVAL; to
 the new &VIDIOC-QUERYCAP; ioctl.</para>
 
-	  <para>There are new fields to identify the driver, a new (as
-of yet unspecified) device function
-<constant>V4L2_CAP_RDS_CAPTURE</constant>, the
+	  <para>There are new fields to identify the driver, a new RDS
+device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
 <constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
 any audio connectors, another I/O capability
 <constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
@@ -2294,6 +2293,15 @@ was renamed to <structname id=v4l2-chip-ident-old>v4l2_chip_ident_old</structnam
 	</listitem>
        </orderedlist>
      </section>
+    <section>
+      <title>V4L2 in Linux 2.6.32</title>
+      <orderedlist>
+	<listitem>
+	  <para>Finalized the RDS capture API. See <xref linkend="rds"> for
+more information.</para>
+	</listitem>
+       </orderedlist>
+     </section>
    </section>
 
    <section id="other">
diff --git a/v4l2-spec/dev-rds.sgml b/v4l2-spec/dev-rds.sgml
index 07bfd4c65..8f357d9f0 100644
--- a/v4l2-spec/dev-rds.sgml
+++ b/v4l2-spec/dev-rds.sgml
@@ -2,38 +2,154 @@
 
       <para>The Radio Data System transmits supplementary
 information in binary format, for example the station name or travel
-information, on a inaudible audio subcarrier of a radio program. This
-interface aims at devices capable of receiving and decoding RDS
+information, on an inaudible audio subcarrier of a radio program. This
+interface is aimed at devices capable of receiving and decoding RDS
 information.</para>
 
-      <para>The V4L API defines its RDS API as follows.</para>
-
-      <para>From radio devices supporting it, RDS data can be read
-with the &func-read; function. The data is packed in groups of three,
-as follows:<orderedlist>
-      <listitem>
-	<para>First Octet Least Significant Byte of RDS Block</para>
-      </listitem>
-      <listitem>
-	<para>Second Octet Most Significant Byte of RDS Block</para>
-      </listitem>
-      <listitem>
-	<para>Third Octet Bit 7: Error bit. Indicates that an
-uncorrectable error occurred during reception of this block. Bit 6:
-Corrected bit. Indicates that an error was corrected for this data
-block. Bits 5-3: Received Offset. Indicates the offset received by the
-sync system. Bits 2-0: Offset Name. Indicates the offset applied to
-this data.</para>
-      </listitem>
-	</orderedlist></para>
-
-      <para>It was argued <!-- video4linux-list@redhat.com
-on 12 Nov 2002, subject "RDS/RBDS" --> the RDS API should be
-extended before integration into V4L2, no new API has been devised yet.
-Please write to the linux-media mailing list for discussion: &v4l-ml;.
-Meanwhile no V4L2 driver should set the
-<constant>V4L2_CAP_RDS_CAPTURE</constant> capability flag.</para>
+      <para>For more information see the core RDS standard <xref linkend="en50067">
+and the RBDS standard <xref linkend="nrsc4">.</para>
 
+      <para>Note that the RBDS standard as is used in the USA is almost identical
+to the RDS standard. Any RDS decoder can also handle RBDS. Only some of the fields
+have slightly different meanings. See the RBDS standard for more information.</para>
+
+      <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
+This is a proprietary format which seems to be discontinued. The RDS interface does not
+support this format. Should support for MMBS (or the so-called 'E blocks' in general)
+be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
+
+  <section>
+    <title>Querying Capabilities</title>
+
+    <para>Devices supporting the RDS capturing API
+set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
+the <structfield>capabilities</structfield> field of &v4l2-capability;
+returned by the &VIDIOC-QUERYCAP; ioctl.</para>
+
+    <para>Any tuner that supports RDS will set the
+<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
+field of &v4l2-tuner;.</para>
+
+    <para>Whether an RDS signal is present can be detected by looking at
+the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the
+<constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para>
+
+  </section>
+
+  <section>
+    <title>Reading RDS data</title>
+
+      <para>RDS data can be read from the radio device
+with the &func-read; function. The data is packed in groups of three bytes,
+as follows:</para>
+    <table frame="none" pgwide="1" id="v4l2-rds-data">
+      <title>struct
+<structname>v4l2_rds_data</structname></title>
+      <tgroup cols="3">
+	<colspec colname="c1" colwidth="1*">
+	<colspec colname="c2" colwidth="1*">
+	<colspec colname="c3" colwidth="5*">
+	<tbody valign="top">
+	  <row>
+	    <entry>__u8</entry>
+	    <entry><structfield>lsb</structfield></entry>
+	    <entry>Least Significant Byte of RDS Block</entry>
+	  </row>
+	  <row>
+	    <entry>__u8</entry>
+	    <entry><structfield>msb</structfield></entry>
+	    <entry>Most Significant Byte of RDS Block</entry>
+	  </row>
+	  <row>
+	    <entry>__u8</entry>
+	    <entry><structfield>block</structfield></entry>
+	    <entry>Block description</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+    <table frame="none" pgwide="1" id="v4l2-rds-block">
+      <title>Block description</title>
+      <tgroup cols="2">
+	<colspec colname="c1" colwidth="1*">
+	<colspec colname="c2" colwidth="5*">
+	<tbody valign="top">
+	  <row>
+	    <entry>Bits 0-2</entry>
+	    <entry>Block (aka offset) of the received data.</entry>
+	  </row>
+	  <row>
+	    <entry>Bits 3-5</entry>
+	    <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
+	  </row>
+	  <row>
+	    <entry>Bit 6</entry>
+	    <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
+	  </row>
+	  <row>
+	    <entry>Bit 7</entry>
+	    <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+
+    <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
+      <title>Block defines</title>
+      <tgroup cols="3">
+	<colspec colname="c1" colwidth="1*">
+	<colspec colname="c2" colwidth="1*">
+	<colspec colname="c3" colwidth="5*">
+	<tbody valign="top">
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_MSK</entry>
+	    <entry>7</entry>
+	    <entry>Mask for bits 0-2 to get the block ID.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_A</entry>
+	    <entry>0</entry>
+	    <entry>Block A.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_B</entry>
+	    <entry>1</entry>
+	    <entry>Block B.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_C</entry>
+	    <entry>2</entry>
+	    <entry>Block C.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_D</entry>
+	    <entry>3</entry>
+	    <entry>Block D.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_C_ALT</entry>
+	    <entry>4</entry>
+	    <entry>Block C'.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_INVALID</entry>
+	    <entry>7</entry>
+	    <entry>An invalid block.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
+	    <entry>0x40</entry>
+	    <entry>A bit error was detected but corrected.</entry>
+	  </row>
+	  <row>
+	    <entry>V4L2_RDS_BLOCK_ERROR</entry>
+	    <entry>0x80</entry>
+	    <entry>An incorrectable error occurred.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </section>
 
 <!--
 Local Variables:
diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml
index 470793d29..815e96ab5 100644
--- a/v4l2-spec/v4l2.sgml
+++ b/v4l2-spec/v4l2.sgml
@@ -130,6 +130,13 @@ structs, ioctls) must be noted in more detail in the history chapter
 (compat.sgml), along with the possible impact on existing drivers and
 applications. -->
 
+      <revision>
+	<revnumber>0.26</revnumber>
+	<date>2009-06-15</date>
+	<authorinitials>hv</authorinitials>
+	<revremark>Finalized the RDS capture API.</revremark>
+      </revision>
+
       <revision>
 	<revnumber>0.25</revnumber>
 	<date>2009-01-18</date>
diff --git a/v4l2-spec/vidioc-g-tuner.sgml b/v4l2-spec/vidioc-g-tuner.sgml
index d5d379838..eb0b89e9a 100644
--- a/v4l2-spec/vidioc-g-tuner.sgml
+++ b/v4l2-spec/vidioc-g-tuner.sgml
@@ -120,9 +120,9 @@ field is not quite clear.--></para></entry>
 to decode audio subprograms. They will <emphasis>not</emphasis>
 change, for example with the current video standard.</para><para>When
 the structure refers to a radio tuner only the
-<constant>V4L2_TUNER_CAP_LOW</constant> and
-<constant>V4L2_TUNER_CAP_STEREO</constant> flags can be
-set.</para></entry>
+<constant>V4L2_TUNER_CAP_LOW</constant>,
+<constant>V4L2_TUNER_CAP_STEREO</constant> and
+<constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
@@ -312,6 +312,12 @@ carrier for a monaural secondary language. Only
 supports the <constant>V4L2_STD_NTSC_M</constant> video
 standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry>
 	  </row>
+	  <row>
+	<entry><constant>V4L2_TUNER_CAP_RDS</constant></entry>
+	<entry>0x0080</entry>
+	<entry>RDS capture is supported. This capability is only valid for
+radio tuners.</entry>
+	  </row>
 	</tbody>
       </tgroup>
     </table>
@@ -353,6 +359,11 @@ bilingual audio signal (or a second audio program).</entry>
 <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
 current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
 	  </row>
+	  <row>
+	    <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
+	    <entry>0x0010</entry>
+	    <entry>The tuner receives an RDS channel.</entry>
+	  </row>
 	</tbody>
       </tgroup>
     </table>
diff --git a/v4l2-spec/vidioc-querycap.sgml b/v4l2-spec/vidioc-querycap.sgml
index 2715289d8..4a741f5e9 100644
--- a/v4l2-spec/vidioc-querycap.sgml
+++ b/v4l2-spec/vidioc-querycap.sgml
@@ -184,7 +184,7 @@ data.</entry>
 	  <row>
 	    <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry>
 	    <entry>0x00000100</entry>
-	    <entry>[to be defined]</entry>
+	    <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry>
-- 
cgit v1.2.3