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 .. c:function:: int ioctl( int fd, VIDIOC_ENUM_FREQ_BANDS, struct v4l2_frequency_band *argp )
  19     :name: VIDIOC_ENUM_FREQ_BANDS
  20
  21
  22 Arguments
  23 =========
  24
  25 ``fd``
  26     File descriptor returned by :ref:`open() <func-open>`.
  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 :c:type:`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 .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
  45
  46 .. c:type:: 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 :c:type:`v4l2_input` ``tuner`` field and
  62           the struct :c:type:`v4l2_tuner` ``index`` field, or
  63           the struct :c:type:`v4l2_output` ``modulator`` field
  64           and the struct :c:type:`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           :c:type:`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 :c:type:`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::
 133
 134              Currently only one modulation system per frequency band
 135              is supported. More work will need to be done if multiple
 136              modulation systems are possible. Contact the linux-media
 137              mailing list
 138              (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
 139              if you need such functionality.
 140
 141     -  .. row 8
 142
 143        -  __u32
 144
 145        -  ``reserved``\ [9]
 146
 147        -  Reserved for future extensions.
 148
 149           Applications and drivers must set the array to zero.
 150
 151
 152
 153 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 154
 155 .. _band-modulation:
 156
 157 .. flat-table:: Band Modulation Systems
 158     :header-rows:  0
 159     :stub-columns: 0
 160     :widths:       3 1 4
 161
 162
 163     -  .. row 1
 164
 165        -  ``V4L2_BAND_MODULATION_VSB``
 166
 167        -  0x02
 168
 169        -  Vestigial Sideband modulation, used for analog TV.
 170
 171     -  .. row 2
 172
 173        -  ``V4L2_BAND_MODULATION_FM``
 174
 175        -  0x04
 176
 177        -  Frequency Modulation, commonly used for analog radio.
 178
 179     -  .. row 3
 180
 181        -  ``V4L2_BAND_MODULATION_AM``
 182
 183        -  0x08
 184
 185        -  Amplitude Modulation, commonly used for analog radio.
 186
 187
 188 Return Value
 189 ============
 190
 191 On success 0 is returned, on error -1 and the ``errno`` variable is set
 192 appropriately. The generic error codes are described at the
 193 :ref:`Generic Error Codes <gen-errors>` chapter.
 194
 195 EINVAL
 196     The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
 197     wrong.