Documentation/media/uapi/v4l/dev-rds.rst

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