diff options
Diffstat (limited to 'Documentation/DocBook/v4l/vidioc-g-modulator.xml')
-rw-r--r-- | Documentation/DocBook/v4l/vidioc-g-modulator.xml | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/v4l/vidioc-g-modulator.xml new file mode 100644 index 000000000000..15ce660f0f5a --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-g-modulator.xml | |||
@@ -0,0 +1,246 @@ | |||
1 | <refentry id="vidioc-g-modulator"> | ||
2 | <refmeta> | ||
3 | <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle> | ||
4 | &manvol; | ||
5 | </refmeta> | ||
6 | |||
7 | <refnamediv> | ||
8 | <refname>VIDIOC_G_MODULATOR</refname> | ||
9 | <refname>VIDIOC_S_MODULATOR</refname> | ||
10 | <refpurpose>Get or set modulator attributes</refpurpose> | ||
11 | </refnamediv> | ||
12 | |||
13 | <refsynopsisdiv> | ||
14 | <funcsynopsis> | ||
15 | <funcprototype> | ||
16 | <funcdef>int <function>ioctl</function></funcdef> | ||
17 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
18 | <paramdef>int <parameter>request</parameter></paramdef> | ||
19 | <paramdef>struct v4l2_modulator | ||
20 | *<parameter>argp</parameter></paramdef> | ||
21 | </funcprototype> | ||
22 | </funcsynopsis> | ||
23 | <funcsynopsis> | ||
24 | <funcprototype> | ||
25 | <funcdef>int <function>ioctl</function></funcdef> | ||
26 | <paramdef>int <parameter>fd</parameter></paramdef> | ||
27 | <paramdef>int <parameter>request</parameter></paramdef> | ||
28 | <paramdef>const struct v4l2_modulator | ||
29 | *<parameter>argp</parameter></paramdef> | ||
30 | </funcprototype> | ||
31 | </funcsynopsis> | ||
32 | </refsynopsisdiv> | ||
33 | |||
34 | <refsect1> | ||
35 | <title>Arguments</title> | ||
36 | |||
37 | <variablelist> | ||
38 | <varlistentry> | ||
39 | <term><parameter>fd</parameter></term> | ||
40 | <listitem> | ||
41 | <para>&fd;</para> | ||
42 | </listitem> | ||
43 | </varlistentry> | ||
44 | <varlistentry> | ||
45 | <term><parameter>request</parameter></term> | ||
46 | <listitem> | ||
47 | <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para> | ||
48 | </listitem> | ||
49 | </varlistentry> | ||
50 | <varlistentry> | ||
51 | <term><parameter>argp</parameter></term> | ||
52 | <listitem> | ||
53 | <para></para> | ||
54 | </listitem> | ||
55 | </varlistentry> | ||
56 | </variablelist> | ||
57 | </refsect1> | ||
58 | |||
59 | <refsect1> | ||
60 | <title>Description</title> | ||
61 | |||
62 | <para>To query the attributes of a modulator applications initialize | ||
63 | the <structfield>index</structfield> field and zero out the | ||
64 | <structfield>reserved</structfield> array of a &v4l2-modulator; and | ||
65 | call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer | ||
66 | to this structure. Drivers fill the rest of the structure or return an | ||
67 | &EINVAL; when the index is out of bounds. To enumerate all modulators | ||
68 | applications shall begin at index zero, incrementing by one until the | ||
69 | driver returns <errorcode>EINVAL</errorcode>.</para> | ||
70 | |||
71 | <para>Modulators have two writable properties, an audio | ||
72 | modulation set and the radio frequency. To change the modulated audio | ||
73 | subprograms, applications initialize the <structfield>index | ||
74 | </structfield> and <structfield>txsubchans</structfield> fields and the | ||
75 | <structfield>reserved</structfield> array and call the | ||
76 | <constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a | ||
77 | different audio modulation if the request cannot be satisfied. However | ||
78 | this is a write-only ioctl, it does not return the actual audio | ||
79 | modulation selected.</para> | ||
80 | |||
81 | <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl | ||
82 | is available.</para> | ||
83 | |||
84 | <table pgwide="1" frame="none" id="v4l2-modulator"> | ||
85 | <title>struct <structname>v4l2_modulator</structname></title> | ||
86 | <tgroup cols="3"> | ||
87 | &cs-str; | ||
88 | <tbody valign="top"> | ||
89 | <row> | ||
90 | <entry>__u32</entry> | ||
91 | <entry><structfield>index</structfield></entry> | ||
92 | <entry>Identifies the modulator, set by the | ||
93 | application.</entry> | ||
94 | </row> | ||
95 | <row> | ||
96 | <entry>__u8</entry> | ||
97 | <entry><structfield>name</structfield>[32]</entry> | ||
98 | <entry>Name of the modulator, a NUL-terminated ASCII | ||
99 | string. This information is intended for the user.</entry> | ||
100 | </row> | ||
101 | <row> | ||
102 | <entry>__u32</entry> | ||
103 | <entry><structfield>capability</structfield></entry> | ||
104 | <entry>Modulator capability flags. No flags are defined | ||
105 | for this field, the tuner flags in &v4l2-tuner; | ||
106 | are used accordingly. The audio flags indicate the ability | ||
107 | to encode audio subprograms. They will <emphasis>not</emphasis> | ||
108 | change for example with the current video standard.</entry> | ||
109 | </row> | ||
110 | <row> | ||
111 | <entry>__u32</entry> | ||
112 | <entry><structfield>rangelow</structfield></entry> | ||
113 | <entry>The lowest tunable frequency in units of 62.5 | ||
114 | KHz, or if the <structfield>capability</structfield> flag | ||
115 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
116 | Hz.</entry> | ||
117 | </row> | ||
118 | <row> | ||
119 | <entry>__u32</entry> | ||
120 | <entry><structfield>rangehigh</structfield></entry> | ||
121 | <entry>The highest tunable frequency in units of 62.5 | ||
122 | KHz, or if the <structfield>capability</structfield> flag | ||
123 | <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5 | ||
124 | Hz.</entry> | ||
125 | </row> | ||
126 | <row> | ||
127 | <entry>__u32</entry> | ||
128 | <entry><structfield>txsubchans</structfield></entry> | ||
129 | <entry>With this field applications can determine how | ||
130 | audio sub-carriers shall be modulated. It contains a set of flags as | ||
131 | defined in <xref linkend="modulator-txsubchans" />. Note the tuner | ||
132 | <structfield>rxsubchans</structfield> flags are reused, but the | ||
133 | semantics are different. Video output devices are assumed to have an | ||
134 | analog or PCM audio input with 1-3 channels. The | ||
135 | <structfield>txsubchans</structfield> flags select one or more | ||
136 | channels for modulation, together with some audio subprogram | ||
137 | indicator, for example a stereo pilot tone.</entry> | ||
138 | </row> | ||
139 | <row> | ||
140 | <entry>__u32</entry> | ||
141 | <entry><structfield>reserved</structfield>[4]</entry> | ||
142 | <entry>Reserved for future extensions. Drivers and | ||
143 | applications must set the array to zero.</entry> | ||
144 | </row> | ||
145 | </tbody> | ||
146 | </tgroup> | ||
147 | </table> | ||
148 | |||
149 | <table pgwide="1" frame="none" id="modulator-txsubchans"> | ||
150 | <title>Modulator Audio Transmission Flags</title> | ||
151 | <tgroup cols="3"> | ||
152 | &cs-def; | ||
153 | <tbody valign="top"> | ||
154 | <row> | ||
155 | <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry> | ||
156 | <entry>0x0001</entry> | ||
157 | <entry>Modulate channel 1 as mono audio, when the input | ||
158 | has more channels, a down-mix of channel 1 and 2. This flag does not | ||
159 | combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or | ||
160 | <constant>V4L2_TUNER_SUB_LANG1</constant>.</entry> | ||
161 | </row> | ||
162 | <row> | ||
163 | <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry> | ||
164 | <entry>0x0002</entry> | ||
165 | <entry>Modulate channel 1 and 2 as left and right | ||
166 | channel of a stereo audio signal. When the input has only one channel | ||
167 | or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also | ||
168 | set, channel 1 is encoded as left and right channel. This flag does | ||
169 | not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or | ||
170 | <constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not | ||
171 | support stereo audio it shall fall back to mono.</entry> | ||
172 | </row> | ||
173 | <row> | ||
174 | <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry> | ||
175 | <entry>0x0008</entry> | ||
176 | <entry>Modulate channel 1 and 2 as primary and secondary | ||
177 | language of a bilingual audio signal. When the input has only one | ||
178 | channel it is used for both languages. It is not possible to encode | ||
179 | the primary or secondary language only. This flag does not combine | ||
180 | with <constant>V4L2_TUNER_SUB_MONO</constant>, | ||
181 | <constant>V4L2_TUNER_SUB_STEREO</constant> or | ||
182 | <constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not | ||
183 | support the respective audio matrix, or the current video standard | ||
184 | does not permit bilingual audio the | ||
185 | <constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL; | ||
186 | and the driver shall fall back to mono or stereo mode.</entry> | ||
187 | </row> | ||
188 | <row> | ||
189 | <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry> | ||
190 | <entry>0x0004</entry> | ||
191 | <entry>Same effect as | ||
192 | <constant>V4L2_TUNER_SUB_SAP</constant>.</entry> | ||
193 | </row> | ||
194 | <row> | ||
195 | <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry> | ||
196 | <entry>0x0004</entry> | ||
197 | <entry>When combined with <constant>V4L2_TUNER_SUB_MONO | ||
198 | </constant> the first channel is encoded as mono audio, the last | ||
199 | channel as Second Audio Program. When the input has only one channel | ||
200 | it is used for both audio tracks. When the input has three channels | ||
201 | the mono track is a down-mix of channel 1 and 2. When combined with | ||
202 | <constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are | ||
203 | encoded as left and right stereo audio, channel 3 as Second Audio | ||
204 | Program. When the input has only two channels, the first is encoded as | ||
205 | left and right channel and the second as SAP. When the input has only | ||
206 | one channel it is used for all audio tracks. It is not possible to | ||
207 | encode a Second Audio Program only. This flag must combine with | ||
208 | <constant>V4L2_TUNER_SUB_MONO</constant> or | ||
209 | <constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not | ||
210 | support the respective audio matrix, or the current video standard | ||
211 | does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl | ||
212 | shall return an &EINVAL; and driver shall fall back to mono or stereo | ||
213 | mode.</entry> | ||
214 | </row> | ||
215 | <row> | ||
216 | <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry> | ||
217 | <entry>0x0010</entry> | ||
218 | <entry>Enable the RDS encoder for a radio FM transmitter.</entry> | ||
219 | </row> | ||
220 | </tbody> | ||
221 | </tgroup> | ||
222 | </table> | ||
223 | </refsect1> | ||
224 | |||
225 | <refsect1> | ||
226 | &return-value; | ||
227 | |||
228 | <variablelist> | ||
229 | <varlistentry> | ||
230 | <term><errorcode>EINVAL</errorcode></term> | ||
231 | <listitem> | ||
232 | <para>The &v4l2-modulator; | ||
233 | <structfield>index</structfield> is out of bounds.</para> | ||
234 | </listitem> | ||
235 | </varlistentry> | ||
236 | </variablelist> | ||
237 | </refsect1> | ||
238 | </refentry> | ||
239 | |||
240 | <!-- | ||
241 | Local Variables: | ||
242 | mode: sgml | ||
243 | sgml-parent-document: "v4l2.sgml" | ||
244 | indent-tabs-mode: nil | ||
245 | End: | ||
246 | --> | ||