summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/dev-rds.xml
blob: 38883a419e65674092aa4265ac4f637ff80211a4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
     <title>RDS Interface</title>

      <para>The Radio Data System transmits supplementary
information in binary format, for example the station name or travel
information, on an inaudible audio subcarrier of a radio program. This
interface is aimed at devices capable of receiving and/or transmitting RDS
information.</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/encoder 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.  Any tuner that supports RDS
will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in
the <structfield>capability</structfield> field of &v4l2-tuner;.  If
the driver only passes RDS blocks without interpreting the data
the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be
set, see <link linkend="reading-rds-data">Reading RDS data</link>.
For future use the
flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been
defined. However, a driver for a radio tuner with this capability does
not yet exist, so if you are planning to write such a driver you
should discuss this on the linux-media mailing list: &v4l-ml;.</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>

    <para>Devices supporting the RDS output API
set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
the <structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl.
Any modulator that supports RDS will set the
<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
field of &v4l2-modulator;.
In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.
If the driver only passes RDS blocks without interpreting the data
the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the
tuner is capable of handling RDS entities like program identification codes and radio
text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set,
see <link linkend="writing-rds-data">Writing RDS data</link> and
<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para>
  </section>

  <section  id="reading-rds-data">
    <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.</para>
  </section>

  <section  id="writing-rds-data">
    <title>Writing RDS data</title>

      <para>RDS data can be written to the radio device
with the &func-write; function. The data is packed in groups of three bytes,
as follows:</para>
  </section>

  <section>
    <title>RDS datastructures</title>
    <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="4">
	<colspec colname="c1" colwidth="1*" />
	<colspec colname="c2" colwidth="1*" />
	<colspec colname="c3" colwidth="1*" />
	<colspec colname="c4" colwidth="5*" />
	<tbody valign="top">
	  <row>
	    <entry>V4L2_RDS_BLOCK_MSK</entry>
	    <entry> </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> </entry>
	    <entry>0</entry>
	    <entry>Block A.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_B</entry>
	    <entry> </entry>
	    <entry>1</entry>
	    <entry>Block B.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_C</entry>
	    <entry> </entry>
	    <entry>2</entry>
	    <entry>Block C.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_D</entry>
	    <entry> </entry>
	    <entry>3</entry>
	    <entry>Block D.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_C_ALT</entry>
	    <entry> </entry>
	    <entry>4</entry>
	    <entry>Block C'.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_INVALID</entry>
	    <entry>read-only</entry>
	    <entry>7</entry>
	    <entry>An invalid block.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
	    <entry>read-only</entry>
	    <entry>0x40</entry>
	    <entry>A bit error was detected but corrected.</entry>
	  </row>
	  <row>
	    <entry>V4L2_RDS_BLOCK_ERROR</entry>
	    <entry>read-only</entry>
	    <entry>0x80</entry>
	    <entry>An uncorrectable error occurred.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </section>