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 .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
  47
  48 .. _v4l2-frequency-band:
  49
  50 .. flat-table:: struct v4l2_frequency_band
  51     :header-rows:  0
  52     :stub-columns: 0
  53     :widths:       1 1 2 1 1
  54
  55
  56     -  .. row 1
  57
  58        -  __u32
  59
  60        -  ``tuner``
  61
  62        -  The tuner or modulator index number. This is the same value as in
  63           the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
  64           the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
  65           the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
  66           and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
  67           field.
  68
  69     -  .. row 2
  70
  71        -  __u32
  72
  73        -  ``type``
  74
  75        -  The tuner type. This is the same value as in the struct
  76           :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
  77           set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
  78           to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
  79           ``V4L2_TUNER_RADIO`` for modulators (currently only radio
  80           modulators are supported). See :ref:`v4l2-tuner-type`
  81
  82     -  .. row 3
  83
  84        -  __u32
  85
  86        -  ``index``
  87
  88        -  Identifies the frequency band, set by the application.
  89
  90     -  .. row 4
  91
  92        -  __u32
  93
  94        -  ``capability``
  95
  96        -  :cspan:`2` The tuner/modulator capability flags for this
  97           frequency band, see :ref:`tuner-capability`. The
  98           ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
  99           be the same for all frequency bands of the selected
 100           tuner/modulator. So either all bands have that capability set, or
 101           none of them have that capability.
 102
 103     -  .. row 5
 104
 105        -  __u32
 106
 107        -  ``rangelow``
 108
 109        -  :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
 110           if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
 111           of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
 112           ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
 113
 114     -  .. row 6
 115
 116        -  __u32
 117
 118        -  ``rangehigh``
 119
 120        -  :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
 121           or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
 122           units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
 123           when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
 124
 125     -  .. row 7
 126
 127        -  __u32
 128
 129        -  ``modulation``
 130
 131        -  :cspan:`2` The supported modulation systems of this frequency
 132           band. See :ref:`band-modulation`.
 133
 134           .. note::
 135
 136              Currently only one modulation system per frequency band
 137              is supported. More work will need to be done if multiple
 138              modulation systems are possible. Contact the linux-media
 139              mailing list
 140              (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
 141              if you need such functionality.
 142
 143     -  .. row 8
 144
 145        -  __u32
 146
 147        -  ``reserved``\ [9]
 148
 149        -  Reserved for future extensions.
 150
 151           Applications and drivers must set the array to zero.
 152
 153
 154
 155 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 156
 157 .. _band-modulation:
 158
 159 .. flat-table:: Band Modulation Systems
 160     :header-rows:  0
 161     :stub-columns: 0
 162     :widths:       3 1 4
 163
 164
 165     -  .. row 1
 166
 167        -  ``V4L2_BAND_MODULATION_VSB``
 168
 169        -  0x02
 170
 171        -  Vestigial Sideband modulation, used for analog TV.
 172
 173     -  .. row 2
 174
 175        -  ``V4L2_BAND_MODULATION_FM``
 176
 177        -  0x04
 178
 179        -  Frequency Modulation, commonly used for analog radio.
 180
 181     -  .. row 3
 182
 183        -  ``V4L2_BAND_MODULATION_AM``
 184
 185        -  0x08
 186
 187        -  Amplitude Modulation, commonly used for analog radio.
 188
 189
 190 Return Value
 191 ============
 192
 193 On success 0 is returned, on error -1 and the ``errno`` variable is set
 194 appropriately. The generic error codes are described at the
 195 :ref:`Generic Error Codes <gen-errors>` chapter.
 196
 197 EINVAL
 198     The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
 199     wrong.