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{5.6cm}|p{2.0cm}|p{1.5cm}|p{7.0cm}|
 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.