Documentation/DocBook/media/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     <title>RDS datastructures</title>
  79     <table frame="none" pgwide="1" id="v4l2-rds-data">
  80       <title>struct
  81 <structname>v4l2_rds_data</structname></title>
  82       <tgroup cols="3">
  83         <colspec colname="c1" colwidth="1*" />
  84         <colspec colname="c2" colwidth="1*" />
  85         <colspec colname="c3" colwidth="5*" />
  86         <tbody valign="top">
  87           <row>
  88             <entry>__u8</entry>
  89             <entry><structfield>lsb</structfield></entry>
  90             <entry>Least Significant Byte of RDS Block</entry>
  91           </row>
  92           <row>
  93             <entry>__u8</entry>
  94             <entry><structfield>msb</structfield></entry>
  95             <entry>Most Significant Byte of RDS Block</entry>
  96           </row>
  97           <row>
  98             <entry>__u8</entry>
  99             <entry><structfield>block</structfield></entry>
 100             <entry>Block description</entry>
 101           </row>
 102         </tbody>
 103       </tgroup>
 104     </table>
 105     <table frame="none" pgwide="1" id="v4l2-rds-block">
 106       <title>Block description</title>
 107       <tgroup cols="2">
 108         <colspec colname="c1" colwidth="1*" />
 109         <colspec colname="c2" colwidth="5*" />
 110         <tbody valign="top">
 111           <row>
 112             <entry>Bits 0-2</entry>
 113             <entry>Block (aka offset) of the received data.</entry>
 114           </row>
 115           <row>
 116             <entry>Bits 3-5</entry>
 117             <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
 118           </row>
 119           <row>
 120             <entry>Bit 6</entry>
 121             <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
 122           </row>
 123           <row>
 124             <entry>Bit 7</entry>
 125             <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
 126           </row>
 127         </tbody>
 128       </tgroup>
 129     </table>
 130
 131     <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
 132       <title>Block defines</title>
 133       <tgroup cols="4">
 134         <colspec colname="c1" colwidth="1*" />
 135         <colspec colname="c2" colwidth="1*" />
 136         <colspec colname="c3" colwidth="1*" />
 137         <colspec colname="c4" colwidth="5*" />
 138         <tbody valign="top">
 139           <row>
 140             <entry>V4L2_RDS_BLOCK_MSK</entry>
 141             <entry> </entry>
 142             <entry>7</entry>
 143             <entry>Mask for bits 0-2 to get the block ID.</entry>
 144           </row>
 145           <row>
 146             <entry>V4L2_RDS_BLOCK_A</entry>
 147             <entry> </entry>
 148             <entry>0</entry>
 149             <entry>Block A.</entry>
 150           </row>
 151           <row>
 152             <entry>V4L2_RDS_BLOCK_B</entry>
 153             <entry> </entry>
 154             <entry>1</entry>
 155             <entry>Block B.</entry>
 156           </row>
 157           <row>
 158             <entry>V4L2_RDS_BLOCK_C</entry>
 159             <entry> </entry>
 160             <entry>2</entry>
 161             <entry>Block C.</entry>
 162           </row>
 163           <row>
 164             <entry>V4L2_RDS_BLOCK_D</entry>
 165             <entry> </entry>
 166             <entry>3</entry>
 167             <entry>Block D.</entry>
 168           </row>
 169           <row>
 170             <entry>V4L2_RDS_BLOCK_C_ALT</entry>
 171             <entry> </entry>
 172             <entry>4</entry>
 173             <entry>Block C'.</entry>
 174           </row>
 175           <row>
 176             <entry>V4L2_RDS_BLOCK_INVALID</entry>
 177             <entry>read-only</entry>
 178             <entry>7</entry>
 179             <entry>An invalid block.</entry>
 180           </row>
 181           <row>
 182             <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
 183             <entry>read-only</entry>
 184             <entry>0x40</entry>
 185             <entry>A bit error was detected but corrected.</entry>
 186           </row>
 187           <row>
 188             <entry>V4L2_RDS_BLOCK_ERROR</entry>
 189             <entry>read-only</entry>
 190             <entry>0x80</entry>
 191             <entry>An uncorrectable error occurred.</entry>
 192           </row>
 193         </tbody>
 194       </tgroup>
 195     </table>
 196   </section>
 197
 198 <!--
 199 Local Variables:
 200 mode: sgml
 201 sgml-parent-document: "v4l2.sgml"
 202 indent-tabs-mode: nil
 203 End:
 204  -->