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