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