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