summaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media/v4l/vidioc-enum-freq-bands.xml
blob: 4e8ea65f7282257f3f72d95de5f1439d2b3023e2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
<refentry id="vidioc-enum-freq-bands">
  <refmeta>
    <refentrytitle>ioctl VIDIOC_ENUM_FREQ_BANDS</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>VIDIOC_ENUM_FREQ_BANDS</refname>
    <refpurpose>Enumerate supported frequency bands</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct v4l2_frequency_band
*<parameter>argp</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Arguments</title>

    <variablelist>
      <varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	  <para>&fd;</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	  <para>VIDIOC_ENUM_FREQ_BANDS</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	  <para></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Description</title>

    <note>
      <title>Experimental</title>
      <para>This is an <link linkend="experimental"> experimental </link>
      interface and may change in the future.</para>
    </note>

    <para>Enumerates the frequency bands that a tuner or modulator supports.
To do this applications initialize the <structfield>tuner</structfield>,
<structfield>type</structfield> and <structfield>index</structfield> fields,
and zero out the <structfield>reserved</structfield> array of a &v4l2-frequency-band; and
call the <constant>VIDIOC_ENUM_FREQ_BANDS</constant> ioctl with a pointer
to this structure.</para>

    <para>This ioctl is supported if the <constant>V4L2_TUNER_CAP_FREQ_BANDS</constant> capability
    of the corresponding tuner/modulator is set.</para>

    <table pgwide="1" frame="none" id="v4l2-frequency-band">
      <title>struct <structname>v4l2_frequency_band</structname></title>
      <tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>tuner</structfield></entry>
	    <entry>The tuner or modulator index number. This is the
same value as in the &v4l2-input; <structfield>tuner</structfield>
field and the &v4l2-tuner; <structfield>index</structfield> field, or
the &v4l2-output; <structfield>modulator</structfield> field and the
&v4l2-modulator; <structfield>index</structfield> field.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>type</structfield></entry>
	    <entry>The tuner type. This is the same value as in the
&v4l2-tuner; <structfield>type</structfield> field. The type must be set
to <constant>V4L2_TUNER_RADIO</constant> for <filename>/dev/radioX</filename>
device nodes, and to <constant>V4L2_TUNER_ANALOG_TV</constant>
for all others. Set this field to <constant>V4L2_TUNER_RADIO</constant> for
modulators (currently only radio modulators are supported).
See <xref linkend="v4l2-tuner-type" /></entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>index</structfield></entry>
	    <entry>Identifies the frequency band, set by the application.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>capability</structfield></entry>
	    <entry spanname="hspan">The tuner/modulator capability flags for
this frequency band, see <xref linkend="tuner-capability" />. The <constant>V4L2_TUNER_CAP_LOW</constant>
or <constant>V4L2_TUNER_CAP_1HZ</constant> capability must be the same for all frequency bands of the selected tuner/modulator.
So either all bands have that capability set, or none of them have that capability.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>rangelow</structfield></entry>
	    <entry spanname="hspan">The lowest tunable frequency in
units of 62.5 kHz, or if the <structfield>capability</structfield>
flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>rangehigh</structfield></entry>
	    <entry spanname="hspan">The highest tunable frequency in
units of 62.5 kHz, or if the <structfield>capability</structfield>
flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
Hz, for this frequency band. A 1 Hz unit is used when the <structfield>capability</structfield> flag
<constant>V4L2_TUNER_CAP_1HZ</constant> is set.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>modulation</structfield></entry>
	    <entry spanname="hspan">The supported modulation systems of this frequency band.
	    See <xref linkend="band-modulation" />. Note that currently only one
	    modulation system per frequency band is supported. More work will need to
	    be done if multiple modulation systems are possible. Contact the
	    linux-media mailing list (&v4l-ml;) if you need that functionality.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>reserved</structfield>[9]</entry>
	    <entry>Reserved for future extensions. Applications and drivers
	    must set the array to zero.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="band-modulation">
      <title>Band Modulation Systems</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>V4L2_BAND_MODULATION_VSB</constant></entry>
	    <entry>0x02</entry>
	    <entry>Vestigial Sideband modulation, used for analog TV.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_BAND_MODULATION_FM</constant></entry>
	    <entry>0x04</entry>
	    <entry>Frequency Modulation, commonly used for analog radio.</entry>
	  </row>
	  <row>
	    <entry><constant>V4L2_BAND_MODULATION_AM</constant></entry>
	    <entry>0x08</entry>
	    <entry>Amplitude Modulation, commonly used for analog radio.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;

    <variablelist>
      <varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	  <para>The <structfield>tuner</structfield> or <structfield>index</structfield>
is out of bounds or the <structfield>type</structfield> field is wrong.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>