Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_ENUM_FREQ_BANDS:
   4
   5 ****************************
   6 ioctl VIDIOC_ENUM_FREQ_BANDS
   7 ****************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency_band *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_ENUM_FREQ_BANDS
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 Enumerates the frequency bands that a tuner or modulator supports. To do
  37 this applications initialize the ``tuner``, ``type`` and ``index``
  38 fields, and zero out the ``reserved`` array of a struct
  39 :ref:`v4l2_frequency_band <v4l2-frequency-band>` and call the
  40 :ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure.
  41
  42 This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
  43 of the corresponding tuner/modulator is set.
  44
  45
  46 .. _v4l2-frequency-band:
  47
  48 .. flat-table:: struct v4l2_frequency_band
  49     :header-rows:  0
  50     :stub-columns: 0
  51     :widths:       1 1 2 1 1
  52
  53
  54     -  .. row 1
  55
  56        -  __u32
  57
  58        -  ``tuner``
  59
  60        -  The tuner or modulator index number. This is the same value as in
  61           the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
  62           the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
  63           the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
  64           and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
  65           field.
  66
  67     -  .. row 2
  68
  69        -  __u32
  70
  71        -  ``type``
  72
  73        -  The tuner type. This is the same value as in the struct
  74           :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
  75           set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
  76           to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
  77           ``V4L2_TUNER_RADIO`` for modulators (currently only radio
  78           modulators are supported). See :ref:`v4l2-tuner-type`
  79
  80     -  .. row 3
  81
  82        -  __u32
  83
  84        -  ``index``
  85
  86        -  Identifies the frequency band, set by the application.
  87
  88     -  .. row 4
  89
  90        -  __u32
  91
  92        -  ``capability``
  93
  94        -  :cspan:`2` The tuner/modulator capability flags for this
  95           frequency band, see :ref:`tuner-capability`. The
  96           ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
  97           be the same for all frequency bands of the selected
  98           tuner/modulator. So either all bands have that capability set, or
  99           none of them have that capability.
 100
 101     -  .. row 5
 102
 103        -  __u32
 104
 105        -  ``rangelow``
 106
 107        -  :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
 108           if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
 109           of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
 110           ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
 111
 112     -  .. row 6
 113
 114        -  __u32
 115
 116        -  ``rangehigh``
 117
 118        -  :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
 119           or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
 120           units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
 121           when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
 122
 123     -  .. row 7
 124
 125        -  __u32
 126
 127        -  ``modulation``
 128
 129        -  :cspan:`2` The supported modulation systems of this frequency
 130           band. See :ref:`band-modulation`.
 131
 132           .. note:: Currently only one modulation system per frequency band
 133              is supported. More work will need to be done if multiple
 134              modulation systems are possible. Contact the linux-media
 135              mailing list
 136              (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
 137              if you need such functionality.
 138
 139     -  .. row 8
 140
 141        -  __u32
 142
 143        -  ``reserved``\ [9]
 144
 145        -  Reserved for future extensions. Applications and drivers must set
 146           the array to zero.
 147
 148
 149
 150 .. _band-modulation:
 151
 152 .. flat-table:: Band Modulation Systems
 153     :header-rows:  0
 154     :stub-columns: 0
 155     :widths:       3 1 4
 156
 157
 158     -  .. row 1
 159
 160        -  ``V4L2_BAND_MODULATION_VSB``
 161
 162        -  0x02
 163
 164        -  Vestigial Sideband modulation, used for analog TV.
 165
 166     -  .. row 2
 167
 168        -  ``V4L2_BAND_MODULATION_FM``
 169
 170        -  0x04
 171
 172        -  Frequency Modulation, commonly used for analog radio.
 173
 174     -  .. row 3
 175
 176        -  ``V4L2_BAND_MODULATION_AM``
 177
 178        -  0x08
 179
 180        -  Amplitude Modulation, commonly used for analog radio.
 181
 182
 183 Return Value
 184 ============
 185
 186 On success 0 is returned, on error -1 and the ``errno`` variable is set
 187 appropriately. The generic error codes are described at the
 188 :ref:`Generic Error Codes <gen-errors>` chapter.
 189
 190 EINVAL
 191     The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
 192     wrong.