v4l2-spec: finalize the RDS specification.

From: Hans Verkuil <hverkuil@xs4all.nl>

Priority: normal

Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>

1 files changed, 145 insertions, 29 deletions

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: