Orange Pi5 kernel

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