Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml

   1 <refentry id="vidioc-enum-freq-bands">
   2   <refmeta>
   3     <refentrytitle>ioctl VIDIOC_ENUM_FREQ_BANDS</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>VIDIOC_ENUM_FREQ_BANDS</refname>
   9     <refpurpose>Enumerate supported frequency bands</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct v4l2_frequency_band
  19 *<parameter>argp</parameter></paramdef>
  20       </funcprototype>
  21     </funcsynopsis>
  22   </refsynopsisdiv>
  23
  24   <refsect1>
  25     <title>Arguments</title>
  26
  27     <variablelist>
  28       <varlistentry>
  29         <term><parameter>fd</parameter></term>
  30         <listitem>
  31           <para>&fd;</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>VIDIOC_ENUM_FREQ_BANDS</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <note>
  53       <title>Experimental</title>
  54       <para>This is an <link linkend="experimental"> experimental </link>
  55       interface and may change in the future.</para>
  56     </note>
  57
  58     <para>Enumerates the frequency bands that a tuner or modulator supports.
  59 To do this applications initialize the <structfield>tuner</structfield>,
  60 <structfield>type</structfield> and <structfield>index</structfield> fields,
  61 and zero out the <structfield>reserved</structfield> array of a &v4l2-frequency-band; and
  62 call the <constant>VIDIOC_ENUM_FREQ_BANDS</constant> ioctl with a pointer
  63 to this structure.</para>
  64
  65     <para>This ioctl is supported if the <constant>V4L2_TUNER_CAP_FREQ_BANDS</constant> capability
  66     of the corresponding tuner/modulator is set.</para>
  67
  68     <table pgwide="1" frame="none" id="v4l2-frequency-band">
  69       <title>struct <structname>v4l2_frequency_band</structname></title>
  70       <tgroup cols="3">
  71         &cs-str;
  72         <tbody valign="top">
  73           <row>
  74             <entry>__u32</entry>
  75             <entry><structfield>tuner</structfield></entry>
  76             <entry>The tuner or modulator index number. This is the
  77 same value as in the &v4l2-input; <structfield>tuner</structfield>
  78 field and the &v4l2-tuner; <structfield>index</structfield> field, or
  79 the &v4l2-output; <structfield>modulator</structfield> field and the
  80 &v4l2-modulator; <structfield>index</structfield> field.</entry>
  81           </row>
  82           <row>
  83             <entry>__u32</entry>
  84             <entry><structfield>type</structfield></entry>
  85             <entry>The tuner type. This is the same value as in the
  86 &v4l2-tuner; <structfield>type</structfield> field. The type must be set
  87 to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename>
  88 device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant>
  89 for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for
  90 modulators (currently only radio modulators are supported).
  91 See <xref linkend="v4l2-tuner-type" /></entry>
  92           </row>
  93           <row>
  94             <entry>__u32</entry>
  95             <entry><structfield>index</structfield></entry>
  96             <entry>Identifies the frequency band, set by the application.</entry>
  97           </row>
  98           <row>
  99             <entry>__u32</entry>
 100             <entry><structfield>capability</structfield></entry>
 101             <entry spanname="hspan">The tuner/modulator capability flags for
 102 this frequency band, see <xref linkend="tuner-capability" />. The <constant>V4L2_TUNER_CAP_LOW</constant>
 103 or <constant>V4L2_TUNER_CAP_1HZ</constant> capability must be the same for all frequency bands of the selected tuner/modulator.
 104 So either all bands have that capability set, or none of them have that capability.</entry>
 105           </row>
 106           <row>
 107             <entry>__u32</entry>
 108             <entry><structfield>rangelow</structfield></entry>
 109             <entry spanname="hspan">The lowest tunable frequency in
 110 units of 62.5 kHz, or if the <structfield>capability</structfield>
 111 flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
 112 Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
 113 <constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
 114           </row>
 115           <row>
 116             <entry>__u32</entry>
 117             <entry><structfield>rangehigh</structfield></entry>
 118             <entry spanname="hspan">The highest tunable frequency in
 119 units of 62.5 kHz, or if the <structfield>capability</structfield>
 120 flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
 121 Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
 122 <constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
 123           </row>
 124           <row>
 125             <entry>__u32</entry>
 126             <entry><structfield>modulation</structfield></entry>
 127             <entry spanname="hspan">The supported modulation systems of this frequency band.
 128             See <xref linkend="band-modulation" />. Note that currently only one
 129             modulation system per frequency band is supported. More work will need to
 130             be done if multiple modulation systems are possible. Contact the
 131             linux-media mailing list (&v4l-ml;) if you need that functionality.</entry>
 132           </row>
 133           <row>
 134             <entry>__u32</entry>
 135             <entry><structfield>reserved</structfield>[9]</entry>
 136             <entry>Reserved for future extensions. Applications and drivers
 137             must set the array to zero.</entry>
 138           </row>
 139         </tbody>
 140       </tgroup>
 141     </table>
 142
 143     <table pgwide="1" frame="none" id="band-modulation">
 144       <title>Band Modulation Systems</title>
 145       <tgroup cols="3">
 146         &cs-def;
 147         <tbody valign="top">
 148           <row>
 149             <entry><constant>V4L2_BAND_MODULATION_VSB</constant></entry>
 150             <entry>0x02</entry>
 151             <entry>Vestigial Sideband modulation, used for analog TV.</entry>
 152           </row>
 153           <row>
 154             <entry><constant>V4L2_BAND_MODULATION_FM</constant></entry>
 155             <entry>0x04</entry>
 156             <entry>Frequency Modulation, commonly used for analog radio.</entry>
 157           </row>
 158           <row>
 159             <entry><constant>V4L2_BAND_MODULATION_AM</constant></entry>
 160             <entry>0x08</entry>
 161             <entry>Amplitude Modulation, commonly used for analog radio.</entry>
 162           </row>
 163         </tbody>
 164       </tgroup>
 165     </table>
 166   </refsect1>
 167
 168   <refsect1>
 169     &return-value;
 170
 171     <variablelist>
 172       <varlistentry>
 173         <term><errorcode>EINVAL</errorcode></term>
 174         <listitem>
 175           <para>The <structfield>tuner</structfield> or <structfield>index</structfield>
 176 is out of bounds or the <structfield>type</structfield> field is wrong.</para>
 177         </listitem>
 178       </varlistentry>
 179     </variablelist>
 180   </refsect1>
 181 </refentry>