Merge tag 'armsoc-dt' of git://git.kernel.org/pub/scm/linux/kernel/git/soc/soc
[sfrench/cifs-2.6.git] / Documentation / media / uapi / v4l / dev-rds.rst
1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
7 ..
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10 .. _rds:
11
12 *************
13 RDS Interface
14 *************
15
16 The Radio Data System transmits supplementary information in binary
17 format, for example the station name or travel information, on an
18 inaudible audio subcarrier of a radio program. This interface is aimed
19 at devices capable of receiving and/or transmitting RDS information.
20
21 For more information see the core RDS standard :ref:`iec62106` and the
22 RBDS standard :ref:`nrsc4`.
23
24 .. note::
25
26    Note that the RBDS standard as is used in the USA is almost
27    identical to the RDS standard. Any RDS decoder/encoder can also handle
28    RBDS. Only some of the fields have slightly different meanings. See the
29    RBDS standard for more information.
30
31 The RBDS standard also specifies support for MMBS (Modified Mobile
32 Search). This is a proprietary format which seems to be discontinued.
33 The RDS interface does not support this format. Should support for MMBS
34 (or the so-called 'E blocks' in general) be needed, then please contact
35 the linux-media mailing list:
36 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
37
38
39 Querying Capabilities
40 =====================
41
42 Devices supporting the RDS capturing API set the
43 ``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct
44 :c:type:`v4l2_capability` returned by the
45 :ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that
46 supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
47 ``capability`` field of struct :c:type:`v4l2_tuner`. If the
48 driver only passes RDS blocks without interpreting the data the
49 ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see
50 :ref:`Reading RDS data <reading-rds-data>`. For future use the flag
51 ``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver
52 for a radio tuner with this capability does not yet exist, so if you are
53 planning to write such a driver you should discuss this on the
54 linux-media mailing list:
55 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
56
57 Whether an RDS signal is present can be detected by looking at the
58 ``rxsubchans`` field of struct :c:type:`v4l2_tuner`: the
59 ``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected.
60
61 Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
62 flag in the ``capabilities`` field of struct
63 :c:type:`v4l2_capability` returned by the
64 :ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that
65 supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
66 ``capability`` field of struct
67 :c:type:`v4l2_modulator`. In order to enable the RDS
68 transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the
69 ``txsubchans`` field of struct
70 :c:type:`v4l2_modulator`. If the driver only passes RDS
71 blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
72 flag has to be set. If the tuner is capable of handling RDS entities
73 like program identification codes and radio text, the flag
74 ``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see
75 :ref:`Writing RDS data <writing-rds-data>` and
76 :ref:`FM Transmitter Control Reference <fm-tx-controls>`.
77
78
79 .. _reading-rds-data:
80
81 Reading RDS data
82 ================
83
84 RDS data can be read from the radio device with the
85 :ref:`read() <func-read>` function. The data is packed in groups of
86 three bytes.
87
88
89 .. _writing-rds-data:
90
91 Writing RDS data
92 ================
93
94 RDS data can be written to the radio device with the
95 :ref:`write() <func-write>` function. The data is packed in groups of
96 three bytes, as follows:
97
98
99 RDS datastructures
100 ==================
101
102
103 .. c:type:: v4l2_rds_data
104
105 .. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}|
106
107 .. flat-table:: struct v4l2_rds_data
108     :header-rows:  0
109     :stub-columns: 0
110     :widths:       1 1 5
111
112     * - __u8
113       - ``lsb``
114       - Least Significant Byte of RDS Block
115     * - __u8
116       - ``msb``
117       - Most Significant Byte of RDS Block
118     * - __u8
119       - ``block``
120       - Block description
121
122
123
124 .. _v4l2-rds-block:
125
126 .. tabularcolumns:: |p{2.9cm}|p{14.6cm}|
127
128 .. flat-table:: Block description
129     :header-rows:  0
130     :stub-columns: 0
131     :widths:       1 5
132
133     * - Bits 0-2
134       - Block (aka offset) of the received data.
135     * - Bits 3-5
136       - Deprecated. Currently identical to bits 0-2. Do not use these
137         bits.
138     * - Bit 6
139       - Corrected bit. Indicates that an error was corrected for this data
140         block.
141     * - Bit 7
142       - Error bit. Indicates that an uncorrectable error occurred during
143         reception of this block.
144
145
146
147 .. _v4l2-rds-block-codes:
148
149 .. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.9cm}|
150
151 .. flat-table:: Block defines
152     :header-rows:  0
153     :stub-columns: 0
154     :widths:       1 1 1 5
155
156     * - V4L2_RDS_BLOCK_MSK
157       -
158       - 7
159       - Mask for bits 0-2 to get the block ID.
160     * - V4L2_RDS_BLOCK_A
161       -
162       - 0
163       - Block A.
164     * - V4L2_RDS_BLOCK_B
165       -
166       - 1
167       - Block B.
168     * - V4L2_RDS_BLOCK_C
169       -
170       - 2
171       - Block C.
172     * - V4L2_RDS_BLOCK_D
173       -
174       - 3
175       - Block D.
176     * - V4L2_RDS_BLOCK_C_ALT
177       -
178       - 4
179       - Block C'.
180     * - V4L2_RDS_BLOCK_INVALID
181       - read-only
182       - 7
183       - An invalid block.
184     * - V4L2_RDS_BLOCK_CORRECTED
185       - read-only
186       - 0x40
187       - A bit error was detected but corrected.
188     * - V4L2_RDS_BLOCK_ERROR
189       - read-only
190       - 0x80
191       - An uncorrectable error occurred.