177 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _rds:5 6*************7RDS Interface8*************9 10The Radio Data System transmits supplementary information in binary11format, for example the station name or travel information, on an12inaudible audio subcarrier of a radio program. This interface is aimed13at devices capable of receiving and/or transmitting RDS information.14 15For more information see the core RDS standard :ref:`iec62106` and the16RBDS standard :ref:`nrsc4`.17 18.. note::19 20 Note that the RBDS standard as is used in the USA is almost21 identical to the RDS standard. Any RDS decoder/encoder can also handle22 RBDS. Only some of the fields have slightly different meanings. See the23 RBDS standard for more information.24 25The RBDS standard also specifies support for MMBS (Modified Mobile26Search). This is a proprietary format which seems to be discontinued.27The RDS interface does not support this format. Should support for MMBS28(or the so-called 'E blocks' in general) be needed, then please contact29the linux-media mailing list:30`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.31 32Querying Capabilities33=====================34 35Devices supporting the RDS capturing API set the36``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct37:c:type:`v4l2_capability` returned by the38:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that39supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the40``capability`` field of struct :c:type:`v4l2_tuner`. If the41driver only passes RDS blocks without interpreting the data the42``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see43:ref:`Reading RDS data <reading-rds-data>`. For future use the flag44``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver45for a radio tuner with this capability does not yet exist, so if you are46planning to write such a driver you should discuss this on the47linux-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 the51``rxsubchans`` field of struct :c:type:`v4l2_tuner`: the52``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 struct56:c:type:`v4l2_capability` returned by the57:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that58supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the59``capability`` field of struct60:c:type:`v4l2_modulator`. In order to enable the RDS61transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the62``txsubchans`` field of struct63:c:type:`v4l2_modulator`. If the driver only passes RDS64blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``65flag has to be set. If the tuner is capable of handling RDS entities66like program identification codes and radio text, the flag67``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see68:ref:`Writing RDS data <writing-rds-data>` and69:ref:`FM Transmitter Control Reference <fm-tx-controls>`.70 71.. _reading-rds-data:72 73Reading RDS data74================75 76RDS data can be read from the radio device with the77:c:func:`read()` function. The data is packed in groups of78three bytes.79 80.. _writing-rds-data:81 82Writing RDS data83================84 85RDS data can be written to the radio device with the86:c:func:`write()` function. The data is packed in groups of87three bytes, as follows:88 89RDS datastructures90==================91 92.. c:type:: v4l2_rds_data93 94.. flat-table:: struct v4l2_rds_data95 :header-rows: 096 :stub-columns: 097 :widths: 1 1 598 99 * - __u8100 - ``lsb``101 - Least Significant Byte of RDS Block102 * - __u8103 - ``msb``104 - Most Significant Byte of RDS Block105 * - __u8106 - ``block``107 - Block description108 109 110.. _v4l2-rds-block:111 112.. tabularcolumns:: |p{2.9cm}|p{14.6cm}|113 114.. flat-table:: Block description115 :header-rows: 0116 :stub-columns: 0117 :widths: 1 5118 119 * - Bits 0-2120 - Block (aka offset) of the received data.121 * - Bits 3-5122 - Deprecated. Currently identical to bits 0-2. Do not use these123 bits.124 * - Bit 6125 - Corrected bit. Indicates that an error was corrected for this data126 block.127 * - Bit 7128 - Error bit. Indicates that an uncorrectable error occurred during129 reception of this block.130 131 132.. _v4l2-rds-block-codes:133 134.. tabularcolumns:: |p{6.4cm}|p{2.0cm}|p{1.2cm}|p{7.0cm}|135 136.. flat-table:: Block defines137 :header-rows: 0138 :stub-columns: 0139 :widths: 1 1 1 5140 141 * - V4L2_RDS_BLOCK_MSK142 -143 - 7144 - Mask for bits 0-2 to get the block ID.145 * - V4L2_RDS_BLOCK_A146 -147 - 0148 - Block A.149 * - V4L2_RDS_BLOCK_B150 -151 - 1152 - Block B.153 * - V4L2_RDS_BLOCK_C154 -155 - 2156 - Block C.157 * - V4L2_RDS_BLOCK_D158 -159 - 3160 - Block D.161 * - V4L2_RDS_BLOCK_C_ALT162 -163 - 4164 - Block C'.165 * - V4L2_RDS_BLOCK_INVALID166 - read-only167 - 7168 - An invalid block.169 * - V4L2_RDS_BLOCK_CORRECTED170 - read-only171 - 0x40172 - A bit error was detected but corrected.173 * - V4L2_RDS_BLOCK_ERROR174 - read-only175 - 0x80176 - An uncorrectable error occurred.177