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::
  18
  19    Note that the RBDS standard as is used in the USA is almost
  20    identical to the RDS standard. Any RDS decoder/encoder can also handle
  21    RBDS. Only some of the fields have slightly different meanings. See the
  22    RBDS standard for more information.
  23
  24 The RBDS standard also specifies support for MMBS (Modified Mobile
  25 Search). This is a proprietary format which seems to be discontinued.
  26 The RDS interface does not support this format. Should support for MMBS
  27 (or the so-called 'E blocks' in general) be needed, then please contact
  28 the linux-media mailing list:
  29 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
  30
  31
  32 Querying Capabilities
  33 =====================
  34
  35 Devices 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
  39 supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
  40 ``capability`` field of struct :c:type:`v4l2_tuner`. If the
  41 driver 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
  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 discuss this on the
  47 linux-media mailing list:
  48 `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
  49
  50 Whether 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
  54 Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
  55 flag in the ``capabilities`` field of struct
  56 :c:type:`v4l2_capability` returned by the
  57 :ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that
  58 supports 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
  61 transmission 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
  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 handling RDS entities
  66 like 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
  72 .. _reading-rds-data:
  73
  74 Reading RDS data
  75 ================
  76
  77 RDS data can be read from the radio device with the
  78 :ref:`read() <func-read>` function. The data is packed in groups of
  79 three bytes.
  80
  81
  82 .. _writing-rds-data:
  83
  84 Writing RDS data
  85 ================
  86
  87 RDS data can be written to the radio device with the
  88 :ref:`write() <func-write>` function. The data is packed in groups of
  89 three bytes, as follows:
  90
  91
  92 RDS datastructures
  93 ==================
  94
  95
  96 .. c:type:: v4l2_rds_data
  97
  98 .. tabularcolumns:: |p{2.5cm}|p{2.5cm}|p{12.5cm}|
  99
 100 .. flat-table:: struct v4l2_rds_data
 101     :header-rows:  0
 102     :stub-columns: 0
 103     :widths:       1 1 5
 104
 105
 106     -  .. row 1
 107
 108        -  __u8
 109
 110        -  ``lsb``
 111
 112        -  Least Significant Byte of RDS Block
 113
 114     -  .. row 2
 115
 116        -  __u8
 117
 118        -  ``msb``
 119
 120        -  Most Significant Byte of RDS Block
 121
 122     -  .. row 3
 123
 124        -  __u8
 125
 126        -  ``block``
 127
 128        -  Block description
 129
 130
 131
 132 .. _v4l2-rds-block:
 133
 134 .. tabularcolumns:: |p{2.9cm}|p{14.6cm}|
 135
 136 .. flat-table:: Block description
 137     :header-rows:  0
 138     :stub-columns: 0
 139     :widths:       1 5
 140
 141
 142     -  .. row 1
 143
 144        -  Bits 0-2
 145
 146        -  Block (aka offset) of the received data.
 147
 148     -  .. row 2
 149
 150        -  Bits 3-5
 151
 152        -  Deprecated. Currently identical to bits 0-2. Do not use these
 153           bits.
 154
 155     -  .. row 3
 156
 157        -  Bit 6
 158
 159        -  Corrected bit. Indicates that an error was corrected for this data
 160           block.
 161
 162     -  .. row 4
 163
 164        -  Bit 7
 165
 166        -  Error bit. Indicates that an uncorrectable error occurred during
 167           reception of this block.
 168
 169
 170
 171 .. _v4l2-rds-block-codes:
 172
 173 .. tabularcolumns:: |p{5.6cm}|p{2.0cm}|p{1.5cm}|p{7.0cm}|
 174
 175 .. flat-table:: Block defines
 176     :header-rows:  0
 177     :stub-columns: 0
 178     :widths:       1 1 1 5
 179
 180
 181     -  .. row 1
 182
 183        -  V4L2_RDS_BLOCK_MSK
 184
 185        -
 186        -  7
 187
 188        -  Mask for bits 0-2 to get the block ID.
 189
 190     -  .. row 2
 191
 192        -  V4L2_RDS_BLOCK_A
 193
 194        -
 195        -  0
 196
 197        -  Block A.
 198
 199     -  .. row 3
 200
 201        -  V4L2_RDS_BLOCK_B
 202
 203        -
 204        -  1
 205
 206        -  Block B.
 207
 208     -  .. row 4
 209
 210        -  V4L2_RDS_BLOCK_C
 211
 212        -
 213        -  2
 214
 215        -  Block C.
 216
 217     -  .. row 5
 218
 219        -  V4L2_RDS_BLOCK_D
 220
 221        -
 222        -  3
 223
 224        -  Block D.
 225
 226     -  .. row 6
 227
 228        -  V4L2_RDS_BLOCK_C_ALT
 229
 230        -
 231        -  4
 232
 233        -  Block C'.
 234
 235     -  .. row 7
 236
 237        -  V4L2_RDS_BLOCK_INVALID
 238
 239        -  read-only
 240
 241        -  7
 242
 243        -  An invalid block.
 244
 245     -  .. row 8
 246
 247        -  V4L2_RDS_BLOCK_CORRECTED
 248
 249        -  read-only
 250
 251        -  0x40
 252
 253        -  A bit error was detected but corrected.
 254
 255     -  .. row 9
 256
 257        -  V4L2_RDS_BLOCK_ERROR
 258
 259        -  read-only
 260
 261        -  0x80
 262
 263        -  An uncorrectable error occurred.