Documentation/DocBook/v4l/dev-rds.xml

   1      <title>RDS Interface</title>
   2
   3       <para>The Radio Data System transmits supplementary
   4 information in binary format, for example the station name or travel
   5 information, on an inaudible audio subcarrier of a radio program. This
   6 interface is aimed at devices capable of receiving and/or transmitting RDS
   7 information.</para>
   8
   9       <para>For more information see the core RDS standard <xref linkend="en50067" />
  10 and the RBDS standard <xref linkend="nrsc4" />.</para>
  11
  12       <para>Note that the RBDS standard as is used in the USA is almost identical
  13 to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the
  14 fields have slightly different meanings. See the RBDS standard for more
  15 information.</para>
  16
  17       <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
  18 This is a proprietary format which seems to be discontinued. The RDS interface does not
  19 support this format. Should support for MMBS (or the so-called 'E blocks' in general)
  20 be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
  21
  22   <section>
  23     <title>Querying Capabilities</title>
  24
  25     <para>Devices supporting the RDS capturing API set
  26 the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
  27 the <structfield>capabilities</structfield> field of &v4l2-capability;
  28 returned by the &VIDIOC-QUERYCAP; ioctl.  Any tuner that supports RDS
  29 will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in
  30 the <structfield>capability</structfield> field of &v4l2-tuner;.  If
  31 the driver only passes RDS blocks without interpreting the data
  32 the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be
  33 set, see <link linkend="reading-rds-data">Reading RDS data</link>.
  34 For future use the
  35 flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> has also been
  36 defined. However, a driver for a radio tuner with this capability does
  37 not yet exist, so if you are planning to write such a driver you
  38 should discuss this on the linux-media mailing list: &v4l-ml;.</para>
  39
  40     <para> Whether an RDS signal is present can be detected by looking
  41 at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;:
  42 the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data
  43 was detected.</para>
  44
  45     <para>Devices supporting the RDS output API
  46 set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
  47 the <structfield>capabilities</structfield> field of &v4l2-capability;
  48 returned by the &VIDIOC-QUERYCAP; ioctl.
  49 Any modulator that supports RDS will set the
  50 <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
  51 field of &v4l2-modulator;.
  52 In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
  53 bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.
  54 If the driver only passes RDS blocks without interpreting the data
  55 the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be set. If the
  56 tuner is capable of handling RDS entities like program identification codes and radio
  57 text, the flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> should be set,
  58 see <link linkend="writing-rds-data">Writing RDS data</link> and
  59 <link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para>
  60   </section>
  61
  62   <section  id="reading-rds-data">
  63     <title>Reading RDS data</title>
  64
  65       <para>RDS data can be read from the radio device
  66 with the &func-read; function. The data is packed in groups of three bytes.</para>
  67   </section>
  68
  69   <section  id="writing-rds-data">
  70     <title>Writing RDS data</title>
  71
  72       <para>RDS data can be written to the radio device
  73 with the &func-write; function. The data is packed in groups of three bytes,
  74 as follows:</para>
  75   </section>
  76
  77   <section>
  78     <table frame="none" pgwide="1" id="v4l2-rds-data">
  79       <title>struct
  80 <structname>v4l2_rds_data</structname></title>
  81       <tgroup cols="3">
  82         <colspec colname="c1" colwidth="1*" />
  83         <colspec colname="c2" colwidth="1*" />
  84         <colspec colname="c3" colwidth="5*" />
  85         <tbody valign="top">
  86           <row>
  87             <entry>__u8</entry>
  88             <entry><structfield>lsb</structfield></entry>
  89             <entry>Least Significant Byte of RDS Block</entry>
  90           </row>
  91           <row>
  92             <entry>__u8</entry>
  93             <entry><structfield>msb</structfield></entry>
  94             <entry>Most Significant Byte of RDS Block</entry>
  95           </row>
  96           <row>
  97             <entry>__u8</entry>
  98             <entry><structfield>block</structfield></entry>
  99             <entry>Block description</entry>
 100           </row>
 101         </tbody>
 102       </tgroup>
 103     </table>
 104     <table frame="none" pgwide="1" id="v4l2-rds-block">
 105       <title>Block description</title>
 106       <tgroup cols="2">
 107         <colspec colname="c1" colwidth="1*" />
 108         <colspec colname="c2" colwidth="5*" />
 109         <tbody valign="top">
 110           <row>
 111             <entry>Bits 0-2</entry>
 112             <entry>Block (aka offset) of the received data.</entry>
 113           </row>
 114           <row>
 115             <entry>Bits 3-5</entry>
 116             <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
 117           </row>
 118           <row>
 119             <entry>Bit 6</entry>
 120             <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
 121           </row>
 122           <row>
 123             <entry>Bit 7</entry>
 124             <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
 125           </row>
 126         </tbody>
 127       </tgroup>
 128     </table>
 129
 130     <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
 131       <title>Block defines</title>
 132       <tgroup cols="3">
 133         <colspec colname="c1" colwidth="1*" />
 134         <colspec colname="c2" colwidth="1*" />
 135         <colspec colname="c3" colwidth="5*" />
 136         <tbody valign="top">
 137           <row>
 138             <entry>V4L2_RDS_BLOCK_MSK</entry>
 139             <entry> </entry>
 140             <entry>7</entry>
 141             <entry>Mask for bits 0-2 to get the block ID.</entry>
 142           </row>
 143           <row>
 144             <entry>V4L2_RDS_BLOCK_A</entry>
 145             <entry> </entry>
 146             <entry>0</entry>
 147             <entry>Block A.</entry>
 148           </row>
 149           <row>
 150             <entry>V4L2_RDS_BLOCK_B</entry>
 151             <entry> </entry>
 152             <entry>1</entry>
 153             <entry>Block B.</entry>
 154           </row>
 155           <row>
 156             <entry>V4L2_RDS_BLOCK_C</entry>
 157             <entry> </entry>
 158             <entry>2</entry>
 159             <entry>Block C.</entry>
 160           </row>
 161           <row>
 162             <entry>V4L2_RDS_BLOCK_D</entry>
 163             <entry> </entry>
 164             <entry>3</entry>
 165             <entry>Block D.</entry>
 166           </row>
 167           <row>
 168             <entry>V4L2_RDS_BLOCK_C_ALT</entry>
 169             <entry> </entry>
 170             <entry>4</entry>
 171             <entry>Block C'.</entry>
 172           </row>
 173           <row>
 174             <entry>V4L2_RDS_BLOCK_INVALID</entry>
 175             <entry>read-only</entry>
 176             <entry>7</entry>
 177             <entry>An invalid block.</entry>
 178           </row>
 179           <row>
 180             <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
 181             <entry>read-only</entry>
 182             <entry>0x40</entry>
 183             <entry>A bit error was detected but corrected.</entry>
 184           </row>
 185           <row>
 186             <entry>V4L2_RDS_BLOCK_ERROR</entry>
 187             <entry>read-only</entry>
 188             <entry>0x80</entry>
 189             <entry>An uncorrectable error occurred.</entry>
 190           </row>
 191         </tbody>
 192       </tgroup>
 193     </table>
 194   </section>
 195
 196 <!--
 197 Local Variables:
 198 mode: sgml
 199 sgml-parent-document: "v4l2.sgml"
 200 indent-tabs-mode: nil
 201 End:
 202  -->