summaryrefslogtreecommitdiff
path: root/v4l2-spec
diff options
context:
space:
mode:
Diffstat (limited to 'v4l2-spec')
-rw-r--r--v4l2-spec/biblio.sgml65
-rw-r--r--v4l2-spec/compat.sgml14
-rw-r--r--v4l2-spec/dev-rds.sgml174
-rw-r--r--v4l2-spec/v4l2.sgml7
-rw-r--r--v4l2-spec/vidioc-g-tuner.sgml17
-rw-r--r--v4l2-spec/vidioc-querycap.sgml2
6 files changed, 195 insertions, 84 deletions
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
@@ -131,6 +131,13 @@ structs, ioctls) must be noted in more detail in the history chapter
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>
<authorinitials>hv</authorinitials>
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>