Doug / smarc-fsl-linux-kernel | Embedian Git Server

Commit c94bed8e1960587d3d93664b11ebf22677c1a541

Authored by Masanari Iida 2012-04-09 23:22:13 +0800

Committed by Jiri Kosina 2012-04-16 20:37:13 +0800

Exists in smarc-l5.0.0_1.0.0-ga and in 5 other branches

Documentation: Fix typo in multiple files in Documentation

Correct multiple spelling typo in Documentation.

Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Acked-by: Rob Landley <rob@landley.net>
Reported-by: Anders Larsen <al@alarsen.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>

Showing 16 changed files with 33 additions and 33 deletions Inline Diff

Documentation/ABI/testing/sysfs-bus-usb
Documentation/DocBook/kernel-hacking.tmpl
Documentation/DocBook/libata.tmpl
Documentation/DocBook/media/v4l/controls.xml
Documentation/blackfin/bfin-gpio-notes.txt
Documentation/devicetree/bindings/net/can/fsl-flexcan.txt
Documentation/dvb/opera-firmware.txt
Documentation/edac.txt
Documentation/filesystems/nfs/pnfs.txt
Documentation/filesystems/qnx6.txt
Documentation/hwmon/it87
Documentation/memory-hotplug.txt
Documentation/networking/can.txt
Documentation/parisc/debugging
Documentation/sound/alsa/compress_offload.txt
Documentation/static-keys.txt

Documentation/ABI/testing/sysfs-bus-usb

Diff comments View file @ c94bed8

Documentation/DocBook/kernel-hacking.tmpl

Diff comments View file @ c94bed8

1	<?xml version="1.0" encoding="UTF-8"?>	1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"	2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>	3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4		4
5	<book id="lk-hacking-guide">	5	<book id="lk-hacking-guide">
6	<bookinfo>	6	<bookinfo>
7	<title>Unreliable Guide To Hacking The Linux Kernel</title>	7	<title>Unreliable Guide To Hacking The Linux Kernel</title>
8		8
9	<authorgroup>	9	<authorgroup>
10	<author>	10	<author>
11	<firstname>Rusty</firstname>	11	<firstname>Rusty</firstname>
12	<surname>Russell</surname>	12	<surname>Russell</surname>
13	<affiliation>	13	<affiliation>
14	<address>	14	<address>
15	<email>rusty@rustcorp.com.au</email>	15	<email>rusty@rustcorp.com.au</email>
16	</address>	16	</address>
17	</affiliation>	17	</affiliation>
18	</author>	18	</author>
19	</authorgroup>	19	</authorgroup>
20		20
21	<copyright>	21	<copyright>
22	<year>2005</year>	22	<year>2005</year>
23	<holder>Rusty Russell</holder>	23	<holder>Rusty Russell</holder>
24	</copyright>	24	</copyright>
25		25
26	<legalnotice>	26	<legalnotice>
27	<para>	27	<para>
28	This documentation is free software; you can redistribute	28	This documentation is free software; you can redistribute
29	it and/or modify it under the terms of the GNU General Public	29	it and/or modify it under the terms of the GNU General Public
30	License as published by the Free Software Foundation; either	30	License as published by the Free Software Foundation; either
31	version 2 of the License, or (at your option) any later	31	version 2 of the License, or (at your option) any later
32	version.	32	version.
33	</para>	33	</para>
34		34
35	<para>	35	<para>
36	This program is distributed in the hope that it will be	36	This program is distributed in the hope that it will be
37	useful, but WITHOUT ANY WARRANTY; without even the implied	37	useful, but WITHOUT ANY WARRANTY; without even the implied
38	warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	38	warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
39	See the GNU General Public License for more details.	39	See the GNU General Public License for more details.
40	</para>	40	</para>
41		41
42	<para>	42	<para>
43	You should have received a copy of the GNU General Public	43	You should have received a copy of the GNU General Public
44	License along with this program; if not, write to the Free	44	License along with this program; if not, write to the Free
45	Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,	45	Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
46	MA 02111-1307 USA	46	MA 02111-1307 USA
47	</para>	47	</para>
48		48
49	<para>	49	<para>
50	For more details see the file COPYING in the source	50	For more details see the file COPYING in the source
51	distribution of Linux.	51	distribution of Linux.
52	</para>	52	</para>
53	</legalnotice>	53	</legalnotice>
54		54
55	<releaseinfo>	55	<releaseinfo>
56	This is the first release of this document as part of the kernel tarball.	56	This is the first release of this document as part of the kernel tarball.
57	</releaseinfo>	57	</releaseinfo>
58		58
59	</bookinfo>	59	</bookinfo>
60		60
61	<toc></toc>	61	<toc></toc>
62		62
63	<chapter id="introduction">	63	<chapter id="introduction">
64	<title>Introduction</title>	64	<title>Introduction</title>
65	<para>	65	<para>
66	Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux	66	Welcome, gentle reader, to Rusty's Remarkably Unreliable Guide to Linux
67	Kernel Hacking. This document describes the common routines and	67	Kernel Hacking. This document describes the common routines and
68	general requirements for kernel code: its goal is to serve as a	68	general requirements for kernel code: its goal is to serve as a
69	primer for Linux kernel development for experienced C	69	primer for Linux kernel development for experienced C
70	programmers. I avoid implementation details: that's what the	70	programmers. I avoid implementation details: that's what the
71	code is for, and I ignore whole tracts of useful routines.	71	code is for, and I ignore whole tracts of useful routines.
72	</para>	72	</para>
73	<para>	73	<para>
74	Before you read this, please understand that I never wanted to	74	Before you read this, please understand that I never wanted to
75	write this document, being grossly under-qualified, but I always	75	write this document, being grossly under-qualified, but I always
76	wanted to read it, and this was the only way. I hope it will	76	wanted to read it, and this was the only way. I hope it will
77	grow into a compendium of best practice, common starting points	77	grow into a compendium of best practice, common starting points
78	and random information.	78	and random information.
79	</para>	79	</para>
80	</chapter>	80	</chapter>
81		81
82	<chapter id="basic-players">	82	<chapter id="basic-players">
83	<title>The Players</title>	83	<title>The Players</title>
84		84
85	<para>	85	<para>
86	At any time each of the CPUs in a system can be:	86	At any time each of the CPUs in a system can be:
87	</para>	87	</para>
88		88
89	<itemizedlist>	89	<itemizedlist>
90	<listitem>	90	<listitem>
91	<para>	91	<para>
92	not associated with any process, serving a hardware interrupt;	92	not associated with any process, serving a hardware interrupt;
93	</para>	93	</para>
94	</listitem>	94	</listitem>
95		95
96	<listitem>	96	<listitem>
97	<para>	97	<para>
98	not associated with any process, serving a softirq or tasklet;	98	not associated with any process, serving a softirq or tasklet;
99	</para>	99	</para>
100	</listitem>	100	</listitem>
101		101
102	<listitem>	102	<listitem>
103	<para>	103	<para>
104	running in kernel space, associated with a process (user context);	104	running in kernel space, associated with a process (user context);
105	</para>	105	</para>
106	</listitem>	106	</listitem>
107		107
108	<listitem>	108	<listitem>
109	<para>	109	<para>
110	running a process in user space.	110	running a process in user space.
111	</para>	111	</para>
112	</listitem>	112	</listitem>
113	</itemizedlist>	113	</itemizedlist>
114		114
115	<para>	115	<para>
116	There is an ordering between these. The bottom two can preempt	116	There is an ordering between these. The bottom two can preempt
117	each other, but above that is a strict hierarchy: each can only be	117	each other, but above that is a strict hierarchy: each can only be
118	preempted by the ones above it. For example, while a softirq is	118	preempted by the ones above it. For example, while a softirq is
119	running on a CPU, no other softirq will preempt it, but a hardware	119	running on a CPU, no other softirq will preempt it, but a hardware
120	interrupt can. However, any other CPUs in the system execute	120	interrupt can. However, any other CPUs in the system execute
121	independently.	121	independently.
122	</para>	122	</para>
123		123
124	<para>	124	<para>
125	We'll see a number of ways that the user context can block	125	We'll see a number of ways that the user context can block
126	interrupts, to become truly non-preemptable.	126	interrupts, to become truly non-preemptable.
127	</para>	127	</para>
128		128
129	<sect1 id="basics-usercontext">	129	<sect1 id="basics-usercontext">
130	<title>User Context</title>	130	<title>User Context</title>
131		131
132	<para>	132	<para>
133	User context is when you are coming in from a system call or other	133	User context is when you are coming in from a system call or other
134	trap: like userspace, you can be preempted by more important tasks	134	trap: like userspace, you can be preempted by more important tasks
135	and by interrupts. You can sleep, by calling	135	and by interrupts. You can sleep, by calling
136	<function>schedule()</function>.	136	<function>schedule()</function>.
137	</para>	137	</para>
138		138
139	<note>	139	<note>
140	<para>	140	<para>
141	You are always in user context on module load and unload,	141	You are always in user context on module load and unload,
142	and on operations on the block device layer.	142	and on operations on the block device layer.
143	</para>	143	</para>
144	</note>	144	</note>
145		145
146	<para>	146	<para>
147	In user context, the <varname>current</varname> pointer (indicating	147	In user context, the <varname>current</varname> pointer (indicating
148	the task we are currently executing) is valid, and	148	the task we are currently executing) is valid, and
149	<function>in_interrupt()</function>	149	<function>in_interrupt()</function>
150	(<filename>include/linux/interrupt.h</filename>) is <returnvalue>false	150	(<filename>include/linux/interrupt.h</filename>) is <returnvalue>false
151	</returnvalue>.	151	</returnvalue>.
152	</para>	152	</para>
153		153
154	<caution>	154	<caution>
155	<para>	155	<para>
156	Beware that if you have preemption or softirqs disabled	156	Beware that if you have preemption or softirqs disabled
157	(see below), <function>in_interrupt()</function> will return a	157	(see below), <function>in_interrupt()</function> will return a
158	false positive.	158	false positive.
159	</para>	159	</para>
160	</caution>	160	</caution>
161	</sect1>	161	</sect1>
162		162
163	<sect1 id="basics-hardirqs">	163	<sect1 id="basics-hardirqs">
164	<title>Hardware Interrupts (Hard IRQs)</title>	164	<title>Hardware Interrupts (Hard IRQs)</title>
165		165
166	<para>	166	<para>
167	Timer ticks, <hardware>network cards</hardware> and	167	Timer ticks, <hardware>network cards</hardware> and
168	<hardware>keyboard</hardware> are examples of real	168	<hardware>keyboard</hardware> are examples of real
169	hardware which produce interrupts at any time. The kernel runs	169	hardware which produce interrupts at any time. The kernel runs
170	interrupt handlers, which services the hardware. The kernel	170	interrupt handlers, which services the hardware. The kernel
171	guarantees that this handler is never re-entered: if the same	171	guarantees that this handler is never re-entered: if the same
172	interrupt arrives, it is queued (or dropped). Because it	172	interrupt arrives, it is queued (or dropped). Because it
173	disables interrupts, this handler has to be fast: frequently it	173	disables interrupts, this handler has to be fast: frequently it
174	simply acknowledges the interrupt, marks a 'software interrupt'	174	simply acknowledges the interrupt, marks a 'software interrupt'
175	for execution and exits.	175	for execution and exits.
176	</para>	176	</para>
177		177
178	<para>	178	<para>
179	You can tell you are in a hardware interrupt, because	179	You can tell you are in a hardware interrupt, because
180	<function>in_irq()</function> returns <returnvalue>true</returnvalue>.	180	<function>in_irq()</function> returns <returnvalue>true</returnvalue>.
181	</para>	181	</para>
182	<caution>	182	<caution>
183	<para>	183	<para>
184	Beware that this will return a false positive if interrupts are disabled	184	Beware that this will return a false positive if interrupts are disabled
185	(see below).	185	(see below).
186	</para>	186	</para>
187	</caution>	187	</caution>
188	</sect1>	188	</sect1>
189		189
190	<sect1 id="basics-softirqs">	190	<sect1 id="basics-softirqs">
191	<title>Software Interrupt Context: Softirqs and Tasklets</title>	191	<title>Software Interrupt Context: Softirqs and Tasklets</title>
192		192
193	<para>	193	<para>
194	Whenever a system call is about to return to userspace, or a	194	Whenever a system call is about to return to userspace, or a
195	hardware interrupt handler exits, any 'software interrupts'	195	hardware interrupt handler exits, any 'software interrupts'
196	which are marked pending (usually by hardware interrupts) are	196	which are marked pending (usually by hardware interrupts) are
197	run (<filename>kernel/softirq.c</filename>).	197	run (<filename>kernel/softirq.c</filename>).
198	</para>	198	</para>
199		199
200	<para>	200	<para>
201	Much of the real interrupt handling work is done here. Early in	201	Much of the real interrupt handling work is done here. Early in
202	the transition to <acronym>SMP</acronym>, there were only 'bottom	202	the transition to <acronym>SMP</acronym>, there were only 'bottom
203	halves' (BHs), which didn't take advantage of multiple CPUs. Shortly	203	halves' (BHs), which didn't take advantage of multiple CPUs. Shortly
204	after we switched from wind-up computers made of match-sticks and snot,	204	after we switched from wind-up computers made of match-sticks and snot,
205	we abandoned this limitation and switched to 'softirqs'.	205	we abandoned this limitation and switched to 'softirqs'.
206	</para>	206	</para>
207		207
208	<para>	208	<para>
209	<filename class="headerfile">include/linux/interrupt.h</filename> lists the	209	<filename class="headerfile">include/linux/interrupt.h</filename> lists the
210	different softirqs. A very important softirq is the	210	different softirqs. A very important softirq is the
211	timer softirq (<filename	211	timer softirq (<filename
212	class="headerfile">include/linux/timer.h</filename>): you can	212	class="headerfile">include/linux/timer.h</filename>): you can
213	register to have it call functions for you in a given length of	213	register to have it call functions for you in a given length of
214	time.	214	time.
215	</para>	215	</para>
216		216
217	<para>	217	<para>
218	Softirqs are often a pain to deal with, since the same softirq	218	Softirqs are often a pain to deal with, since the same softirq
219	will run simultaneously on more than one CPU. For this reason,	219	will run simultaneously on more than one CPU. For this reason,
220	tasklets (<filename	220	tasklets (<filename
221	class="headerfile">include/linux/interrupt.h</filename>) are more	221	class="headerfile">include/linux/interrupt.h</filename>) are more
222	often used: they are dynamically-registrable (meaning you can have	222	often used: they are dynamically-registrable (meaning you can have
223	as many as you want), and they also guarantee that any tasklet	223	as many as you want), and they also guarantee that any tasklet
224	will only run on one CPU at any time, although different tasklets	224	will only run on one CPU at any time, although different tasklets
225	can run simultaneously.	225	can run simultaneously.
226	</para>	226	</para>
227	<caution>	227	<caution>
228	<para>	228	<para>
229	The name 'tasklet' is misleading: they have nothing to do with 'tasks',	229	The name 'tasklet' is misleading: they have nothing to do with 'tasks',
230	and probably more to do with some bad vodka Alexey Kuznetsov had at the	230	and probably more to do with some bad vodka Alexey Kuznetsov had at the
231	time.	231	time.
232	</para>	232	</para>
233	</caution>	233	</caution>
234		234
235	<para>	235	<para>
236	You can tell you are in a softirq (or tasklet)	236	You can tell you are in a softirq (or tasklet)
237	using the <function>in_softirq()</function> macro	237	using the <function>in_softirq()</function> macro
238	(<filename class="headerfile">include/linux/interrupt.h</filename>).	238	(<filename class="headerfile">include/linux/interrupt.h</filename>).
239	</para>	239	</para>
240	<caution>	240	<caution>
241	<para>	241	<para>
242	Beware that this will return a false positive if a bh lock (see below)	242	Beware that this will return a false positive if a bh lock (see below)
243	is held.	243	is held.
244	</para>	244	</para>
245	</caution>	245	</caution>
246	</sect1>	246	</sect1>
247	</chapter>	247	</chapter>
248		248
249	<chapter id="basic-rules">	249	<chapter id="basic-rules">
250	<title>Some Basic Rules</title>	250	<title>Some Basic Rules</title>
251		251
252	<variablelist>	252	<variablelist>
253	<varlistentry>	253	<varlistentry>
254	<term>No memory protection</term>	254	<term>No memory protection</term>
255	<listitem>	255	<listitem>
256	<para>	256	<para>
257	If you corrupt memory, whether in user context or	257	If you corrupt memory, whether in user context or
258	interrupt context, the whole machine will crash. Are you	258	interrupt context, the whole machine will crash. Are you
259	sure you can't do what you want in userspace?	259	sure you can't do what you want in userspace?
260	</para>	260	</para>
261	</listitem>	261	</listitem>
262	</varlistentry>	262	</varlistentry>
263		263
264	<varlistentry>	264	<varlistentry>
265	<term>No floating point or <acronym>MMX</acronym></term>	265	<term>No floating point or <acronym>MMX</acronym></term>
266	<listitem>	266	<listitem>
267	<para>	267	<para>
268	The <acronym>FPU</acronym> context is not saved; even in user	268	The <acronym>FPU</acronym> context is not saved; even in user
269	context the <acronym>FPU</acronym> state probably won't	269	context the <acronym>FPU</acronym> state probably won't
270	correspond with the current process: you would mess with some	270	correspond with the current process: you would mess with some
271	user process' <acronym>FPU</acronym> state. If you really want	271	user process' <acronym>FPU</acronym> state. If you really want
272	to do this, you would have to explicitly save/restore the full	272	to do this, you would have to explicitly save/restore the full
273	<acronym>FPU</acronym> state (and avoid context switches). It	273	<acronym>FPU</acronym> state (and avoid context switches). It
274	is generally a bad idea; use fixed point arithmetic first.	274	is generally a bad idea; use fixed point arithmetic first.
275	</para>	275	</para>
276	</listitem>	276	</listitem>
277	</varlistentry>	277	</varlistentry>
278		278
279	<varlistentry>	279	<varlistentry>
280	<term>A rigid stack limit</term>	280	<term>A rigid stack limit</term>
281	<listitem>	281	<listitem>
282	<para>	282	<para>
283	Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's	283	Depending on configuration options the kernel stack is about 3K to 6K for most 32-bit architectures: it's
284	about 14K on most 64-bit archs, and often shared with interrupts	284	about 14K on most 64-bit archs, and often shared with interrupts
285	so you can't use it all. Avoid deep recursion and huge local	285	so you can't use it all. Avoid deep recursion and huge local
286	arrays on the stack (allocate them dynamically instead).	286	arrays on the stack (allocate them dynamically instead).
287	</para>	287	</para>
288	</listitem>	288	</listitem>
289	</varlistentry>	289	</varlistentry>
290		290
291	<varlistentry>	291	<varlistentry>
292	<term>The Linux kernel is portable</term>	292	<term>The Linux kernel is portable</term>
293	<listitem>	293	<listitem>
294	<para>	294	<para>
295	Let's keep it that way. Your code should be 64-bit clean,	295	Let's keep it that way. Your code should be 64-bit clean,
296	and endian-independent. You should also minimize CPU	296	and endian-independent. You should also minimize CPU
297	specific stuff, e.g. inline assembly should be cleanly	297	specific stuff, e.g. inline assembly should be cleanly
298	encapsulated and minimized to ease porting. Generally it	298	encapsulated and minimized to ease porting. Generally it
299	should be restricted to the architecture-dependent part of	299	should be restricted to the architecture-dependent part of
300	the kernel tree.	300	the kernel tree.
301	</para>	301	</para>
302	</listitem>	302	</listitem>
303	</varlistentry>	303	</varlistentry>
304	</variablelist>	304	</variablelist>
305	</chapter>	305	</chapter>
306		306
307	<chapter id="ioctls">	307	<chapter id="ioctls">
308	<title>ioctls: Not writing a new system call</title>	308	<title>ioctls: Not writing a new system call</title>
309		309
310	<para>	310	<para>
311	A system call generally looks like this	311	A system call generally looks like this
312	</para>	312	</para>
313		313
314	<programlisting>	314	<programlisting>
315	asmlinkage long sys_mycall(int arg)	315	asmlinkage long sys_mycall(int arg)
316	{	316	{
317	return 0;	317	return 0;
318	}	318	}
319	</programlisting>	319	</programlisting>
320		320
321	<para>	321	<para>
322	First, in most cases you don't want to create a new system call.	322	First, in most cases you don't want to create a new system call.
323	You create a character device and implement an appropriate ioctl	323	You create a character device and implement an appropriate ioctl
324	for it. This is much more flexible than system calls, doesn't have	324	for it. This is much more flexible than system calls, doesn't have
325	to be entered in every architecture's	325	to be entered in every architecture's
326	<filename class="headerfile">include/asm/unistd.h</filename> and	326	<filename class="headerfile">include/asm/unistd.h</filename> and
327	<filename>arch/kernel/entry.S</filename> file, and is much more	327	<filename>arch/kernel/entry.S</filename> file, and is much more
328	likely to be accepted by Linus.	328	likely to be accepted by Linus.
329	</para>	329	</para>
330		330
331	<para>	331	<para>
332	If all your routine does is read or write some parameter, consider	332	If all your routine does is read or write some parameter, consider
333	implementing a <function>sysfs</function> interface instead.	333	implementing a <function>sysfs</function> interface instead.
334	</para>	334	</para>
335		335
336	<para>	336	<para>
337	Inside the ioctl you're in user context to a process. When a	337	Inside the ioctl you're in user context to a process. When a
338	error occurs you return a negated errno (see	338	error occurs you return a negated errno (see
339	<filename class="headerfile">include/linux/errno.h</filename>),	339	<filename class="headerfile">include/linux/errno.h</filename>),
340	otherwise you return <returnvalue>0</returnvalue>.	340	otherwise you return <returnvalue>0</returnvalue>.
341	</para>	341	</para>
342		342
343	<para>	343	<para>
344	After you slept you should check if a signal occurred: the	344	After you slept you should check if a signal occurred: the
345	Unix/Linux way of handling signals is to temporarily exit the	345	Unix/Linux way of handling signals is to temporarily exit the
346	system call with the <constant>-ERESTARTSYS</constant> error. The	346	system call with the <constant>-ERESTARTSYS</constant> error. The
347	system call entry code will switch back to user context, process	347	system call entry code will switch back to user context, process
348	the signal handler and then your system call will be restarted	348	the signal handler and then your system call will be restarted
349	(unless the user disabled that). So you should be prepared to	349	(unless the user disabled that). So you should be prepared to
350	process the restart, e.g. if you're in the middle of manipulating	350	process the restart, e.g. if you're in the middle of manipulating
351	some data structure.	351	some data structure.
352	</para>	352	</para>
353		353
354	<programlisting>	354	<programlisting>
355	if (signal_pending(current))	355	if (signal_pending(current))
356	return -ERESTARTSYS;	356	return -ERESTARTSYS;
357	</programlisting>	357	</programlisting>
358		358
359	<para>	359	<para>
360	If you're doing longer computations: first think userspace. If you	360	If you're doing longer computations: first think userspace. If you
361	<emphasis>really</emphasis> want to do it in kernel you should	361	<emphasis>really</emphasis> want to do it in kernel you should
362	regularly check if you need to give up the CPU (remember there is	362	regularly check if you need to give up the CPU (remember there is
363	cooperative multitasking per CPU). Idiom:	363	cooperative multitasking per CPU). Idiom:
364	</para>	364	</para>
365		365
366	<programlisting>	366	<programlisting>
367	cond_resched(); /* Will sleep */	367	cond_resched(); /* Will sleep */
368	</programlisting>	368	</programlisting>
369		369
370	<para>	370	<para>
371	A short note on interface design: the UNIX system call motto is	371	A short note on interface design: the UNIX system call motto is
372	"Provide mechanism not policy".	372	"Provide mechanism not policy".
373	</para>	373	</para>
374	</chapter>	374	</chapter>
375		375
376	<chapter id="deadlock-recipes">	376	<chapter id="deadlock-recipes">
377	<title>Recipes for Deadlock</title>	377	<title>Recipes for Deadlock</title>
378		378
379	<para>	379	<para>
380	You cannot call any routines which may sleep, unless:	380	You cannot call any routines which may sleep, unless:
381	</para>	381	</para>
382	<itemizedlist>	382	<itemizedlist>
383	<listitem>	383	<listitem>
384	<para>	384	<para>
385	You are in user context.	385	You are in user context.
386	</para>	386	</para>
387	</listitem>	387	</listitem>
388		388
389	<listitem>	389	<listitem>
390	<para>	390	<para>
391	You do not own any spinlocks.	391	You do not own any spinlocks.
392	</para>	392	</para>
393	</listitem>	393	</listitem>
394		394
395	<listitem>	395	<listitem>
396	<para>	396	<para>
397	You have interrupts enabled (actually, Andi Kleen says	397	You have interrupts enabled (actually, Andi Kleen says
398	that the scheduling code will enable them for you, but	398	that the scheduling code will enable them for you, but
399	that's probably not what you wanted).	399	that's probably not what you wanted).
400	</para>	400	</para>
401	</listitem>	401	</listitem>
402	</itemizedlist>	402	</itemizedlist>
403		403
404	<para>	404	<para>
405	Note that some functions may sleep implicitly: common ones are	405	Note that some functions may sleep implicitly: common ones are
406	the user space access functions (*_user) and memory allocation	406	the user space access functions (*_user) and memory allocation
407	functions without <symbol>GFP_ATOMIC</symbol>.	407	functions without <symbol>GFP_ATOMIC</symbol>.
408	</para>	408	</para>
409		409
410	<para>	410	<para>
411	You should always compile your kernel	411	You should always compile your kernel
412	<symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn	412	<symbol>CONFIG_DEBUG_ATOMIC_SLEEP</symbol> on, and it will warn
413	you if you break these rules. If you <emphasis>do</emphasis> break	413	you if you break these rules. If you <emphasis>do</emphasis> break
414	the rules, you will eventually lock up your box.	414	the rules, you will eventually lock up your box.
415	</para>	415	</para>
416		416
417	<para>	417	<para>
418	Really.	418	Really.
419	</para>	419	</para>
420	</chapter>	420	</chapter>
421		421
422	<chapter id="common-routines">	422	<chapter id="common-routines">
423	<title>Common Routines</title>	423	<title>Common Routines</title>
424		424
425	<sect1 id="routines-printk">	425	<sect1 id="routines-printk">
426	<title>	426	<title>
427	<function>printk()</function>	427	<function>printk()</function>
428	<filename class="headerfile">include/linux/kernel.h</filename>	428	<filename class="headerfile">include/linux/kernel.h</filename>
429	</title>	429	</title>
430		430
431	<para>	431	<para>
432	<function>printk()</function> feeds kernel messages to the	432	<function>printk()</function> feeds kernel messages to the
433	console, dmesg, and the syslog daemon. It is useful for debugging	433	console, dmesg, and the syslog daemon. It is useful for debugging
434	and reporting errors, and can be used inside interrupt context,	434	and reporting errors, and can be used inside interrupt context,
435	but use with caution: a machine which has its console flooded with	435	but use with caution: a machine which has its console flooded with
436	printk messages is unusable. It uses a format string mostly	436	printk messages is unusable. It uses a format string mostly
437	compatible with ANSI C printf, and C string concatenation to give	437	compatible with ANSI C printf, and C string concatenation to give
438	it a first "priority" argument:	438	it a first "priority" argument:
439	</para>	439	</para>
440		440
441	<programlisting>	441	<programlisting>
442	printk(KERN_INFO "i = %u\n", i);	442	printk(KERN_INFO "i = %u\n", i);
443	</programlisting>	443	</programlisting>
444		444
445	<para>	445	<para>
446	See <filename class="headerfile">include/linux/kernel.h</filename>;	446	See <filename class="headerfile">include/linux/kernel.h</filename>;
447	for other KERN_ values; these are interpreted by syslog as the	447	for other KERN_ values; these are interpreted by syslog as the
448	level. Special case: for printing an IP address use	448	level. Special case: for printing an IP address use
449	</para>	449	</para>
450		450
451	<programlisting>	451	<programlisting>
452	__be32 ipaddress;	452	__be32 ipaddress;
453	printk(KERN_INFO "my ip: %pI4\n", &ipaddress);	453	printk(KERN_INFO "my ip: %pI4\n", &ipaddress);
454	</programlisting>	454	</programlisting>
455		455
456	<para>	456	<para>
457	<function>printk()</function> internally uses a 1K buffer and does	457	<function>printk()</function> internally uses a 1K buffer and does
458	not catch overruns. Make sure that will be enough.	458	not catch overruns. Make sure that will be enough.
459	</para>	459	</para>
460		460
461	<note>	461	<note>
462	<para>	462	<para>
463	You will know when you are a real kernel hacker	463	You will know when you are a real kernel hacker
464	when you start typoing printf as printk in your user programs :)	464	when you start typoing printf as printk in your user programs :)
465	</para>	465	</para>
466	</note>	466	</note>
467		467
468	<!--- From the Lions book reader department -->	468	<!--- From the Lions book reader department -->
469		469
470	<note>	470	<note>
471	<para>	471	<para>
472	Another sidenote: the original Unix Version 6 sources had a	472	Another sidenote: the original Unix Version 6 sources had a
473	comment on top of its printf function: "Printf should not be	473	comment on top of its printf function: "Printf should not be
474	used for chit-chat". You should follow that advice.	474	used for chit-chat". You should follow that advice.
475	</para>	475	</para>
476	</note>	476	</note>
477	</sect1>	477	</sect1>
478		478
479	<sect1 id="routines-copy">	479	<sect1 id="routines-copy">
480	<title>	480	<title>
481	<function>copy_[to/from]_user()</function>	481	<function>copy_[to/from]_user()</function>
482	/	482	/
483	<function>get_user()</function>	483	<function>get_user()</function>
484	/	484	/
485	<function>put_user()</function>	485	<function>put_user()</function>
486	<filename class="headerfile">include/asm/uaccess.h</filename>	486	<filename class="headerfile">include/asm/uaccess.h</filename>
487	</title>	487	</title>
488		488
489	<para>	489	<para>
490	<emphasis>[SLEEPS]</emphasis>	490	<emphasis>[SLEEPS]</emphasis>
491	</para>	491	</para>
492		492
493	<para>	493	<para>
494	<function>put_user()</function> and <function>get_user()</function>	494	<function>put_user()</function> and <function>get_user()</function>
495	are used to get and put single values (such as an int, char, or	495	are used to get and put single values (such as an int, char, or
496	long) from and to userspace. A pointer into userspace should	496	long) from and to userspace. A pointer into userspace should
497	never be simply dereferenced: data should be copied using these	497	never be simply dereferenced: data should be copied using these
498	routines. Both return <constant>-EFAULT</constant> or 0.	498	routines. Both return <constant>-EFAULT</constant> or 0.
499	</para>	499	</para>
500	<para>	500	<para>
501	<function>copy_to_user()</function> and	501	<function>copy_to_user()</function> and
502	<function>copy_from_user()</function> are more general: they copy	502	<function>copy_from_user()</function> are more general: they copy
503	an arbitrary amount of data to and from userspace.	503	an arbitrary amount of data to and from userspace.
504	<caution>	504	<caution>
505	<para>	505	<para>
506	Unlike <function>put_user()</function> and	506	Unlike <function>put_user()</function> and
507	<function>get_user()</function>, they return the amount of	507	<function>get_user()</function>, they return the amount of
508	uncopied data (ie. <returnvalue>0</returnvalue> still means	508	uncopied data (ie. <returnvalue>0</returnvalue> still means
509	success).	509	success).
510	</para>	510	</para>
511	</caution>	511	</caution>
512	[Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.]	512	[Yes, this moronic interface makes me cringe. The flamewar comes up every year or so. --RR.]
513	</para>	513	</para>
514	<para>	514	<para>
515	The functions may sleep implicitly. This should never be called	515	The functions may sleep implicitly. This should never be called
516	outside user context (it makes no sense), with interrupts	516	outside user context (it makes no sense), with interrupts
517	disabled, or a spinlock held.	517	disabled, or a spinlock held.
518	</para>	518	</para>
519	</sect1>	519	</sect1>
520		520
521	<sect1 id="routines-kmalloc">	521	<sect1 id="routines-kmalloc">
522	<title><function>kmalloc()</function>/<function>kfree()</function>	522	<title><function>kmalloc()</function>/<function>kfree()</function>
523	<filename class="headerfile">include/linux/slab.h</filename></title>	523	<filename class="headerfile">include/linux/slab.h</filename></title>
524		524
525	<para>	525	<para>
526	<emphasis>[MAY SLEEP: SEE BELOW]</emphasis>	526	<emphasis>[MAY SLEEP: SEE BELOW]</emphasis>
527	</para>	527	</para>
528		528
529	<para>	529	<para>
530	These routines are used to dynamically request pointer-aligned	530	These routines are used to dynamically request pointer-aligned
531	chunks of memory, like malloc and free do in userspace, but	531	chunks of memory, like malloc and free do in userspace, but
532	<function>kmalloc()</function> takes an extra flag word.	532	<function>kmalloc()</function> takes an extra flag word.
533	Important values:	533	Important values:
534	</para>	534	</para>
535		535
536	<variablelist>	536	<variablelist>
537	<varlistentry>	537	<varlistentry>
538	<term>	538	<term>
539	<constant>	539	<constant>
540	GFP_KERNEL	540	GFP_KERNEL
541	</constant>	541	</constant>
542	</term>	542	</term>
543	<listitem>	543	<listitem>
544	<para>	544	<para>
545	May sleep and swap to free memory. Only allowed in user	545	May sleep and swap to free memory. Only allowed in user
546	context, but is the most reliable way to allocate memory.	546	context, but is the most reliable way to allocate memory.
547	</para>	547	</para>
548	</listitem>	548	</listitem>
549	</varlistentry>	549	</varlistentry>
550		550
551	<varlistentry>	551	<varlistentry>
552	<term>	552	<term>
553	<constant>	553	<constant>
554	GFP_ATOMIC	554	GFP_ATOMIC
555	</constant>	555	</constant>
556	</term>	556	</term>
557	<listitem>	557	<listitem>
558	<para>	558	<para>
559	Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>,	559	Don't sleep. Less reliable than <constant>GFP_KERNEL</constant>,
560	but may be called from interrupt context. You should	560	but may be called from interrupt context. You should
561	<emphasis>really</emphasis> have a good out-of-memory	561	<emphasis>really</emphasis> have a good out-of-memory
562	error-handling strategy.	562	error-handling strategy.
563	</para>	563	</para>
564	</listitem>	564	</listitem>
565	</varlistentry>	565	</varlistentry>
566		566
567	<varlistentry>	567	<varlistentry>
568	<term>	568	<term>
569	<constant>	569	<constant>
570	GFP_DMA	570	GFP_DMA
571	</constant>	571	</constant>
572	</term>	572	</term>
573	<listitem>	573	<listitem>
574	<para>	574	<para>
575	Allocate ISA DMA lower than 16MB. If you don't know what that	575	Allocate ISA DMA lower than 16MB. If you don't know what that
576	is you don't need it. Very unreliable.	576	is you don't need it. Very unreliable.
577	</para>	577	</para>
578	</listitem>	578	</listitem>
579	</varlistentry>	579	</varlistentry>
580	</variablelist>	580	</variablelist>
581		581
582	<para>	582	<para>
583	If you see a <errorname>sleeping function called from invalid	583	If you see a <errorname>sleeping function called from invalid
584	context</errorname> warning message, then maybe you called a	584	context</errorname> warning message, then maybe you called a
585	sleeping allocation function from interrupt context without	585	sleeping allocation function from interrupt context without
586	<constant>GFP_ATOMIC</constant>. You should really fix that.	586	<constant>GFP_ATOMIC</constant>. You should really fix that.
587	Run, don't walk.	587	Run, don't walk.
588	</para>	588	</para>
589		589
590	<para>	590	<para>
591	If you are allocating at least <constant>PAGE_SIZE</constant>	591	If you are allocating at least <constant>PAGE_SIZE</constant>
592	(<filename class="headerfile">include/asm/page.h</filename>) bytes,	592	(<filename class="headerfile">include/asm/page.h</filename>) bytes,
593	consider using <function>__get_free_pages()</function>	593	consider using <function>__get_free_pages()</function>
594		594
595	(<filename class="headerfile">include/linux/mm.h</filename>). It	595	(<filename class="headerfile">include/linux/mm.h</filename>). It
596	takes an order argument (0 for page sized, 1 for double page, 2	596	takes an order argument (0 for page sized, 1 for double page, 2
597	for four pages etc.) and the same memory priority flag word as	597	for four pages etc.) and the same memory priority flag word as
598	above.	598	above.
599	</para>	599	</para>
600		600
601	<para>	601	<para>
602	If you are allocating more than a page worth of bytes you can use	602	If you are allocating more than a page worth of bytes you can use
603	<function>vmalloc()</function>. It'll allocate virtual memory in	603	<function>vmalloc()</function>. It'll allocate virtual memory in
604	the kernel map. This block is not contiguous in physical memory,	604	the kernel map. This block is not contiguous in physical memory,
605	but the <acronym>MMU</acronym> makes it look like it is for you	605	but the <acronym>MMU</acronym> makes it look like it is for you
606	(so it'll only look contiguous to the CPUs, not to external device	606	(so it'll only look contiguous to the CPUs, not to external device
607	drivers). If you really need large physically contiguous memory	607	drivers). If you really need large physically contiguous memory
608	for some weird device, you have a problem: it is poorly supported	608	for some weird device, you have a problem: it is poorly supported
609	in Linux because after some time memory fragmentation in a running	609	in Linux because after some time memory fragmentation in a running
610	kernel makes it hard. The best way is to allocate the block early	610	kernel makes it hard. The best way is to allocate the block early
611	in the boot process via the <function>alloc_bootmem()</function>	611	in the boot process via the <function>alloc_bootmem()</function>
612	routine.	612	routine.
613	</para>	613	</para>
614		614
615	<para>	615	<para>
616	Before inventing your own cache of often-used objects consider	616	Before inventing your own cache of often-used objects consider
617	using a slab cache in	617	using a slab cache in
618	<filename class="headerfile">include/linux/slab.h</filename>	618	<filename class="headerfile">include/linux/slab.h</filename>
619	</para>	619	</para>
620	</sect1>	620	</sect1>
621		621
622	<sect1 id="routines-current">	622	<sect1 id="routines-current">
623	<title><function>current</function>	623	<title><function>current</function>
624	<filename class="headerfile">include/asm/current.h</filename></title>	624	<filename class="headerfile">include/asm/current.h</filename></title>
625		625
626	<para>	626	<para>
627	This global variable (really a macro) contains a pointer to	627	This global variable (really a macro) contains a pointer to
628	the current task structure, so is only valid in user context.	628	the current task structure, so is only valid in user context.
629	For example, when a process makes a system call, this will	629	For example, when a process makes a system call, this will
630	point to the task structure of the calling process. It is	630	point to the task structure of the calling process. It is
631	<emphasis>not NULL</emphasis> in interrupt context.	631	<emphasis>not NULL</emphasis> in interrupt context.
632	</para>	632	</para>
633	</sect1>	633	</sect1>
634		634
635	<sect1 id="routines-udelay">	635	<sect1 id="routines-udelay">
636	<title><function>mdelay()</function>/<function>udelay()</function>	636	<title><function>mdelay()</function>/<function>udelay()</function>
637	<filename class="headerfile">include/asm/delay.h</filename>	637	<filename class="headerfile">include/asm/delay.h</filename>
638	<filename class="headerfile">include/linux/delay.h</filename>	638	<filename class="headerfile">include/linux/delay.h</filename>
639	</title>	639	</title>
640		640
641	<para>	641	<para>
642	The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses.	642	The <function>udelay()</function> and <function>ndelay()</function> functions can be used for small pauses.
643	Do not use large values with them as you risk	643	Do not use large values with them as you risk
644	overflow - the helper function <function>mdelay()</function> is useful	644	overflow - the helper function <function>mdelay()</function> is useful
645	here, or consider <function>msleep()</function>.	645	here, or consider <function>msleep()</function>.
646	</para>	646	</para>
647	</sect1>	647	</sect1>
648		648
649	<sect1 id="routines-endian">	649	<sect1 id="routines-endian">
650	<title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function>	650	<title><function>cpu_to_be32()</function>/<function>be32_to_cpu()</function>/<function>cpu_to_le32()</function>/<function>le32_to_cpu()</function>
651	<filename class="headerfile">include/asm/byteorder.h</filename>	651	<filename class="headerfile">include/asm/byteorder.h</filename>
652	</title>	652	</title>
653		653
654	<para>	654	<para>
655	The <function>cpu_to_be32()</function> family (where the "32" can	655	The <function>cpu_to_be32()</function> family (where the "32" can
656	be replaced by 64 or 16, and the "be" can be replaced by "le") are	656	be replaced by 64 or 16, and the "be" can be replaced by "le") are
657	the general way to do endian conversions in the kernel: they	657	the general way to do endian conversions in the kernel: they
658	return the converted value. All variations supply the reverse as	658	return the converted value. All variations supply the reverse as
659	well: <function>be32_to_cpu()</function>, etc.	659	well: <function>be32_to_cpu()</function>, etc.
660	</para>	660	</para>
661		661
662	<para>	662	<para>
663	There are two major variations of these functions: the pointer	663	There are two major variations of these functions: the pointer
664	variation, such as <function>cpu_to_be32p()</function>, which take	664	variation, such as <function>cpu_to_be32p()</function>, which take
665	a pointer to the given type, and return the converted value. The	665	a pointer to the given type, and return the converted value. The
666	other variation is the "in-situ" family, such as	666	other variation is the "in-situ" family, such as
667	<function>cpu_to_be32s()</function>, which convert value referred	667	<function>cpu_to_be32s()</function>, which convert value referred
668	to by the pointer, and return void.	668	to by the pointer, and return void.
669	</para>	669	</para>
670	</sect1>	670	</sect1>
671		671
672	<sect1 id="routines-local-irqs">	672	<sect1 id="routines-local-irqs">
673	<title><function>local_irq_save()</function>/<function>local_irq_restore()</function>	673	<title><function>local_irq_save()</function>/<function>local_irq_restore()</function>
674	<filename class="headerfile">include/asm/system.h</filename>	674	<filename class="headerfile">include/asm/system.h</filename>
675	</title>	675	</title>
676		676
677	<para>	677	<para>
678	These routines disable hard interrupts on the local CPU, and	678	These routines disable hard interrupts on the local CPU, and
679	restore them. They are reentrant; saving the previous state in	679	restore them. They are reentrant; saving the previous state in
680	their one <varname>unsigned long flags</varname> argument. If you	680	their one <varname>unsigned long flags</varname> argument. If you
681	know that interrupts are enabled, you can simply use	681	know that interrupts are enabled, you can simply use
682	<function>local_irq_disable()</function> and	682	<function>local_irq_disable()</function> and
683	<function>local_irq_enable()</function>.	683	<function>local_irq_enable()</function>.
684	</para>	684	</para>
685	</sect1>	685	</sect1>
686		686
687	<sect1 id="routines-softirqs">	687	<sect1 id="routines-softirqs">
688	<title><function>local_bh_disable()</function>/<function>local_bh_enable()</function>	688	<title><function>local_bh_disable()</function>/<function>local_bh_enable()</function>
689	<filename class="headerfile">include/linux/interrupt.h</filename></title>	689	<filename class="headerfile">include/linux/interrupt.h</filename></title>
690		690
691	<para>	691	<para>
692	These routines disable soft interrupts on the local CPU, and	692	These routines disable soft interrupts on the local CPU, and
693	restore them. They are reentrant; if soft interrupts were	693	restore them. They are reentrant; if soft interrupts were
694	disabled before, they will still be disabled after this pair	694	disabled before, they will still be disabled after this pair
695	of functions has been called. They prevent softirqs and tasklets	695	of functions has been called. They prevent softirqs and tasklets
696	from running on the current CPU.	696	from running on the current CPU.
697	</para>	697	</para>
698	</sect1>	698	</sect1>
699		699
700	<sect1 id="routines-processorids">	700	<sect1 id="routines-processorids">
701	<title><function>smp_processor_id</function>()	701	<title><function>smp_processor_id</function>()
702	<filename class="headerfile">include/asm/smp.h</filename></title>	702	<filename class="headerfile">include/asm/smp.h</filename></title>
703		703
704	<para>	704	<para>
705	<function>get_cpu()</function> disables preemption (so you won't	705	<function>get_cpu()</function> disables preemption (so you won't
706	suddenly get moved to another CPU) and returns the current	706	suddenly get moved to another CPU) and returns the current
707	processor number, between 0 and <symbol>NR_CPUS</symbol>. Note	707	processor number, between 0 and <symbol>NR_CPUS</symbol>. Note
708	that the CPU numbers are not necessarily continuous. You return	708	that the CPU numbers are not necessarily continuous. You return
709	it again with <function>put_cpu()</function> when you are done.	709	it again with <function>put_cpu()</function> when you are done.
710	</para>	710	</para>
711	<para>	711	<para>
712	If you know you cannot be preempted by another task (ie. you are	712	If you know you cannot be preempted by another task (ie. you are
713	in interrupt context, or have preemption disabled) you can use	713	in interrupt context, or have preemption disabled) you can use
714	smp_processor_id().	714	smp_processor_id().
715	</para>	715	</para>
716	</sect1>	716	</sect1>
717		717
718	<sect1 id="routines-init">	718	<sect1 id="routines-init">
719	<title><type>__init</type>/<type>__exit</type>/<type>__initdata</type>	719	<title><type>__init</type>/<type>__exit</type>/<type>__initdata</type>
720	<filename class="headerfile">include/linux/init.h</filename></title>	720	<filename class="headerfile">include/linux/init.h</filename></title>
721		721
722	<para>	722	<para>
723	After boot, the kernel frees up a special section; functions	723	After boot, the kernel frees up a special section; functions
724	marked with <type>__init</type> and data structures marked with	724	marked with <type>__init</type> and data structures marked with
725	<type>__initdata</type> are dropped after boot is complete: similarly	725	<type>__initdata</type> are dropped after boot is complete: similarly
726	modules discard this memory after initialization. <type>__exit</type>	726	modules discard this memory after initialization. <type>__exit</type>
727	is used to declare a function which is only required on exit: the	727	is used to declare a function which is only required on exit: the
728	function will be dropped if this file is not compiled as a module.	728	function will be dropped if this file is not compiled as a module.
729	See the header file for use. Note that it makes no sense for a function	729	See the header file for use. Note that it makes no sense for a function
730	marked with <type>__init</type> to be exported to modules with	730	marked with <type>__init</type> to be exported to modules with
731	<function>EXPORT_SYMBOL()</function> - this will break.	731	<function>EXPORT_SYMBOL()</function> - this will break.
732	</para>	732	</para>
733		733
734	</sect1>	734	</sect1>
735		735
736	<sect1 id="routines-init-again">	736	<sect1 id="routines-init-again">
737	<title><function>__initcall()</function>/<function>module_init()</function>	737	<title><function>__initcall()</function>/<function>module_init()</function>
738	<filename class="headerfile">include/linux/init.h</filename></title>	738	<filename class="headerfile">include/linux/init.h</filename></title>
739	<para>	739	<para>
740	Many parts of the kernel are well served as a module	740	Many parts of the kernel are well served as a module
741	(dynamically-loadable parts of the kernel). Using the	741	(dynamically-loadable parts of the kernel). Using the
742	<function>module_init()</function> and	742	<function>module_init()</function> and
743	<function>module_exit()</function> macros it is easy to write code	743	<function>module_exit()</function> macros it is easy to write code
744	without #ifdefs which can operate both as a module or built into	744	without #ifdefs which can operate both as a module or built into
745	the kernel.	745	the kernel.
746	</para>	746	</para>
747		747
748	<para>	748	<para>
749	The <function>module_init()</function> macro defines which	749	The <function>module_init()</function> macro defines which
750	function is to be called at module insertion time (if the file is	750	function is to be called at module insertion time (if the file is
751	compiled as a module), or at boot time: if the file is not	751	compiled as a module), or at boot time: if the file is not
752	compiled as a module the <function>module_init()</function> macro	752	compiled as a module the <function>module_init()</function> macro
753	becomes equivalent to <function>__initcall()</function>, which	753	becomes equivalent to <function>__initcall()</function>, which
754	through linker magic ensures that the function is called on boot.	754	through linker magic ensures that the function is called on boot.
755	</para>	755	</para>
756		756
757	<para>	757	<para>
758	The function can return a negative error number to cause	758	The function can return a negative error number to cause
759	module loading to fail (unfortunately, this has no effect if	759	module loading to fail (unfortunately, this has no effect if
760	the module is compiled into the kernel). This function is	760	the module is compiled into the kernel). This function is
761	called in user context with interrupts enabled, so it can sleep.	761	called in user context with interrupts enabled, so it can sleep.
762	</para>	762	</para>
763	</sect1>	763	</sect1>
764		764
765	<sect1 id="routines-moduleexit">	765	<sect1 id="routines-moduleexit">
766	<title> <function>module_exit()</function>	766	<title> <function>module_exit()</function>
767	<filename class="headerfile">include/linux/init.h</filename> </title>	767	<filename class="headerfile">include/linux/init.h</filename> </title>
768		768
769	<para>	769	<para>
770	This macro defines the function to be called at module removal	770	This macro defines the function to be called at module removal
771	time (or never, in the case of the file compiled into the	771	time (or never, in the case of the file compiled into the
772	kernel). It will only be called if the module usage count has	772	kernel). It will only be called if the module usage count has
773	reached zero. This function can also sleep, but cannot fail:	773	reached zero. This function can also sleep, but cannot fail:
774	everything must be cleaned up by the time it returns.	774	everything must be cleaned up by the time it returns.
775	</para>	775	</para>
776		776
777	<para>	777	<para>
778	Note that this macro is optional: if it is not present, your	778	Note that this macro is optional: if it is not present, your
779	module will not be removable (except for 'rmmod -f').	779	module will not be removable (except for 'rmmod -f').
780	</para>	780	</para>
781	</sect1>	781	</sect1>
782		782
783	<sect1 id="routines-module-use-counters">	783	<sect1 id="routines-module-use-counters">
784	<title> <function>try_module_get()</function>/<function>module_put()</function>	784	<title> <function>try_module_get()</function>/<function>module_put()</function>
785	<filename class="headerfile">include/linux/module.h</filename></title>	785	<filename class="headerfile">include/linux/module.h</filename></title>
786		786
787	<para>	787	<para>
788	These manipulate the module usage count, to protect against	788	These manipulate the module usage count, to protect against
789	removal (a module also can't be removed if another module uses one	789	removal (a module also can't be removed if another module uses one
790	of its exported symbols: see below). Before calling into module	790	of its exported symbols: see below). Before calling into module
791	code, you should call <function>try_module_get()</function> on	791	code, you should call <function>try_module_get()</function> on
792	that module: if it fails, then the module is being removed and you	792	that module: if it fails, then the module is being removed and you
793	should act as if it wasn't there. Otherwise, you can safely enter	793	should act as if it wasn't there. Otherwise, you can safely enter
794	the module, and call <function>module_put()</function> when you're	794	the module, and call <function>module_put()</function> when you're
795	finished.	795	finished.
796	</para>	796	</para>
797		797
798	<para>	798	<para>
799	Most registerable structures have an	799	Most registerable structures have an
800	<structfield>owner</structfield> field, such as in the	800	<structfield>owner</structfield> field, such as in the
801	<structname>file_operations</structname> structure. Set this field	801	<structname>file_operations</structname> structure. Set this field
802	to the macro <symbol>THIS_MODULE</symbol>.	802	to the macro <symbol>THIS_MODULE</symbol>.
803	</para>	803	</para>
804	</sect1>	804	</sect1>
805		805
806	<!-- add info on new-style module refcounting here -->	806	<!-- add info on new-style module refcounting here -->
807	</chapter>	807	</chapter>
808		808
809	<chapter id="queues">	809	<chapter id="queues">
810	<title>Wait Queues	810	<title>Wait Queues
811	<filename class="headerfile">include/linux/wait.h</filename>	811	<filename class="headerfile">include/linux/wait.h</filename>
812	</title>	812	</title>
813	<para>	813	<para>
814	<emphasis>[SLEEPS]</emphasis>	814	<emphasis>[SLEEPS]</emphasis>
815	</para>	815	</para>
816		816
817	<para>	817	<para>
818	A wait queue is used to wait for someone to wake you up when a	818	A wait queue is used to wait for someone to wake you up when a
819	certain condition is true. They must be used carefully to ensure	819	certain condition is true. They must be used carefully to ensure
820	there is no race condition. You declare a	820	there is no race condition. You declare a
821	<type>wait_queue_head_t</type>, and then processes which want to	821	<type>wait_queue_head_t</type>, and then processes which want to
822	wait for that condition declare a <type>wait_queue_t</type>	822	wait for that condition declare a <type>wait_queue_t</type>
823	referring to themselves, and place that in the queue.	823	referring to themselves, and place that in the queue.
824	</para>	824	</para>
825		825
826	<sect1 id="queue-declaring">	826	<sect1 id="queue-declaring">
827	<title>Declaring</title>	827	<title>Declaring</title>
828		828
829	<para>	829	<para>
830	You declare a <type>wait_queue_head_t</type> using the	830	You declare a <type>wait_queue_head_t</type> using the
831	<function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the	831	<function>DECLARE_WAIT_QUEUE_HEAD()</function> macro, or using the
832	<function>init_waitqueue_head()</function> routine in your	832	<function>init_waitqueue_head()</function> routine in your
833	initialization code.	833	initialization code.
834	</para>	834	</para>
835	</sect1>	835	</sect1>
836		836
837	<sect1 id="queue-waitqueue">	837	<sect1 id="queue-waitqueue">
838	<title>Queuing</title>	838	<title>Queuing</title>
839		839
840	<para>	840	<para>
841	Placing yourself in the waitqueue is fairly complex, because you	841	Placing yourself in the waitqueue is fairly complex, because you
842	must put yourself in the queue before checking the condition.	842	must put yourself in the queue before checking the condition.
843	There is a macro to do this:	843	There is a macro to do this:
844	<function>wait_event_interruptible()</function>	844	<function>wait_event_interruptible()</function>
845		845
846	<filename class="headerfile">include/linux/wait.h</filename> The	846	<filename class="headerfile">include/linux/wait.h</filename> The
847	first argument is the wait queue head, and the second is an	847	first argument is the wait queue head, and the second is an
848	expression which is evaluated; the macro returns	848	expression which is evaluated; the macro returns
849	<returnvalue>0</returnvalue> when this expression is true, or	849	<returnvalue>0</returnvalue> when this expression is true, or
850	<returnvalue>-ERESTARTSYS</returnvalue> if a signal is received.	850	<returnvalue>-ERESTARTSYS</returnvalue> if a signal is received.
851	The <function>wait_event()</function> version ignores signals.	851	The <function>wait_event()</function> version ignores signals.
852	</para>	852	</para>
853	<para>	853	<para>
854	Do not use the <function>sleep_on()</function> function family -	854	Do not use the <function>sleep_on()</function> function family -
855	it is very easy to accidentally introduce races; almost certainly	855	it is very easy to accidentally introduce races; almost certainly
856	one of the <function>wait_event()</function> family will do, or a	856	one of the <function>wait_event()</function> family will do, or a
857	loop around <function>schedule_timeout()</function>. If you choose	857	loop around <function>schedule_timeout()</function>. If you choose
858	to loop around <function>schedule_timeout()</function> remember	858	to loop around <function>schedule_timeout()</function> remember
859	you must set the task state (with	859	you must set the task state (with
860	<function>set_current_state()</function>) on each iteration to avoid	860	<function>set_current_state()</function>) on each iteration to avoid
861	busy-looping.	861	busy-looping.
862	</para>	862	</para>
863		863
864	</sect1>	864	</sect1>
865		865
866	<sect1 id="queue-waking">	866	<sect1 id="queue-waking">
867	<title>Waking Up Queued Tasks</title>	867	<title>Waking Up Queued Tasks</title>
868		868
869	<para>	869	<para>
870	Call <function>wake_up()</function>	870	Call <function>wake_up()</function>
871		871
872	<filename class="headerfile">include/linux/wait.h</filename>;,	872	<filename class="headerfile">include/linux/wait.h</filename>;,
873	which will wake up every process in the queue. The exception is	873	which will wake up every process in the queue. The exception is
874	if one has <constant>TASK_EXCLUSIVE</constant> set, in which case	874	if one has <constant>TASK_EXCLUSIVE</constant> set, in which case
875	the remainder of the queue will not be woken. There are other variants	875	the remainder of the queue will not be woken. There are other variants
876	of this basic function available in the same header.	876	of this basic function available in the same header.
877	</para>	877	</para>
878	</sect1>	878	</sect1>
879	</chapter>	879	</chapter>
880		880
881	<chapter id="atomic-ops">	881	<chapter id="atomic-ops">
882	<title>Atomic Operations</title>	882	<title>Atomic Operations</title>
883		883
884	<para>	884	<para>
885	Certain operations are guaranteed atomic on all platforms. The	885	Certain operations are guaranteed atomic on all platforms. The
886	first class of operations work on <type>atomic_t</type>	886	first class of operations work on <type>atomic_t</type>
887		887
888	<filename class="headerfile">include/asm/atomic.h</filename>; this	888	<filename class="headerfile">include/asm/atomic.h</filename>; this
889	contains a signed integer (at least 32 bits long), and you must use	889	contains a signed integer (at least 32 bits long), and you must use
890	these functions to manipulate or read atomic_t variables.	890	these functions to manipulate or read atomic_t variables.
891	<function>atomic_read()</function> and	891	<function>atomic_read()</function> and
892	<function>atomic_set()</function> get and set the counter,	892	<function>atomic_set()</function> get and set the counter,
893	<function>atomic_add()</function>,	893	<function>atomic_add()</function>,
894	<function>atomic_sub()</function>,	894	<function>atomic_sub()</function>,
895	<function>atomic_inc()</function>,	895	<function>atomic_inc()</function>,
896	<function>atomic_dec()</function>, and	896	<function>atomic_dec()</function>, and
897	<function>atomic_dec_and_test()</function> (returns	897	<function>atomic_dec_and_test()</function> (returns
898	<returnvalue>true</returnvalue> if it was decremented to zero).	898	<returnvalue>true</returnvalue> if it was decremented to zero).
899	</para>	899	</para>
900		900
901	<para>	901	<para>
902	Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the	902	Yes. It returns <returnvalue>true</returnvalue> (i.e. != 0) if the
903	atomic variable is zero.	903	atomic variable is zero.
904	</para>	904	</para>
905		905
906	<para>	906	<para>
907	Note that these functions are slower than normal arithmetic, and	907	Note that these functions are slower than normal arithmetic, and
908	so should not be used unnecessarily.	908	so should not be used unnecessarily.
909	</para>	909	</para>
910		910
911	<para>	911	<para>
912	The second class of atomic operations is atomic bit operations on an	912	The second class of atomic operations is atomic bit operations on an
913	<type>unsigned long</type>, defined in	913	<type>unsigned long</type>, defined in
914		914
915	<filename class="headerfile">include/linux/bitops.h</filename>. These	915	<filename class="headerfile">include/linux/bitops.h</filename>. These
916	operations generally take a pointer to the bit pattern, and a bit	916	operations generally take a pointer to the bit pattern, and a bit
917	number: 0 is the least significant bit.	917	number: 0 is the least significant bit.
918	<function>set_bit()</function>, <function>clear_bit()</function>	918	<function>set_bit()</function>, <function>clear_bit()</function>
919	and <function>change_bit()</function> set, clear, and flip the	919	and <function>change_bit()</function> set, clear, and flip the
920	given bit. <function>test_and_set_bit()</function>,	920	given bit. <function>test_and_set_bit()</function>,
921	<function>test_and_clear_bit()</function> and	921	<function>test_and_clear_bit()</function> and
922	<function>test_and_change_bit()</function> do the same thing,	922	<function>test_and_change_bit()</function> do the same thing,
923	except return true if the bit was previously set; these are	923	except return true if the bit was previously set; these are
924	particularly useful for atomically setting flags.	924	particularly useful for atomically setting flags.
925	</para>	925	</para>
926		926
927	<para>	927	<para>
928	It is possible to call these operations with bit indices greater	928	It is possible to call these operations with bit indices greater
929	than BITS_PER_LONG. The resulting behavior is strange on big-endian	929	than BITS_PER_LONG. The resulting behavior is strange on big-endian
930	platforms though so it is a good idea not to do this.	930	platforms though so it is a good idea not to do this.
931	</para>	931	</para>
932	</chapter>	932	</chapter>
933		933
934	<chapter id="symbols">	934	<chapter id="symbols">
935	<title>Symbols</title>	935	<title>Symbols</title>
936		936
937	<para>	937	<para>
938	Within the kernel proper, the normal linking rules apply	938	Within the kernel proper, the normal linking rules apply
939	(ie. unless a symbol is declared to be file scope with the	939	(ie. unless a symbol is declared to be file scope with the
940	<type>static</type> keyword, it can be used anywhere in the	940	<type>static</type> keyword, it can be used anywhere in the
941	kernel). However, for modules, a special exported symbol table is	941	kernel). However, for modules, a special exported symbol table is
942	kept which limits the entry points to the kernel proper. Modules	942	kept which limits the entry points to the kernel proper. Modules
943	can also export symbols.	943	can also export symbols.
944	</para>	944	</para>
945		945
946	<sect1 id="sym-exportsymbols">	946	<sect1 id="sym-exportsymbols">
947	<title><function>EXPORT_SYMBOL()</function>	947	<title><function>EXPORT_SYMBOL()</function>
948	<filename class="headerfile">include/linux/module.h</filename></title>	948	<filename class="headerfile">include/linux/module.h</filename></title>
949		949
950	<para>	950	<para>
951	This is the classic method of exporting a symbol: dynamically	951	This is the classic method of exporting a symbol: dynamically
952	loaded modules will be able to use the symbol as normal.	952	loaded modules will be able to use the symbol as normal.
953	</para>	953	</para>
954	</sect1>	954	</sect1>
955		955
956	<sect1 id="sym-exportsymbols-gpl">	956	<sect1 id="sym-exportsymbols-gpl">
957	<title><function>EXPORT_SYMBOL_GPL()</function>	957	<title><function>EXPORT_SYMBOL_GPL()</function>
958	<filename class="headerfile">include/linux/module.h</filename></title>	958	<filename class="headerfile">include/linux/module.h</filename></title>
959		959
960	<para>	960	<para>
961	Similar to <function>EXPORT_SYMBOL()</function> except that the	961	Similar to <function>EXPORT_SYMBOL()</function> except that the
962	symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can	962	symbols exported by <function>EXPORT_SYMBOL_GPL()</function> can
963	only be seen by modules with a	963	only be seen by modules with a
964	<function>MODULE_LICENSE()</function> that specifies a GPL	964	<function>MODULE_LICENSE()</function> that specifies a GPL
965	compatible license. It implies that the function is considered	965	compatible license. It implies that the function is considered
966	an internal implementation issue, and not really an interface.	966	an internal implementation issue, and not really an interface.
967	</para>	967	</para>
968	</sect1>	968	</sect1>
969	</chapter>	969	</chapter>
970		970
971	<chapter id="conventions">	971	<chapter id="conventions">
972	<title>Routines and Conventions</title>	972	<title>Routines and Conventions</title>
973		973
974	<sect1 id="conventions-doublelinkedlist">	974	<sect1 id="conventions-doublelinkedlist">
975	<title>Double-linked lists	975	<title>Double-linked lists
976	<filename class="headerfile">include/linux/list.h</filename></title>	976	<filename class="headerfile">include/linux/list.h</filename></title>
977		977
978	<para>	978	<para>
979	There used to be three sets of linked-list routines in the kernel	979	There used to be three sets of linked-list routines in the kernel
980	headers, but this one is the winner. If you don't have some	980	headers, but this one is the winner. If you don't have some
981	particular pressing need for a single list, it's a good choice.	981	particular pressing need for a single list, it's a good choice.
982	</para>	982	</para>
983		983
984	<para>	984	<para>
985	In particular, <function>list_for_each_entry</function> is useful.	985	In particular, <function>list_for_each_entry</function> is useful.
986	</para>	986	</para>
987	</sect1>	987	</sect1>
988		988
989	<sect1 id="convention-returns">	989	<sect1 id="convention-returns">
990	<title>Return Conventions</title>	990	<title>Return Conventions</title>
991		991
992	<para>	992	<para>
993	For code called in user context, it's very common to defy C	993	For code called in user context, it's very common to defy C
994	convention, and return <returnvalue>0</returnvalue> for success,	994	convention, and return <returnvalue>0</returnvalue> for success,
995	and a negative error number	995	and a negative error number
996	(eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be	996	(eg. <returnvalue>-EFAULT</returnvalue>) for failure. This can be
997	unintuitive at first, but it's fairly widespread in the kernel.	997	unintuitive at first, but it's fairly widespread in the kernel.
998	</para>	998	</para>
999		999
1000	<para>	1000	<para>
1001	Using <function>ERR_PTR()</function>	1001	Using <function>ERR_PTR()</function>
1002		1002
1003	<filename class="headerfile">include/linux/err.h</filename>; to	1003	<filename class="headerfile">include/linux/err.h</filename>; to
1004	encode a negative error number into a pointer, and	1004	encode a negative error number into a pointer, and
1005	<function>IS_ERR()</function> and <function>PTR_ERR()</function>	1005	<function>IS_ERR()</function> and <function>PTR_ERR()</function>
1006	to get it back out again: avoids a separate pointer parameter for	1006	to get it back out again: avoids a separate pointer parameter for
1007	the error number. Icky, but in a good way.	1007	the error number. Icky, but in a good way.
1008	</para>	1008	</para>
1009	</sect1>	1009	</sect1>
1010		1010
1011	<sect1 id="conventions-borkedcompile">	1011	<sect1 id="conventions-borkedcompile">
1012	<title>Breaking Compilation</title>	1012	<title>Breaking Compilation</title>
1013		1013
1014	<para>	1014	<para>
1015	Linus and the other developers sometimes change function or	1015	Linus and the other developers sometimes change function or
1016	structure names in development kernels; this is not done just to	1016	structure names in development kernels; this is not done just to
1017	keep everyone on their toes: it reflects a fundamental change	1017	keep everyone on their toes: it reflects a fundamental change
1018	(eg. can no longer be called with interrupts on, or does extra	1018	(eg. can no longer be called with interrupts on, or does extra
1019	checks, or doesn't do checks which were caught before). Usually	1019	checks, or doesn't do checks which were caught before). Usually
1020	this is accompanied by a fairly complete note to the linux-kernel	1020	this is accompanied by a fairly complete note to the linux-kernel
1021	mailing list; search the archive. Simply doing a global replace	1021	mailing list; search the archive. Simply doing a global replace
1022	on the file usually makes things <emphasis>worse</emphasis>.	1022	on the file usually makes things <emphasis>worse</emphasis>.
1023	</para>	1023	</para>
1024	</sect1>	1024	</sect1>
1025		1025
1026	<sect1 id="conventions-initialising">	1026	<sect1 id="conventions-initialising">
1027	<title>Initializing structure members</title>	1027	<title>Initializing structure members</title>
1028		1028
1029	<para>	1029	<para>
1030	The preferred method of initializing structures is to use	1030	The preferred method of initializing structures is to use
1031	designated initialisers, as defined by ISO C99, eg:	1031	designated initialisers, as defined by ISO C99, eg:
1032	</para>	1032	</para>
1033	<programlisting>	1033	<programlisting>
1034	static struct block_device_operations opt_fops = {	1034	static struct block_device_operations opt_fops = {
1035	.open = opt_open,	1035	.open = opt_open,
1036	.release = opt_release,	1036	.release = opt_release,
1037	.ioctl = opt_ioctl,	1037	.ioctl = opt_ioctl,
1038	.check_media_change = opt_media_change,	1038	.check_media_change = opt_media_change,
1039	};	1039	};
1040	</programlisting>	1040	</programlisting>
1041	<para>	1041	<para>
1042	This makes it easy to grep for, and makes it clear which	1042	This makes it easy to grep for, and makes it clear which
1043	structure fields are set. You should do this because it looks	1043	structure fields are set. You should do this because it looks
1044	cool.	1044	cool.
1045	</para>	1045	</para>
1046	</sect1>	1046	</sect1>
1047		1047
1048	<sect1 id="conventions-gnu-extns">	1048	<sect1 id="conventions-gnu-extns">
1049	<title>GNU Extensions</title>	1049	<title>GNU Extensions</title>
1050		1050
1051	<para>	1051	<para>
1052	GNU Extensions are explicitly allowed in the Linux kernel.	1052	GNU Extensions are explicitly allowed in the Linux kernel.
1053	Note that some of the more complex ones are not very well	1053	Note that some of the more complex ones are not very well
1054	supported, due to lack of general use, but the following are	1054	supported, due to lack of general use, but the following are
1055	considered standard (see the GCC info page section "C	1055	considered standard (see the GCC info page section "C
1056	Extensions" for more details - Yes, really the info page, the	1056	Extensions" for more details - Yes, really the info page, the
1057	man page is only a short summary of the stuff in info).	1057	man page is only a short summary of the stuff in info).
1058	</para>	1058	</para>
1059	<itemizedlist>	1059	<itemizedlist>
1060	<listitem>	1060	<listitem>
1061	<para>	1061	<para>
1062	Inline functions	1062	Inline functions
1063	</para>	1063	</para>
1064	</listitem>	1064	</listitem>
1065	<listitem>	1065	<listitem>
1066	<para>	1066	<para>
1067	Statement expressions (ie. the ({ and }) constructs).	1067	Statement expressions (ie. the ({ and }) constructs).
1068	</para>	1068	</para>
1069	</listitem>	1069	</listitem>
1070	<listitem>	1070	<listitem>
1071	<para>	1071	<para>
1072	Declaring attributes of a function / variable / type	1072	Declaring attributes of a function / variable / type
1073	(__attribute__)	1073	(__attribute__)
1074	</para>	1074	</para>
1075	</listitem>	1075	</listitem>
1076	<listitem>	1076	<listitem>
1077	<para>	1077	<para>
1078	typeof	1078	typeof
1079	</para>	1079	</para>
1080	</listitem>	1080	</listitem>
1081	<listitem>	1081	<listitem>
1082	<para>	1082	<para>
1083	Zero length arrays	1083	Zero length arrays
1084	</para>	1084	</para>
1085	</listitem>	1085	</listitem>
1086	<listitem>	1086	<listitem>
1087	<para>	1087	<para>
1088	Macro varargs	1088	Macro varargs
1089	</para>	1089	</para>
1090	</listitem>	1090	</listitem>
1091	<listitem>	1091	<listitem>
1092	<para>	1092	<para>
1093	Arithmetic on void pointers	1093	Arithmetic on void pointers
1094	</para>	1094	</para>
1095	</listitem>	1095	</listitem>
1096	<listitem>	1096	<listitem>
1097	<para>	1097	<para>
1098	Non-Constant initializers	1098	Non-Constant initializers
1099	</para>	1099	</para>
1100	</listitem>	1100	</listitem>
1101	<listitem>	1101	<listitem>
1102	<para>	1102	<para>
1103	Assembler Instructions (not outside arch/ and include/asm/)	1103	Assembler Instructions (not outside arch/ and include/asm/)
1104	</para>	1104	</para>
1105	</listitem>	1105	</listitem>
1106	<listitem>	1106	<listitem>
1107	<para>	1107	<para>
1108	Function names as strings (__func__).	1108	Function names as strings (__func__).
1109	</para>	1109	</para>
1110	</listitem>	1110	</listitem>
1111	<listitem>	1111	<listitem>
1112	<para>	1112	<para>
1113	__builtin_constant_p()	1113	__builtin_constant_p()
1114	</para>	1114	</para>
1115	</listitem>	1115	</listitem>
1116	</itemizedlist>	1116	</itemizedlist>
1117		1117
1118	<para>	1118	<para>
1119	Be wary when using long long in the kernel, the code gcc generates for	1119	Be wary when using long long in the kernel, the code gcc generates for
1120	it is horrible and worse: division and multiplication does not work	1120	it is horrible and worse: division and multiplication does not work
1121	on i386 because the GCC runtime functions for it are missing from	1121	on i386 because the GCC runtime functions for it are missing from
1122	the kernel environment.	1122	the kernel environment.
1123	</para>	1123	</para>
1124		1124
1125	<!-- FIXME: add a note about ANSI aliasing cleanness -->	1125	<!-- FIXME: add a note about ANSI aliasing cleanness -->
1126	</sect1>	1126	</sect1>
1127		1127
1128	<sect1 id="conventions-cplusplus">	1128	<sect1 id="conventions-cplusplus">
1129	<title>C++</title>	1129	<title>C++</title>
1130		1130
1131	<para>	1131	<para>
1132	Using C++ in the kernel is usually a bad idea, because the	1132	Using C++ in the kernel is usually a bad idea, because the
1133	kernel does not provide the necessary runtime environment	1133	kernel does not provide the necessary runtime environment
1134	and the include files are not tested for it. It is still	1134	and the include files are not tested for it. It is still
1135	possible, but not recommended. If you really want to do	1135	possible, but not recommended. If you really want to do
1136	this, forget about exceptions at least.	1136	this, forget about exceptions at least.
1137	</para>	1137	</para>
1138	</sect1>	1138	</sect1>
1139		1139
1140	<sect1 id="conventions-ifdef">	1140	<sect1 id="conventions-ifdef">
1141	<title>&num;if</title>	1141	<title>&num;if</title>
1142		1142
1143	<para>	1143	<para>
1144	It is generally considered cleaner to use macros in header files	1144	It is generally considered cleaner to use macros in header files
1145	(or at the top of .c files) to abstract away functions rather than	1145	(or at the top of .c files) to abstract away functions rather than
1146	using `#if' pre-processor statements throughout the source code.	1146	using `#if' pre-processor statements throughout the source code.
1147	</para>	1147	</para>
1148	</sect1>	1148	</sect1>
1149	</chapter>	1149	</chapter>
1150		1150
1151	<chapter id="submitting">	1151	<chapter id="submitting">
1152	<title>Putting Your Stuff in the Kernel</title>	1152	<title>Putting Your Stuff in the Kernel</title>
1153		1153
1154	<para>	1154	<para>
1155	In order to get your stuff into shape for official inclusion, or	1155	In order to get your stuff into shape for official inclusion, or
1156	even to make a neat patch, there's administrative work to be	1156	even to make a neat patch, there's administrative work to be
1157	done:	1157	done:
1158	</para>	1158	</para>
1159	<itemizedlist>	1159	<itemizedlist>
1160	<listitem>	1160	<listitem>
1161	<para>	1161	<para>
1162	Figure out whose pond you've been pissing in. Look at the top of	1162	Figure out whose pond you've been pissing in. Look at the top of
1163	the source files, inside the <filename>MAINTAINERS</filename>	1163	the source files, inside the <filename>MAINTAINERS</filename>
1164	file, and last of all in the <filename>CREDITS</filename> file.	1164	file, and last of all in the <filename>CREDITS</filename> file.
1165	You should coordinate with this person to make sure you're not	1165	You should coordinate with this person to make sure you're not
1166	duplicating effort, or trying something that's already been	1166	duplicating effort, or trying something that's already been
1167	rejected.	1167	rejected.
1168	</para>	1168	</para>
1169		1169
1170	<para>	1170	<para>
1171	Make sure you put your name and EMail address at the top of	1171	Make sure you put your name and EMail address at the top of
1172	any files you create or mangle significantly. This is the	1172	any files you create or mangle significantly. This is the
1173	first place people will look when they find a bug, or when	1173	first place people will look when they find a bug, or when
1174	<emphasis>they</emphasis> want to make a change.	1174	<emphasis>they</emphasis> want to make a change.
1175	</para>	1175	</para>
1176	</listitem>	1176	</listitem>
1177		1177
1178	<listitem>	1178	<listitem>
1179	<para>	1179	<para>
1180	Usually you want a configuration option for your kernel hack.	1180	Usually you want a configuration option for your kernel hack.
1181	Edit <filename>Kconfig</filename> in the appropriate directory.	1181	Edit <filename>Kconfig</filename> in the appropriate directory.
1182	The Config language is simple to use by cut and paste, and there's	1182	The Config language is simple to use by cut and paste, and there's
1183	complete documentation in	1183	complete documentation in
1184	<filename>Documentation/kbuild/kconfig-language.txt</filename>.	1184	<filename>Documentation/kbuild/kconfig-language.txt</filename>.
1185	</para>	1185	</para>
1186		1186
1187	<para>	1187	<para>
1188	You may well want to make your CONFIG option only visible if	1188	You may well want to make your CONFIG option only visible if
1189	<symbol>CONFIG_EXPERIMENTAL</symbol> is enabled: this serves as a	1189	<symbol>CONFIG_EXPERIMENTAL</symbol> is enabled: this serves as a
1190	warning to users. There many other fancy things you can do: see	1190	warning to users. There many other fancy things you can do: see
1191	the various <filename>Kconfig</filename> files for ideas.	1191	the various <filename>Kconfig</filename> files for ideas.
1192	</para>	1192	</para>
1193		1193
1194	<para>	1194	<para>
1195	In your description of the option, make sure you address both the	1195	In your description of the option, make sure you address both the
1196	expert user and the user who knows nothing about your feature. Mention	1196	expert user and the user who knows nothing about your feature. Mention
1197	incompatibilities and issues here. <emphasis> Definitely	1197	incompatibilities and issues here. <emphasis> Definitely
1198	</emphasis> end your description with <quote> if in doubt, say N	1198	</emphasis> end your description with <quote> if in doubt, say N
1199	</quote> (or, occasionally, `Y'); this is for people who have no	1199	</quote> (or, occasionally, `Y'); this is for people who have no
1200	idea what you are talking about.	1200	idea what you are talking about.
1201	</para>	1201	</para>
1202	</listitem>	1202	</listitem>
1203		1203
1204	<listitem>	1204	<listitem>
1205	<para>	1205	<para>
1206	Edit the <filename>Makefile</filename>: the CONFIG variables are	1206	Edit the <filename>Makefile</filename>: the CONFIG variables are
1207	exported here so you can usually just add a "obj-$(CONFIG_xxx) +=	1207	exported here so you can usually just add a "obj-$(CONFIG_xxx) +=
1208	xxx.o" line. The syntax is documented in	1208	xxx.o" line. The syntax is documented in
1209	<filename>Documentation/kbuild/makefiles.txt</filename>.	1209	<filename>Documentation/kbuild/makefiles.txt</filename>.
1210	</para>	1210	</para>
1211	</listitem>	1211	</listitem>
1212		1212
1213	<listitem>	1213	<listitem>
1214	<para>	1214	<para>
1215	Put yourself in <filename>CREDITS</filename> if you've done	1215	Put yourself in <filename>CREDITS</filename> if you've done
1216	something noteworthy, usually beyond a single file (your name	1216	something noteworthy, usually beyond a single file (your name
1217	should be at the top of the source files anyway).	1217	should be at the top of the source files anyway).
1218	<filename>MAINTAINERS</filename> means you want to be consulted	1218	<filename>MAINTAINERS</filename> means you want to be consulted
1219	when changes are made to a subsystem, and hear about bugs; it	1219	when changes are made to a subsystem, and hear about bugs; it
1220	implies a more-than-passing commitment to some part of the code.	1220	implies a more-than-passing commitment to some part of the code.
1221	</para>	1221	</para>
1222	</listitem>	1222	</listitem>
1223		1223
1224	<listitem>	1224	<listitem>
1225	<para>	1225	<para>
1226	Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>	1226	Finally, don't forget to read <filename>Documentation/SubmittingPatches</filename>
1227	and possibly <filename>Documentation/SubmittingDrivers</filename>.	1227	and possibly <filename>Documentation/SubmittingDrivers</filename>.
1228	</para>	1228	</para>
1229	</listitem>	1229	</listitem>
1230	</itemizedlist>	1230	</itemizedlist>
1231	</chapter>	1231	</chapter>
1232		1232
1233	<chapter id="cantrips">	1233	<chapter id="cantrips">
1234	<title>Kernel Cantrips</title>	1234	<title>Kernel Cantrips</title>
1235		1235
1236	<para>	1236	<para>
1237	Some favorites from browsing the source. Feel free to add to this	1237	Some favorites from browsing the source. Feel free to add to this
1238	list.	1238	list.
1239	</para>	1239	</para>
1240		1240
1241	<para>	1241	<para>
1242	<filename>arch/x86/include/asm/delay.h:</filename>	1242	<filename>arch/x86/include/asm/delay.h:</filename>
1243	</para>	1243	</para>
1244	<programlisting>	1244	<programlisting>
1245	#define ndelay(n) (__builtin_constant_p(n) ? \	1245	#define ndelay(n) (__builtin_constant_p(n) ? \
1246	((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \	1246	((n) > 20000 ? __bad_ndelay() : __const_udelay((n) * 5ul)) : \
1247	__ndelay(n))	1247	__ndelay(n))
1248	</programlisting>	1248	</programlisting>
1249		1249
1250	<para>	1250	<para>
1251	<filename>include/linux/fs.h</filename>:	1251	<filename>include/linux/fs.h</filename>:
1252	</para>	1252	</para>
1253	<programlisting>	1253	<programlisting>
1254	/*	1254	/*
1255	* Kernel pointers have redundant information, so we can use a	1255	* Kernel pointers have redundant information, so we can use a
1256	* scheme where we can return either an error code or a dentry	1256	* scheme where we can return either an error code or a dentry
1257	* pointer with the same return value.	1257	* pointer with the same return value.
1258	*	1258	*
1259	* This should be a per-architecture thing, to allow different	1259	* This should be a per-architecture thing, to allow different
1260	* error and pointer decisions.	1260	* error and pointer decisions.
1261	*/	1261	*/
1262	#define ERR_PTR(err) ((void *)((long)(err)))	1262	#define ERR_PTR(err) ((void *)((long)(err)))
1263	#define PTR_ERR(ptr) ((long)(ptr))	1263	#define PTR_ERR(ptr) ((long)(ptr))
1264	#define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))	1264	#define IS_ERR(ptr) ((unsigned long)(ptr) > (unsigned long)(-1000))
1265	</programlisting>	1265	</programlisting>
1266		1266
1267	<para>	1267	<para>
1268	<filename>arch/x86/include/asm/uaccess_32.h:</filename>	1268	<filename>arch/x86/include/asm/uaccess_32.h:</filename>
1269	</para>	1269	</para>
1270		1270
1271	<programlisting>	1271	<programlisting>
1272	#define copy_to_user(to,from,n) \	1272	#define copy_to_user(to,from,n) \
1273	(__builtin_constant_p(n) ? \	1273	(__builtin_constant_p(n) ? \
1274	__constant_copy_to_user((to),(from),(n)) : \	1274	__constant_copy_to_user((to),(from),(n)) : \
1275	__generic_copy_to_user((to),(from),(n)))	1275	__generic_copy_to_user((to),(from),(n)))
1276	</programlisting>	1276	</programlisting>
1277		1277
1278	<para>	1278	<para>
1279	<filename>arch/sparc/kernel/head.S:</filename>	1279	<filename>arch/sparc/kernel/head.S:</filename>
1280	</para>	1280	</para>
1281		1281
1282	<programlisting>	1282	<programlisting>
1283	/*	1283	/*
1284	* Sun people can't spell worth damn. "compatability" indeed.	1284	* Sun people can't spell worth damn. "compatability" indeed.
1285	* At least we know we can't spell, and use a spell-checker.	1285	* At least we know we can't spell, and use a spell-checker.
1286	*/	1286	*/
1287		1287
1288	/* Uh, actually Linus it is I who cannot spell. Too much murky	1288	/* Uh, actually Linus it is I who cannot spell. Too much murky
1289	* Sparc assembly will do this to ya.	1289	* Sparc assembly will do this to ya.
1290	*/	1290	*/
1291	C_LABEL(cputypvar):	1291	C_LABEL(cputypvar):
1292	.asciz "compatability"	1292	.asciz "compatibility"
1293		1293
1294	/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */	1294	/* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */
1295	.align 4	1295	.align 4
1296	C_LABEL(cputypvar_sun4m):	1296	C_LABEL(cputypvar_sun4m):
1297	.asciz "compatible"	1297	.asciz "compatible"
1298	</programlisting>	1298	</programlisting>
1299		1299
1300	<para>	1300	<para>
1301	<filename>arch/sparc/lib/checksum.S:</filename>	1301	<filename>arch/sparc/lib/checksum.S:</filename>
1302	</para>	1302	</para>
1303		1303
1304	<programlisting>	1304	<programlisting>
1305	/* Sun, you just can't beat me, you just can't. Stop trying,	1305	/* Sun, you just can't beat me, you just can't. Stop trying,
1306	* give up. I'm serious, I am going to kick the living shit	1306	* give up. I'm serious, I am going to kick the living shit
1307	* out of you, game over, lights out.	1307	* out of you, game over, lights out.
1308	*/	1308	*/
1309	</programlisting>	1309	</programlisting>
1310	</chapter>	1310	</chapter>
1311		1311
1312	<chapter id="credits">	1312	<chapter id="credits">
1313	<title>Thanks</title>	1313	<title>Thanks</title>
1314		1314
1315	<para>	1315	<para>
1316	Thanks to Andi Kleen for the idea, answering my questions, fixing	1316	Thanks to Andi Kleen for the idea, answering my questions, fixing
1317	my mistakes, filling content, etc. Philipp Rumpf for more spelling	1317	my mistakes, filling content, etc. Philipp Rumpf for more spelling
1318	and clarity fixes, and some excellent non-obvious points. Werner	1318	and clarity fixes, and some excellent non-obvious points. Werner
1319	Almesberger for giving me a great summary of	1319	Almesberger for giving me a great summary of
1320	<function>disable_irq()</function>, and Jes Sorensen and Andrea	1320	<function>disable_irq()</function>, and Jes Sorensen and Andrea
1321	Arcangeli added caveats. Michael Elizabeth Chastain for checking	1321	Arcangeli added caveats. Michael Elizabeth Chastain for checking
1322	and adding to the Configure section. <!-- Rusty insisted on this	1322	and adding to the Configure section. <!-- Rusty insisted on this
1323	bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook.	1323	bit; I didn't do it! --> Telsa Gwynne for teaching me DocBook.
1324	</para>	1324	</para>
1325	</chapter>	1325	</chapter>
1326	</book>	1326	</book>
1327		1327
1328		1328

Documentation/DocBook/libata.tmpl

Diff comments View file @ c94bed8

1	<?xml version="1.0" encoding="UTF-8"?>	1	<?xml version="1.0" encoding="UTF-8"?>
2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"	2	<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>	3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4		4
5	<book id="libataDevGuide">	5	<book id="libataDevGuide">
6	<bookinfo>	6	<bookinfo>
7	<title>libATA Developer's Guide</title>	7	<title>libATA Developer's Guide</title>
8		8
9	<authorgroup>	9	<authorgroup>
10	<author>	10	<author>
11	<firstname>Jeff</firstname>	11	<firstname>Jeff</firstname>
12	<surname>Garzik</surname>	12	<surname>Garzik</surname>
13	</author>	13	</author>
14	</authorgroup>	14	</authorgroup>
15		15
16	<copyright>	16	<copyright>
17	<year>2003-2006</year>	17	<year>2003-2006</year>
18	<holder>Jeff Garzik</holder>	18	<holder>Jeff Garzik</holder>
19	</copyright>	19	</copyright>
20		20
21	<legalnotice>	21	<legalnotice>
22	<para>	22	<para>
23	The contents of this file are subject to the Open	23	The contents of this file are subject to the Open
24	Software License version 1.1 that can be found at	24	Software License version 1.1 that can be found at
25	<ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink>	25	<ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink>
26	and is included herein by reference.	26	and is included herein by reference.
27	</para>	27	</para>
28		28
29	<para>	29	<para>
30	Alternatively, the contents of this file may be used under the terms	30	Alternatively, the contents of this file may be used under the terms
31	of the GNU General Public License version 2 (the "GPL") as distributed	31	of the GNU General Public License version 2 (the "GPL") as distributed
32	in the kernel source COPYING file, in which case the provisions of	32	in the kernel source COPYING file, in which case the provisions of
33	the GPL are applicable instead of the above. If you wish to allow	33	the GPL are applicable instead of the above. If you wish to allow
34	the use of your version of this file only under the terms of the	34	the use of your version of this file only under the terms of the
35	GPL and not to allow others to use your version of this file under	35	GPL and not to allow others to use your version of this file under
36	the OSL, indicate your decision by deleting the provisions above and	36	the OSL, indicate your decision by deleting the provisions above and
37	replace them with the notice and other provisions required by the GPL.	37	replace them with the notice and other provisions required by the GPL.
38	If you do not delete the provisions above, a recipient may use your	38	If you do not delete the provisions above, a recipient may use your
39	version of this file under either the OSL or the GPL.	39	version of this file under either the OSL or the GPL.
40	</para>	40	</para>
41		41
42	</legalnotice>	42	</legalnotice>
43	</bookinfo>	43	</bookinfo>
44		44
45	<toc></toc>	45	<toc></toc>
46		46
47	<chapter id="libataIntroduction">	47	<chapter id="libataIntroduction">
48	<title>Introduction</title>	48	<title>Introduction</title>
49	<para>	49	<para>
50	libATA is a library used inside the Linux kernel to support ATA host	50	libATA is a library used inside the Linux kernel to support ATA host
51	controllers and devices. libATA provides an ATA driver API, class	51	controllers and devices. libATA provides an ATA driver API, class
52	transports for ATA and ATAPI devices, and SCSI<->ATA translation	52	transports for ATA and ATAPI devices, and SCSI<->ATA translation
53	for ATA devices according to the T10 SAT specification.	53	for ATA devices according to the T10 SAT specification.
54	</para>	54	</para>
55	<para>	55	<para>
56	This Guide documents the libATA driver API, library functions, library	56	This Guide documents the libATA driver API, library functions, library
57	internals, and a couple sample ATA low-level drivers.	57	internals, and a couple sample ATA low-level drivers.
58	</para>	58	</para>
59	</chapter>	59	</chapter>
60		60
61	<chapter id="libataDriverApi">	61	<chapter id="libataDriverApi">
62	<title>libata Driver API</title>	62	<title>libata Driver API</title>
63	<para>	63	<para>
64	struct ata_port_operations is defined for every low-level libata	64	struct ata_port_operations is defined for every low-level libata
65	hardware driver, and it controls how the low-level driver	65	hardware driver, and it controls how the low-level driver
66	interfaces with the ATA and SCSI layers.	66	interfaces with the ATA and SCSI layers.
67	</para>	67	</para>
68	<para>	68	<para>
69	FIS-based drivers will hook into the system with ->qc_prep() and	69	FIS-based drivers will hook into the system with ->qc_prep() and
70	->qc_issue() high-level hooks. Hardware which behaves in a manner	70	->qc_issue() high-level hooks. Hardware which behaves in a manner
71	similar to PCI IDE hardware may utilize several generic helpers,	71	similar to PCI IDE hardware may utilize several generic helpers,
72	defining at a bare minimum the bus I/O addresses of the ATA shadow	72	defining at a bare minimum the bus I/O addresses of the ATA shadow
73	register blocks.	73	register blocks.
74	</para>	74	</para>
75	<sect1>	75	<sect1>
76	<title>struct ata_port_operations</title>	76	<title>struct ata_port_operations</title>
77		77
78	<sect2><title>Disable ATA port</title>	78	<sect2><title>Disable ATA port</title>
79	<programlisting>	79	<programlisting>
80	void (port_disable) (struct ata_port );	80	void (port_disable) (struct ata_port );
81	</programlisting>	81	</programlisting>
82		82
83	<para>	83	<para>
84	Called from ata_bus_probe() error path, as well as when	84	Called from ata_bus_probe() error path, as well as when
85	unregistering from the SCSI module (rmmod, hot unplug).	85	unregistering from the SCSI module (rmmod, hot unplug).
86	This function should do whatever needs to be done to take the	86	This function should do whatever needs to be done to take the
87	port out of use. In most cases, ata_port_disable() can be used	87	port out of use. In most cases, ata_port_disable() can be used
88	as this hook.	88	as this hook.
89	</para>	89	</para>
90	<para>	90	<para>
91	Called from ata_bus_probe() on a failed probe.	91	Called from ata_bus_probe() on a failed probe.
92	Called from ata_scsi_release().	92	Called from ata_scsi_release().
93	</para>	93	</para>
94		94
95	</sect2>	95	</sect2>
96		96
97	<sect2><title>Post-IDENTIFY device configuration</title>	97	<sect2><title>Post-IDENTIFY device configuration</title>
98	<programlisting>	98	<programlisting>
99	void (dev_config) (struct ata_port , struct ata_device *);	99	void (dev_config) (struct ata_port , struct ata_device *);
100	</programlisting>	100	</programlisting>
101		101
102	<para>	102	<para>
103	Called after IDENTIFY [PACKET] DEVICE is issued to each device	103	Called after IDENTIFY [PACKET] DEVICE is issued to each device
104	found. Typically used to apply device-specific fixups prior to	104	found. Typically used to apply device-specific fixups prior to
105	issue of SET FEATURES - XFER MODE, and prior to operation.	105	issue of SET FEATURES - XFER MODE, and prior to operation.
106	</para>	106	</para>
107	<para>	107	<para>
108	This entry may be specified as NULL in ata_port_operations.	108	This entry may be specified as NULL in ata_port_operations.
109	</para>	109	</para>
110		110
111	</sect2>	111	</sect2>
112		112
113	<sect2><title>Set PIO/DMA mode</title>	113	<sect2><title>Set PIO/DMA mode</title>
114	<programlisting>	114	<programlisting>
115	void (set_piomode) (struct ata_port , struct ata_device *);	115	void (set_piomode) (struct ata_port , struct ata_device *);
116	void (set_dmamode) (struct ata_port , struct ata_device *);	116	void (set_dmamode) (struct ata_port , struct ata_device *);
117	void (post_set_mode) (struct ata_port );	117	void (post_set_mode) (struct ata_port );
118	unsigned int (mode_filter) (struct ata_port , struct ata_device *, unsigned int);	118	unsigned int (mode_filter) (struct ata_port , struct ata_device *, unsigned int);
119	</programlisting>	119	</programlisting>
120		120
121	<para>	121	<para>
122	Hooks called prior to the issue of SET FEATURES - XFER MODE	122	Hooks called prior to the issue of SET FEATURES - XFER MODE
123	command. The optional ->mode_filter() hook is called when libata	123	command. The optional ->mode_filter() hook is called when libata
124	has built a mask of the possible modes. This is passed to the	124	has built a mask of the possible modes. This is passed to the
125	->mode_filter() function which should return a mask of valid modes	125	->mode_filter() function which should return a mask of valid modes
126	after filtering those unsuitable due to hardware limits. It is not	126	after filtering those unsuitable due to hardware limits. It is not
127	valid to use this interface to add modes.	127	valid to use this interface to add modes.
128	</para>	128	</para>
129	<para>	129	<para>
130	dev->pio_mode and dev->dma_mode are guaranteed to be valid when	130	dev->pio_mode and dev->dma_mode are guaranteed to be valid when
131	->set_piomode() and when ->set_dmamode() is called. The timings for	131	->set_piomode() and when ->set_dmamode() is called. The timings for
132	any other drive sharing the cable will also be valid at this point.	132	any other drive sharing the cable will also be valid at this point.
133	That is the library records the decisions for the modes of each	133	That is the library records the decisions for the modes of each
134	drive on a channel before it attempts to set any of them.	134	drive on a channel before it attempts to set any of them.
135	</para>	135	</para>
136	<para>	136	<para>
137	->post_set_mode() is	137	->post_set_mode() is
138	called unconditionally, after the SET FEATURES - XFER MODE	138	called unconditionally, after the SET FEATURES - XFER MODE
139	command completes successfully.	139	command completes successfully.
140	</para>	140	</para>
141		141
142	<para>	142	<para>
143	->set_piomode() is always called (if present), but	143	->set_piomode() is always called (if present), but
144	->set_dma_mode() is only called if DMA is possible.	144	->set_dma_mode() is only called if DMA is possible.
145	</para>	145	</para>
146		146
147	</sect2>	147	</sect2>
148		148
149	<sect2><title>Taskfile read/write</title>	149	<sect2><title>Taskfile read/write</title>
150	<programlisting>	150	<programlisting>
151	void (sff_tf_load) (struct ata_port ap, struct ata_taskfile *tf);	151	void (sff_tf_load) (struct ata_port ap, struct ata_taskfile *tf);
152	void (sff_tf_read) (struct ata_port ap, struct ata_taskfile *tf);	152	void (sff_tf_read) (struct ata_port ap, struct ata_taskfile *tf);
153	</programlisting>	153	</programlisting>
154		154
155	<para>	155	<para>
156	->tf_load() is called to load the given taskfile into hardware	156	->tf_load() is called to load the given taskfile into hardware
157	registers / DMA buffers. ->tf_read() is called to read the	157	registers / DMA buffers. ->tf_read() is called to read the
158	hardware registers / DMA buffers, to obtain the current set of	158	hardware registers / DMA buffers, to obtain the current set of
159	taskfile register values.	159	taskfile register values.
160	Most drivers for taskfile-based hardware (PIO or MMIO) use	160	Most drivers for taskfile-based hardware (PIO or MMIO) use
161	ata_sff_tf_load() and ata_sff_tf_read() for these hooks.	161	ata_sff_tf_load() and ata_sff_tf_read() for these hooks.
162	</para>	162	</para>
163		163
164	</sect2>	164	</sect2>
165		165
166	<sect2><title>PIO data read/write</title>	166	<sect2><title>PIO data read/write</title>
167	<programlisting>	167	<programlisting>
168	void (sff_data_xfer) (struct ata_device , unsigned char *, unsigned int, int);	168	void (sff_data_xfer) (struct ata_device , unsigned char *, unsigned int, int);
169	</programlisting>	169	</programlisting>
170		170
171	<para>	171	<para>
172	All bmdma-style drivers must implement this hook. This is the low-level	172	All bmdma-style drivers must implement this hook. This is the low-level
173	operation that actually copies the data bytes during a PIO data	173	operation that actually copies the data bytes during a PIO data
174	transfer.	174	transfer.
175	Typically the driver will choose one of ata_sff_data_xfer_noirq(),	175	Typically the driver will choose one of ata_sff_data_xfer_noirq(),
176	ata_sff_data_xfer(), or ata_sff_data_xfer32().	176	ata_sff_data_xfer(), or ata_sff_data_xfer32().
177	</para>	177	</para>
178		178
179	</sect2>	179	</sect2>
180		180
181	<sect2><title>ATA command execute</title>	181	<sect2><title>ATA command execute</title>
182	<programlisting>	182	<programlisting>
183	void (sff_exec_command)(struct ata_port ap, struct ata_taskfile *tf);	183	void (sff_exec_command)(struct ata_port ap, struct ata_taskfile *tf);
184	</programlisting>	184	</programlisting>
185		185
186	<para>	186	<para>
187	causes an ATA command, previously loaded with	187	causes an ATA command, previously loaded with
188	->tf_load(), to be initiated in hardware.	188	->tf_load(), to be initiated in hardware.
189	Most drivers for taskfile-based hardware use ata_sff_exec_command()	189	Most drivers for taskfile-based hardware use ata_sff_exec_command()
190	for this hook.	190	for this hook.
191	</para>	191	</para>
192		192
193	</sect2>	193	</sect2>
194		194
195	<sect2><title>Per-cmd ATAPI DMA capabilities filter</title>	195	<sect2><title>Per-cmd ATAPI DMA capabilities filter</title>
196	<programlisting>	196	<programlisting>
197	int (check_atapi_dma) (struct ata_queued_cmd qc);	197	int (check_atapi_dma) (struct ata_queued_cmd qc);
198	</programlisting>	198	</programlisting>
199		199
200	<para>	200	<para>
201	Allow low-level driver to filter ATA PACKET commands, returning a status	201	Allow low-level driver to filter ATA PACKET commands, returning a status
202	indicating whether or not it is OK to use DMA for the supplied PACKET	202	indicating whether or not it is OK to use DMA for the supplied PACKET
203	command.	203	command.
204	</para>	204	</para>
205	<para>	205	<para>
206	This hook may be specified as NULL, in which case libata will	206	This hook may be specified as NULL, in which case libata will
207	assume that atapi dma can be supported.	207	assume that atapi dma can be supported.
208	</para>	208	</para>
209		209
210	</sect2>	210	</sect2>
211		211
212	<sect2><title>Read specific ATA shadow registers</title>	212	<sect2><title>Read specific ATA shadow registers</title>
213	<programlisting>	213	<programlisting>
214	u8 (sff_check_status)(struct ata_port ap);	214	u8 (sff_check_status)(struct ata_port ap);
215	u8 (sff_check_altstatus)(struct ata_port ap);	215	u8 (sff_check_altstatus)(struct ata_port ap);
216	</programlisting>	216	</programlisting>
217		217
218	<para>	218	<para>
219	Reads the Status/AltStatus ATA shadow register from	219	Reads the Status/AltStatus ATA shadow register from
220	hardware. On some hardware, reading the Status register has	220	hardware. On some hardware, reading the Status register has
221	the side effect of clearing the interrupt condition.	221	the side effect of clearing the interrupt condition.
222	Most drivers for taskfile-based hardware use	222	Most drivers for taskfile-based hardware use
223	ata_sff_check_status() for this hook.	223	ata_sff_check_status() for this hook.
224	</para>	224	</para>
225		225
226	</sect2>	226	</sect2>
227		227
228	<sect2><title>Write specific ATA shadow register</title>	228	<sect2><title>Write specific ATA shadow register</title>
229	<programlisting>	229	<programlisting>
230	void (sff_set_devctl)(struct ata_port ap, u8 ctl);	230	void (sff_set_devctl)(struct ata_port ap, u8 ctl);
231	</programlisting>	231	</programlisting>
232		232
233	<para>	233	<para>
234	Write the device control ATA shadow register to the hardware.	234	Write the device control ATA shadow register to the hardware.
235	Most drivers don't need to define this.	235	Most drivers don't need to define this.
236	</para>	236	</para>
237		237
238	</sect2>	238	</sect2>
239		239
240	<sect2><title>Select ATA device on bus</title>	240	<sect2><title>Select ATA device on bus</title>
241	<programlisting>	241	<programlisting>
242	void (sff_dev_select)(struct ata_port ap, unsigned int device);	242	void (sff_dev_select)(struct ata_port ap, unsigned int device);
243	</programlisting>	243	</programlisting>
244		244
245	<para>	245	<para>
246	Issues the low-level hardware command(s) that causes one of N	246	Issues the low-level hardware command(s) that causes one of N
247	hardware devices to be considered 'selected' (active and	247	hardware devices to be considered 'selected' (active and
248	available for use) on the ATA bus. This generally has no	248	available for use) on the ATA bus. This generally has no
249	meaning on FIS-based devices.	249	meaning on FIS-based devices.
250	</para>	250	</para>
251	<para>	251	<para>
252	Most drivers for taskfile-based hardware use	252	Most drivers for taskfile-based hardware use
253	ata_sff_dev_select() for this hook.	253	ata_sff_dev_select() for this hook.
254	</para>	254	</para>
255		255
256	</sect2>	256	</sect2>
257		257
258	<sect2><title>Private tuning method</title>	258	<sect2><title>Private tuning method</title>
259	<programlisting>	259	<programlisting>
260	void (set_mode) (struct ata_port ap);	260	void (set_mode) (struct ata_port ap);
261	</programlisting>	261	</programlisting>
262		262
263	<para>	263	<para>
264	By default libata performs drive and controller tuning in	264	By default libata performs drive and controller tuning in
265	accordance with the ATA timing rules and also applies blacklists	265	accordance with the ATA timing rules and also applies blacklists
266	and cable limits. Some controllers need special handling and have	266	and cable limits. Some controllers need special handling and have
267	custom tuning rules, typically raid controllers that use ATA	267	custom tuning rules, typically raid controllers that use ATA
268	commands but do not actually do drive timing.	268	commands but do not actually do drive timing.
269	</para>	269	</para>
270		270
271	<warning>	271	<warning>
272	<para>	272	<para>
273	This hook should not be used to replace the standard controller	273	This hook should not be used to replace the standard controller
274	tuning logic when a controller has quirks. Replacing the default	274	tuning logic when a controller has quirks. Replacing the default
275	tuning logic in that case would bypass handling for drive and	275	tuning logic in that case would bypass handling for drive and
276	bridge quirks that may be important to data reliability. If a	276	bridge quirks that may be important to data reliability. If a
277	controller needs to filter the mode selection it should use the	277	controller needs to filter the mode selection it should use the
278	mode_filter hook instead.	278	mode_filter hook instead.
279	</para>	279	</para>
280	</warning>	280	</warning>
281		281
282	</sect2>	282	</sect2>
283		283
284	<sect2><title>Control PCI IDE BMDMA engine</title>	284	<sect2><title>Control PCI IDE BMDMA engine</title>
285	<programlisting>	285	<programlisting>
286	void (bmdma_setup) (struct ata_queued_cmd qc);	286	void (bmdma_setup) (struct ata_queued_cmd qc);
287	void (bmdma_start) (struct ata_queued_cmd qc);	287	void (bmdma_start) (struct ata_queued_cmd qc);
288	void (bmdma_stop) (struct ata_port ap);	288	void (bmdma_stop) (struct ata_port ap);
289	u8 (bmdma_status) (struct ata_port ap);	289	u8 (bmdma_status) (struct ata_port ap);
290	</programlisting>	290	</programlisting>
291		291
292	<para>	292	<para>
293	When setting up an IDE BMDMA transaction, these hooks arm	293	When setting up an IDE BMDMA transaction, these hooks arm
294	(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)	294	(->bmdma_setup), fire (->bmdma_start), and halt (->bmdma_stop)
295	the hardware's DMA engine. ->bmdma_status is used to read the standard	295	the hardware's DMA engine. ->bmdma_status is used to read the standard
296	PCI IDE DMA Status register.	296	PCI IDE DMA Status register.
297	</para>	297	</para>
298		298
299	<para>	299	<para>
300	These hooks are typically either no-ops, or simply not implemented, in	300	These hooks are typically either no-ops, or simply not implemented, in
301	FIS-based drivers.	301	FIS-based drivers.
302	</para>	302	</para>
303	<para>	303	<para>
304	Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()	304	Most legacy IDE drivers use ata_bmdma_setup() for the bmdma_setup()
305	hook. ata_bmdma_setup() will write the pointer to the PRD table to	305	hook. ata_bmdma_setup() will write the pointer to the PRD table to
306	the IDE PRD Table Address register, enable DMA in the DMA Command	306	the IDE PRD Table Address register, enable DMA in the DMA Command
307	register, and call exec_command() to begin the transfer.	307	register, and call exec_command() to begin the transfer.
308	</para>	308	</para>
309	<para>	309	<para>
310	Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()	310	Most legacy IDE drivers use ata_bmdma_start() for the bmdma_start()
311	hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA	311	hook. ata_bmdma_start() will write the ATA_DMA_START flag to the DMA
312	Command register.	312	Command register.
313	</para>	313	</para>
314	<para>	314	<para>
315	Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()	315	Many legacy IDE drivers use ata_bmdma_stop() for the bmdma_stop()
316	hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA	316	hook. ata_bmdma_stop() clears the ATA_DMA_START flag in the DMA
317	command register.	317	command register.
318	</para>	318	</para>
319	<para>	319	<para>
320	Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.	320	Many legacy IDE drivers use ata_bmdma_status() as the bmdma_status() hook.
321	</para>	321	</para>
322		322
323	</sect2>	323	</sect2>
324		324
325	<sect2><title>High-level taskfile hooks</title>	325	<sect2><title>High-level taskfile hooks</title>
326	<programlisting>	326	<programlisting>
327	void (qc_prep) (struct ata_queued_cmd qc);	327	void (qc_prep) (struct ata_queued_cmd qc);
328	int (qc_issue) (struct ata_queued_cmd qc);	328	int (qc_issue) (struct ata_queued_cmd qc);
329	</programlisting>	329	</programlisting>
330		330
331	<para>	331	<para>
332	Higher-level hooks, these two hooks can potentially supercede	332	Higher-level hooks, these two hooks can potentially supercede
333	several of the above taskfile/DMA engine hooks. ->qc_prep is	333	several of the above taskfile/DMA engine hooks. ->qc_prep is
334	called after the buffers have been DMA-mapped, and is typically	334	called after the buffers have been DMA-mapped, and is typically
335	used to populate the hardware's DMA scatter-gather table.	335	used to populate the hardware's DMA scatter-gather table.
336	Most drivers use the standard ata_qc_prep() helper function, but	336	Most drivers use the standard ata_qc_prep() helper function, but
337	more advanced drivers roll their own.	337	more advanced drivers roll their own.
338	</para>	338	</para>
339	<para>	339	<para>
340	->qc_issue is used to make a command active, once the hardware	340	->qc_issue is used to make a command active, once the hardware
341	and S/G tables have been prepared. IDE BMDMA drivers use the	341	and S/G tables have been prepared. IDE BMDMA drivers use the
342	helper function ata_qc_issue_prot() for taskfile protocol-based	342	helper function ata_qc_issue_prot() for taskfile protocol-based
343	dispatch. More advanced drivers implement their own ->qc_issue.	343	dispatch. More advanced drivers implement their own ->qc_issue.
344	</para>	344	</para>
345	<para>	345	<para>
346	ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and	346	ata_qc_issue_prot() calls ->tf_load(), ->bmdma_setup(), and
347	->bmdma_start() as necessary to initiate a transfer.	347	->bmdma_start() as necessary to initiate a transfer.
348	</para>	348	</para>
349		349
350	</sect2>	350	</sect2>
351		351
352	<sect2><title>Exception and probe handling (EH)</title>	352	<sect2><title>Exception and probe handling (EH)</title>
353	<programlisting>	353	<programlisting>
354	void (eng_timeout) (struct ata_port ap);	354	void (eng_timeout) (struct ata_port ap);
355	void (phy_reset) (struct ata_port ap);	355	void (phy_reset) (struct ata_port ap);
356	</programlisting>	356	</programlisting>
357		357
358	<para>	358	<para>
359	Deprecated. Use ->error_handler() instead.	359	Deprecated. Use ->error_handler() instead.
360	</para>	360	</para>
361		361
362	<programlisting>	362	<programlisting>
363	void (freeze) (struct ata_port ap);	363	void (freeze) (struct ata_port ap);
364	void (thaw) (struct ata_port ap);	364	void (thaw) (struct ata_port ap);
365	</programlisting>	365	</programlisting>
366		366
367	<para>	367	<para>
368	ata_port_freeze() is called when HSM violations or some other	368	ata_port_freeze() is called when HSM violations or some other
369	condition disrupts normal operation of the port. A frozen port	369	condition disrupts normal operation of the port. A frozen port
370	is not allowed to perform any operation until the port is	370	is not allowed to perform any operation until the port is
371	thawed, which usually follows a successful reset.	371	thawed, which usually follows a successful reset.
372	</para>	372	</para>
373		373
374	<para>	374	<para>
375	The optional ->freeze() callback can be used for freezing the port	375	The optional ->freeze() callback can be used for freezing the port
376	hardware-wise (e.g. mask interrupt and stop DMA engine). If a	376	hardware-wise (e.g. mask interrupt and stop DMA engine). If a
377	port cannot be frozen hardware-wise, the interrupt handler	377	port cannot be frozen hardware-wise, the interrupt handler
378	must ack and clear interrupts unconditionally while the port	378	must ack and clear interrupts unconditionally while the port
379	is frozen.	379	is frozen.
380	</para>	380	</para>
381	<para>	381	<para>
382	The optional ->thaw() callback is called to perform the opposite of ->freeze():	382	The optional ->thaw() callback is called to perform the opposite of ->freeze():
383	prepare the port for normal operation once again. Unmask interrupts,	383	prepare the port for normal operation once again. Unmask interrupts,
384	start DMA engine, etc.	384	start DMA engine, etc.
385	</para>	385	</para>
386		386
387	<programlisting>	387	<programlisting>
388	void (error_handler) (struct ata_port ap);	388	void (error_handler) (struct ata_port ap);
389	</programlisting>	389	</programlisting>
390		390
391	<para>	391	<para>
392	->error_handler() is a driver's hook into probe, hotplug, and recovery	392	->error_handler() is a driver's hook into probe, hotplug, and recovery
393	and other exceptional conditions. The primary responsibility of an	393	and other exceptional conditions. The primary responsibility of an
394	implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set	394	implementation is to call ata_do_eh() or ata_bmdma_drive_eh() with a set
395	of EH hooks as arguments:	395	of EH hooks as arguments:
396	</para>	396	</para>
397		397
398	<para>	398	<para>
399	'prereset' hook (may be NULL) is called during an EH reset, before any other actions	399	'prereset' hook (may be NULL) is called during an EH reset, before any other actions
400	are taken.	400	are taken.
401	</para>	401	</para>
402		402
403	<para>	403	<para>
404	'postreset' hook (may be NULL) is called after the EH reset is performed. Based on	404	'postreset' hook (may be NULL) is called after the EH reset is performed. Based on
405	existing conditions, severity of the problem, and hardware capabilities,	405	existing conditions, severity of the problem, and hardware capabilities,
406	</para>	406	</para>
407		407
408	<para>	408	<para>
409	Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be	409	Either 'softreset' (may be NULL) or 'hardreset' (may be NULL) will be
410	called to perform the low-level EH reset.	410	called to perform the low-level EH reset.
411	</para>	411	</para>
412		412
413	<programlisting>	413	<programlisting>
414	void (post_internal_cmd) (struct ata_queued_cmd qc);	414	void (post_internal_cmd) (struct ata_queued_cmd qc);
415	</programlisting>	415	</programlisting>
416		416
417	<para>	417	<para>
418	Perform any hardware-specific actions necessary to finish processing	418	Perform any hardware-specific actions necessary to finish processing
419	after executing a probe-time or EH-time command via ata_exec_internal().	419	after executing a probe-time or EH-time command via ata_exec_internal().
420	</para>	420	</para>
421		421
422	</sect2>	422	</sect2>
423		423
424	<sect2><title>Hardware interrupt handling</title>	424	<sect2><title>Hardware interrupt handling</title>
425	<programlisting>	425	<programlisting>
426	irqreturn_t (irq_handler)(int, void , struct pt_regs *);	426	irqreturn_t (irq_handler)(int, void , struct pt_regs *);
427	void (irq_clear) (struct ata_port );	427	void (irq_clear) (struct ata_port );
428	</programlisting>	428	</programlisting>
429		429
430	<para>	430	<para>
431	->irq_handler is the interrupt handling routine registered with	431	->irq_handler is the interrupt handling routine registered with
432	the system, by libata. ->irq_clear is called during probe just	432	the system, by libata. ->irq_clear is called during probe just
433	before the interrupt handler is registered, to be sure hardware	433	before the interrupt handler is registered, to be sure hardware
434	is quiet.	434	is quiet.
435	</para>	435	</para>
436	<para>	436	<para>
437	The second argument, dev_instance, should be cast to a pointer	437	The second argument, dev_instance, should be cast to a pointer
438	to struct ata_host_set.	438	to struct ata_host_set.
439	</para>	439	</para>
440	<para>	440	<para>
441	Most legacy IDE drivers use ata_sff_interrupt() for the	441	Most legacy IDE drivers use ata_sff_interrupt() for the
442	irq_handler hook, which scans all ports in the host_set,	442	irq_handler hook, which scans all ports in the host_set,
443	determines which queued command was active (if any), and calls	443	determines which queued command was active (if any), and calls
444	ata_sff_host_intr(ap,qc).	444	ata_sff_host_intr(ap,qc).
445	</para>	445	</para>
446	<para>	446	<para>
447	Most legacy IDE drivers use ata_sff_irq_clear() for the	447	Most legacy IDE drivers use ata_sff_irq_clear() for the
448	irq_clear() hook, which simply clears the interrupt and error	448	irq_clear() hook, which simply clears the interrupt and error
449	flags in the DMA status register.	449	flags in the DMA status register.
450	</para>	450	</para>
451		451
452	</sect2>	452	</sect2>
453		453
454	<sect2><title>SATA phy read/write</title>	454	<sect2><title>SATA phy read/write</title>
455	<programlisting>	455	<programlisting>
456	int (scr_read) (struct ata_port ap, unsigned int sc_reg,	456	int (scr_read) (struct ata_port ap, unsigned int sc_reg,
457	u32 *val);	457	u32 *val);
458	int (scr_write) (struct ata_port ap, unsigned int sc_reg,	458	int (scr_write) (struct ata_port ap, unsigned int sc_reg,
459	u32 val);	459	u32 val);
460	</programlisting>	460	</programlisting>
461		461
462	<para>	462	<para>
463	Read and write standard SATA phy registers. Currently only used	463	Read and write standard SATA phy registers. Currently only used
464	if ->phy_reset hook called the sata_phy_reset() helper function.	464	if ->phy_reset hook called the sata_phy_reset() helper function.
465	sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.	465	sc_reg is one of SCR_STATUS, SCR_CONTROL, SCR_ERROR, or SCR_ACTIVE.
466	</para>	466	</para>
467		467
468	</sect2>	468	</sect2>
469		469
470	<sect2><title>Init and shutdown</title>	470	<sect2><title>Init and shutdown</title>
471	<programlisting>	471	<programlisting>
472	int (port_start) (struct ata_port ap);	472	int (port_start) (struct ata_port ap);
473	void (port_stop) (struct ata_port ap);	473	void (port_stop) (struct ata_port ap);
474	void (host_stop) (struct ata_host_set host_set);	474	void (host_stop) (struct ata_host_set host_set);
475	</programlisting>	475	</programlisting>
476		476
477	<para>	477	<para>
478	->port_start() is called just after the data structures for each	478	->port_start() is called just after the data structures for each
479	port are initialized. Typically this is used to alloc per-port	479	port are initialized. Typically this is used to alloc per-port
480	DMA buffers / tables / rings, enable DMA engines, and similar	480	DMA buffers / tables / rings, enable DMA engines, and similar
481	tasks. Some drivers also use this entry point as a chance to	481	tasks. Some drivers also use this entry point as a chance to
482	allocate driver-private memory for ap->private_data.	482	allocate driver-private memory for ap->private_data.
483	</para>	483	</para>
484	<para>	484	<para>
485	Many drivers use ata_port_start() as this hook or call	485	Many drivers use ata_port_start() as this hook or call
486	it from their own port_start() hooks. ata_port_start()	486	it from their own port_start() hooks. ata_port_start()
487	allocates space for a legacy IDE PRD table and returns.	487	allocates space for a legacy IDE PRD table and returns.
488	</para>	488	</para>
489	<para>	489	<para>
490	->port_stop() is called after ->host_stop(). Its sole function	490	->port_stop() is called after ->host_stop(). Its sole function
491	is to release DMA/memory resources, now that they are no longer	491	is to release DMA/memory resources, now that they are no longer
492	actively being used. Many drivers also free driver-private	492	actively being used. Many drivers also free driver-private
493	data from port at this time.	493	data from port at this time.
494	</para>	494	</para>
495	<para>	495	<para>
496	->host_stop() is called after all ->port_stop() calls	496	->host_stop() is called after all ->port_stop() calls
497	have completed. The hook must finalize hardware shutdown, release DMA	497	have completed. The hook must finalize hardware shutdown, release DMA
498	and other resources, etc.	498	and other resources, etc.
499	This hook may be specified as NULL, in which case it is not called.	499	This hook may be specified as NULL, in which case it is not called.
500	</para>	500	</para>
501		501
502	</sect2>	502	</sect2>
503		503
504	</sect1>	504	</sect1>
505	</chapter>	505	</chapter>
506		506
507	<chapter id="libataEH">	507	<chapter id="libataEH">
508	<title>Error handling</title>	508	<title>Error handling</title>
509		509
510	<para>	510	<para>
511	This chapter describes how errors are handled under libata.	511	This chapter describes how errors are handled under libata.
512	Readers are advised to read SCSI EH	512	Readers are advised to read SCSI EH
513	(Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first.	513	(Documentation/scsi/scsi_eh.txt) and ATA exceptions doc first.
514	</para>	514	</para>
515		515
516	<sect1><title>Origins of commands</title>	516	<sect1><title>Origins of commands</title>
517	<para>	517	<para>
518	In libata, a command is represented with struct ata_queued_cmd	518	In libata, a command is represented with struct ata_queued_cmd
519	or qc. qc's are preallocated during port initialization and	519	or qc. qc's are preallocated during port initialization and
520	repetitively used for command executions. Currently only one	520	repetitively used for command executions. Currently only one
521	qc is allocated per port but yet-to-be-merged NCQ branch	521	qc is allocated per port but yet-to-be-merged NCQ branch
522	allocates one for each tag and maps each qc to NCQ tag 1-to-1.	522	allocates one for each tag and maps each qc to NCQ tag 1-to-1.
523	</para>	523	</para>
524	<para>	524	<para>
525	libata commands can originate from two sources - libata itself	525	libata commands can originate from two sources - libata itself
526	and SCSI midlayer. libata internal commands are used for	526	and SCSI midlayer. libata internal commands are used for
527	initialization and error handling. All normal blk requests	527	initialization and error handling. All normal blk requests
528	and commands for SCSI emulation are passed as SCSI commands	528	and commands for SCSI emulation are passed as SCSI commands
529	through queuecommand callback of SCSI host template.	529	through queuecommand callback of SCSI host template.
530	</para>	530	</para>
531	</sect1>	531	</sect1>
532		532
533	<sect1><title>How commands are issued</title>	533	<sect1><title>How commands are issued</title>
534		534
535	<variablelist>	535	<variablelist>
536		536
537	<varlistentry><term>Internal commands</term>	537	<varlistentry><term>Internal commands</term>
538	<listitem>	538	<listitem>
539	<para>	539	<para>
540	First, qc is allocated and initialized using	540	First, qc is allocated and initialized using
541	ata_qc_new_init(). Although ata_qc_new_init() doesn't	541	ata_qc_new_init(). Although ata_qc_new_init() doesn't
542	implement any wait or retry mechanism when qc is not	542	implement any wait or retry mechanism when qc is not
543	available, internal commands are currently issued only during	543	available, internal commands are currently issued only during
544	initialization and error recovery, so no other command is	544	initialization and error recovery, so no other command is
545	active and allocation is guaranteed to succeed.	545	active and allocation is guaranteed to succeed.
546	</para>	546	</para>
547	<para>	547	<para>
548	Once allocated qc's taskfile is initialized for the command to	548	Once allocated qc's taskfile is initialized for the command to
549	be executed. qc currently has two mechanisms to notify	549	be executed. qc currently has two mechanisms to notify
550	completion. One is via qc->complete_fn() callback and the	550	completion. One is via qc->complete_fn() callback and the
551	other is completion qc->waiting. qc->complete_fn() callback	551	other is completion qc->waiting. qc->complete_fn() callback
552	is the asynchronous path used by normal SCSI translated	552	is the asynchronous path used by normal SCSI translated
553	commands and qc->waiting is the synchronous (issuer sleeps in	553	commands and qc->waiting is the synchronous (issuer sleeps in
554	process context) path used by internal commands.	554	process context) path used by internal commands.
555	</para>	555	</para>
556	<para>	556	<para>
557	Once initialization is complete, host_set lock is acquired	557	Once initialization is complete, host_set lock is acquired
558	and the qc is issued.	558	and the qc is issued.
559	</para>	559	</para>
560	</listitem>	560	</listitem>
561	</varlistentry>	561	</varlistentry>
562		562
563	<varlistentry><term>SCSI commands</term>	563	<varlistentry><term>SCSI commands</term>
564	<listitem>	564	<listitem>
565	<para>	565	<para>
566	All libata drivers use ata_scsi_queuecmd() as	566	All libata drivers use ata_scsi_queuecmd() as
567	hostt->queuecommand callback. scmds can either be simulated	567	hostt->queuecommand callback. scmds can either be simulated
568	or translated. No qc is involved in processing a simulated	568	or translated. No qc is involved in processing a simulated
569	scmd. The result is computed right away and the scmd is	569	scmd. The result is computed right away and the scmd is
570	completed.	570	completed.
571	</para>	571	</para>
572	<para>	572	<para>
573	For a translated scmd, ata_qc_new_init() is invoked to	573	For a translated scmd, ata_qc_new_init() is invoked to
574	allocate a qc and the scmd is translated into the qc. SCSI	574	allocate a qc and the scmd is translated into the qc. SCSI
575	midlayer's completion notification function pointer is stored	575	midlayer's completion notification function pointer is stored
576	into qc->scsidone.	576	into qc->scsidone.
577	</para>	577	</para>
578	<para>	578	<para>
579	qc->complete_fn() callback is used for completion	579	qc->complete_fn() callback is used for completion
580	notification. ATA commands use ata_scsi_qc_complete() while	580	notification. ATA commands use ata_scsi_qc_complete() while
581	ATAPI commands use atapi_qc_complete(). Both functions end up	581	ATAPI commands use atapi_qc_complete(). Both functions end up
582	calling qc->scsidone to notify upper layer when the qc is	582	calling qc->scsidone to notify upper layer when the qc is
583	finished. After translation is completed, the qc is issued	583	finished. After translation is completed, the qc is issued
584	with ata_qc_issue().	584	with ata_qc_issue().
585	</para>	585	</para>
586	<para>	586	<para>
587	Note that SCSI midlayer invokes hostt->queuecommand while	587	Note that SCSI midlayer invokes hostt->queuecommand while
588	holding host_set lock, so all above occur while holding	588	holding host_set lock, so all above occur while holding
589	host_set lock.	589	host_set lock.
590	</para>	590	</para>
591	</listitem>	591	</listitem>
592	</varlistentry>	592	</varlistentry>
593		593
594	</variablelist>	594	</variablelist>
595	</sect1>	595	</sect1>
596		596
597	<sect1><title>How commands are processed</title>	597	<sect1><title>How commands are processed</title>
598	<para>	598	<para>
599	Depending on which protocol and which controller are used,	599	Depending on which protocol and which controller are used,
600	commands are processed differently. For the purpose of	600	commands are processed differently. For the purpose of
601	discussion, a controller which uses taskfile interface and all	601	discussion, a controller which uses taskfile interface and all
602	standard callbacks is assumed.	602	standard callbacks is assumed.
603	</para>	603	</para>
604	<para>	604	<para>
605	Currently 6 ATA command protocols are used. They can be	605	Currently 6 ATA command protocols are used. They can be
606	sorted into the following four categories according to how	606	sorted into the following four categories according to how
607	they are processed.	607	they are processed.
608	</para>	608	</para>
609		609
610	<variablelist>	610	<variablelist>
611	<varlistentry><term>ATA NO DATA or DMA</term>	611	<varlistentry><term>ATA NO DATA or DMA</term>
612	<listitem>	612	<listitem>
613	<para>	613	<para>
614	ATA_PROT_NODATA and ATA_PROT_DMA fall into this category.	614	ATA_PROT_NODATA and ATA_PROT_DMA fall into this category.
615	These types of commands don't require any software	615	These types of commands don't require any software
616	intervention once issued. Device will raise interrupt on	616	intervention once issued. Device will raise interrupt on
617	completion.	617	completion.
618	</para>	618	</para>
619	</listitem>	619	</listitem>
620	</varlistentry>	620	</varlistentry>
621		621
622	<varlistentry><term>ATA PIO</term>	622	<varlistentry><term>ATA PIO</term>
623	<listitem>	623	<listitem>
624	<para>	624	<para>
625	ATA_PROT_PIO is in this category. libata currently	625	ATA_PROT_PIO is in this category. libata currently
626	implements PIO with polling. ATA_NIEN bit is set to turn	626	implements PIO with polling. ATA_NIEN bit is set to turn
627	off interrupt and pio_task on ata_wq performs polling and	627	off interrupt and pio_task on ata_wq performs polling and
628	IO.	628	IO.
629	</para>	629	</para>
630	</listitem>	630	</listitem>
631	</varlistentry>	631	</varlistentry>
632		632
633	<varlistentry><term>ATAPI NODATA or DMA</term>	633	<varlistentry><term>ATAPI NODATA or DMA</term>
634	<listitem>	634	<listitem>
635	<para>	635	<para>
636	ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this	636	ATA_PROT_ATAPI_NODATA and ATA_PROT_ATAPI_DMA are in this
637	category. packet_task is used to poll BSY bit after	637	category. packet_task is used to poll BSY bit after
638	issuing PACKET command. Once BSY is turned off by the	638	issuing PACKET command. Once BSY is turned off by the
639	device, packet_task transfers CDB and hands off processing	639	device, packet_task transfers CDB and hands off processing
640	to interrupt handler.	640	to interrupt handler.
641	</para>	641	</para>
642	</listitem>	642	</listitem>
643	</varlistentry>	643	</varlistentry>
644		644
645	<varlistentry><term>ATAPI PIO</term>	645	<varlistentry><term>ATAPI PIO</term>
646	<listitem>	646	<listitem>
647	<para>	647	<para>
648	ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set	648	ATA_PROT_ATAPI is in this category. ATA_NIEN bit is set
649	and, as in ATAPI NODATA or DMA, packet_task submits cdb.	649	and, as in ATAPI NODATA or DMA, packet_task submits cdb.
650	However, after submitting cdb, further processing (data	650	However, after submitting cdb, further processing (data
651	transfer) is handed off to pio_task.	651	transfer) is handed off to pio_task.
652	</para>	652	</para>
653	</listitem>	653	</listitem>
654	</varlistentry>	654	</varlistentry>
655	</variablelist>	655	</variablelist>
656	</sect1>	656	</sect1>
657		657
658	<sect1><title>How commands are completed</title>	658	<sect1><title>How commands are completed</title>
659	<para>	659	<para>
660	Once issued, all qc's are either completed with	660	Once issued, all qc's are either completed with
661	ata_qc_complete() or time out. For commands which are handled	661	ata_qc_complete() or time out. For commands which are handled
662	by interrupts, ata_host_intr() invokes ata_qc_complete(), and,	662	by interrupts, ata_host_intr() invokes ata_qc_complete(), and,
663	for PIO tasks, pio_task invokes ata_qc_complete(). In error	663	for PIO tasks, pio_task invokes ata_qc_complete(). In error
664	cases, packet_task may also complete commands.	664	cases, packet_task may also complete commands.
665	</para>	665	</para>
666	<para>	666	<para>
667	ata_qc_complete() does the following.	667	ata_qc_complete() does the following.
668	</para>	668	</para>
669		669
670	<orderedlist>	670	<orderedlist>
671		671
672	<listitem>	672	<listitem>
673	<para>	673	<para>
674	DMA memory is unmapped.	674	DMA memory is unmapped.
675	</para>	675	</para>
676	</listitem>	676	</listitem>
677		677
678	<listitem>	678	<listitem>
679	<para>	679	<para>
680	ATA_QCFLAG_ACTIVE is clared from qc->flags.	680	ATA_QCFLAG_ACTIVE is clared from qc->flags.
681	</para>	681	</para>
682	</listitem>	682	</listitem>
683		683
684	<listitem>	684	<listitem>
685	<para>	685	<para>
686	qc->complete_fn() callback is invoked. If the return value of	686	qc->complete_fn() callback is invoked. If the return value of
687	the callback is not zero. Completion is short circuited and	687	the callback is not zero. Completion is short circuited and
688	ata_qc_complete() returns.	688	ata_qc_complete() returns.
689	</para>	689	</para>
690	</listitem>	690	</listitem>
691		691
692	<listitem>	692	<listitem>
693	<para>	693	<para>
694	__ata_qc_complete() is called, which does	694	__ata_qc_complete() is called, which does
695	<orderedlist>	695	<orderedlist>
696		696
697	<listitem>	697	<listitem>
698	<para>	698	<para>
699	qc->flags is cleared to zero.	699	qc->flags is cleared to zero.
700	</para>	700	</para>
701	</listitem>	701	</listitem>
702		702
703	<listitem>	703	<listitem>
704	<para>	704	<para>
705	ap->active_tag and qc->tag are poisoned.	705	ap->active_tag and qc->tag are poisoned.
706	</para>	706	</para>
707	</listitem>	707	</listitem>
708		708
709	<listitem>	709	<listitem>
710	<para>	710	<para>
711	qc->waiting is claread & completed (in that order).	711	qc->waiting is claread & completed (in that order).
712	</para>	712	</para>
713	</listitem>	713	</listitem>
714		714
715	<listitem>	715	<listitem>
716	<para>	716	<para>
717	qc is deallocated by clearing appropriate bit in ap->qactive.	717	qc is deallocated by clearing appropriate bit in ap->qactive.
718	</para>	718	</para>
719	</listitem>	719	</listitem>
720		720
721	</orderedlist>	721	</orderedlist>
722	</para>	722	</para>
723	</listitem>	723	</listitem>
724		724
725	</orderedlist>	725	</orderedlist>
726		726
727	<para>	727	<para>
728	So, it basically notifies upper layer and deallocates qc. One	728	So, it basically notifies upper layer and deallocates qc. One
729	exception is short-circuit path in #3 which is used by	729	exception is short-circuit path in #3 which is used by
730	atapi_qc_complete().	730	atapi_qc_complete().
731	</para>	731	</para>
732	<para>	732	<para>
733	For all non-ATAPI commands, whether it fails or not, almost	733	For all non-ATAPI commands, whether it fails or not, almost
734	the same code path is taken and very little error handling	734	the same code path is taken and very little error handling
735	takes place. A qc is completed with success status if it	735	takes place. A qc is completed with success status if it
736	succeeded, with failed status otherwise.	736	succeeded, with failed status otherwise.
737	</para>	737	</para>
738	<para>	738	<para>
739	However, failed ATAPI commands require more handling as	739	However, failed ATAPI commands require more handling as
740	REQUEST SENSE is needed to acquire sense data. If an ATAPI	740	REQUEST SENSE is needed to acquire sense data. If an ATAPI
741	command fails, ata_qc_complete() is invoked with error status,	741	command fails, ata_qc_complete() is invoked with error status,
742	which in turn invokes atapi_qc_complete() via	742	which in turn invokes atapi_qc_complete() via
743	qc->complete_fn() callback.	743	qc->complete_fn() callback.
744	</para>	744	</para>
745	<para>	745	<para>
746	This makes atapi_qc_complete() set scmd->result to	746	This makes atapi_qc_complete() set scmd->result to
747	SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As	747	SAM_STAT_CHECK_CONDITION, complete the scmd and return 1. As
748	the sense data is empty but scmd->result is CHECK CONDITION,	748	the sense data is empty but scmd->result is CHECK CONDITION,
749	SCSI midlayer will invoke EH for the scmd, and returning 1	749	SCSI midlayer will invoke EH for the scmd, and returning 1
750	makes ata_qc_complete() to return without deallocating the qc.	750	makes ata_qc_complete() to return without deallocating the qc.
751	This leads us to ata_scsi_error() with partially completed qc.	751	This leads us to ata_scsi_error() with partially completed qc.
752	</para>	752	</para>
753		753
754	</sect1>	754	</sect1>
755		755
756	<sect1><title>ata_scsi_error()</title>	756	<sect1><title>ata_scsi_error()</title>
757	<para>	757	<para>
758	ata_scsi_error() is the current transportt->eh_strategy_handler()	758	ata_scsi_error() is the current transportt->eh_strategy_handler()
759	for libata. As discussed above, this will be entered in two	759	for libata. As discussed above, this will be entered in two
760	cases - timeout and ATAPI error completion. This function	760	cases - timeout and ATAPI error completion. This function
761	calls low level libata driver's eng_timeout() callback, the	761	calls low level libata driver's eng_timeout() callback, the
762	standard callback for which is ata_eng_timeout(). It checks	762	standard callback for which is ata_eng_timeout(). It checks
763	if a qc is active and calls ata_qc_timeout() on the qc if so.	763	if a qc is active and calls ata_qc_timeout() on the qc if so.
764	Actual error handling occurs in ata_qc_timeout().	764	Actual error handling occurs in ata_qc_timeout().
765	</para>	765	</para>
766	<para>	766	<para>
767	If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and	767	If EH is invoked for timeout, ata_qc_timeout() stops BMDMA and
768	completes the qc. Note that as we're currently in EH, we	768	completes the qc. Note that as we're currently in EH, we
769	cannot call scsi_done. As described in SCSI EH doc, a	769	cannot call scsi_done. As described in SCSI EH doc, a
770	recovered scmd should be either retried with	770	recovered scmd should be either retried with
771	scsi_queue_insert() or finished with scsi_finish_command().	771	scsi_queue_insert() or finished with scsi_finish_command().
772	Here, we override qc->scsidone with scsi_finish_command() and	772	Here, we override qc->scsidone with scsi_finish_command() and
773	calls ata_qc_complete().	773	calls ata_qc_complete().
774	</para>	774	</para>
775	<para>	775	<para>
776	If EH is invoked due to a failed ATAPI qc, the qc here is	776	If EH is invoked due to a failed ATAPI qc, the qc here is
777	completed but not deallocated. The purpose of this	777	completed but not deallocated. The purpose of this
778	half-completion is to use the qc as place holder to make EH	778	half-completion is to use the qc as place holder to make EH
779	code reach this place. This is a bit hackish, but it works.	779	code reach this place. This is a bit hackish, but it works.
780	</para>	780	</para>
781	<para>	781	<para>
782	Once control reaches here, the qc is deallocated by invoking	782	Once control reaches here, the qc is deallocated by invoking
783	__ata_qc_complete() explicitly. Then, internal qc for REQUEST	783	__ata_qc_complete() explicitly. Then, internal qc for REQUEST
784	SENSE is issued. Once sense data is acquired, scmd is	784	SENSE is issued. Once sense data is acquired, scmd is
785	finished by directly invoking scsi_finish_command() on the	785	finished by directly invoking scsi_finish_command() on the
786	scmd. Note that as we already have completed and deallocated	786	scmd. Note that as we already have completed and deallocated
787	the qc which was associated with the scmd, we don't need	787	the qc which was associated with the scmd, we don't need
788	to/cannot call ata_qc_complete() again.	788	to/cannot call ata_qc_complete() again.
789	</para>	789	</para>
790		790
791	</sect1>	791	</sect1>
792		792
793	<sect1><title>Problems with the current EH</title>	793	<sect1><title>Problems with the current EH</title>
794		794
795	<itemizedlist>	795	<itemizedlist>
796		796
797	<listitem>	797	<listitem>
798	<para>	798	<para>
799	Error representation is too crude. Currently any and all	799	Error representation is too crude. Currently any and all
800	error conditions are represented with ATA STATUS and ERROR	800	error conditions are represented with ATA STATUS and ERROR
801	registers. Errors which aren't ATA device errors are treated	801	registers. Errors which aren't ATA device errors are treated
802	as ATA device errors by setting ATA_ERR bit. Better error	802	as ATA device errors by setting ATA_ERR bit. Better error
803	descriptor which can properly represent ATA and other	803	descriptor which can properly represent ATA and other
804	errors/exceptions is needed.	804	errors/exceptions is needed.
805	</para>	805	</para>
806	</listitem>	806	</listitem>
807		807
808	<listitem>	808	<listitem>
809	<para>	809	<para>
810	When handling timeouts, no action is taken to make device	810	When handling timeouts, no action is taken to make device
811	forget about the timed out command and ready for new commands.	811	forget about the timed out command and ready for new commands.
812	</para>	812	</para>
813	</listitem>	813	</listitem>
814		814
815	<listitem>	815	<listitem>
816	<para>	816	<para>
817	EH handling via ata_scsi_error() is not properly protected	817	EH handling via ata_scsi_error() is not properly protected
818	from usual command processing. On EH entrance, the device is	818	from usual command processing. On EH entrance, the device is
819	not in quiescent state. Timed out commands may succeed or	819	not in quiescent state. Timed out commands may succeed or
820	fail any time. pio_task and atapi_task may still be running.	820	fail any time. pio_task and atapi_task may still be running.
821	</para>	821	</para>
822	</listitem>	822	</listitem>
823		823
824	<listitem>	824	<listitem>
825	<para>	825	<para>
826	Too weak error recovery. Devices / controllers causing HSM	826	Too weak error recovery. Devices / controllers causing HSM
827	mismatch errors and other errors quite often require reset to	827	mismatch errors and other errors quite often require reset to
828	return to known state. Also, advanced error handling is	828	return to known state. Also, advanced error handling is
829	necessary to support features like NCQ and hotplug.	829	necessary to support features like NCQ and hotplug.
830	</para>	830	</para>
831	</listitem>	831	</listitem>
832		832
833	<listitem>	833	<listitem>
834	<para>	834	<para>
835	ATA errors are directly handled in the interrupt handler and	835	ATA errors are directly handled in the interrupt handler and
836	PIO errors in pio_task. This is problematic for advanced	836	PIO errors in pio_task. This is problematic for advanced
837	error handling for the following reasons.	837	error handling for the following reasons.
838	</para>	838	</para>
839	<para>	839	<para>
840	First, advanced error handling often requires context and	840	First, advanced error handling often requires context and
841	internal qc execution.	841	internal qc execution.
842	</para>	842	</para>
843	<para>	843	<para>
844	Second, even a simple failure (say, CRC error) needs	844	Second, even a simple failure (say, CRC error) needs
845	information gathering and could trigger complex error handling	845	information gathering and could trigger complex error handling
846	(say, resetting & reconfiguring). Having multiple code	846	(say, resetting & reconfiguring). Having multiple code
847	paths to gather information, enter EH and trigger actions	847	paths to gather information, enter EH and trigger actions
848	makes life painful.	848	makes life painful.
849	</para>	849	</para>
850	<para>	850	<para>
851	Third, scattered EH code makes implementing low level drivers	851	Third, scattered EH code makes implementing low level drivers
852	difficult. Low level drivers override libata callbacks. If	852	difficult. Low level drivers override libata callbacks. If
853	EH is scattered over several places, each affected callbacks	853	EH is scattered over several places, each affected callbacks
854	should perform its part of error handling. This can be error	854	should perform its part of error handling. This can be error
855	prone and painful.	855	prone and painful.
856	</para>	856	</para>
857	</listitem>	857	</listitem>
858		858
859	</itemizedlist>	859	</itemizedlist>
860	</sect1>	860	</sect1>
861	</chapter>	861	</chapter>
862		862
863	<chapter id="libataExt">	863	<chapter id="libataExt">
864	<title>libata Library</title>	864	<title>libata Library</title>
865	!Edrivers/ata/libata-core.c	865	!Edrivers/ata/libata-core.c
866	</chapter>	866	</chapter>
867		867
868	<chapter id="libataInt">	868	<chapter id="libataInt">
869	<title>libata Core Internals</title>	869	<title>libata Core Internals</title>
870	!Idrivers/ata/libata-core.c	870	!Idrivers/ata/libata-core.c
871	</chapter>	871	</chapter>
872		872
873	<chapter id="libataScsiInt">	873	<chapter id="libataScsiInt">
874	<title>libata SCSI translation/emulation</title>	874	<title>libata SCSI translation/emulation</title>
875	!Edrivers/ata/libata-scsi.c	875	!Edrivers/ata/libata-scsi.c
876	!Idrivers/ata/libata-scsi.c	876	!Idrivers/ata/libata-scsi.c
877	</chapter>	877	</chapter>
878		878
879	<chapter id="ataExceptions">	879	<chapter id="ataExceptions">
880	<title>ATA errors and exceptions</title>	880	<title>ATA errors and exceptions</title>
881		881
882	<para>	882	<para>
883	This chapter tries to identify what error/exception conditions exist	883	This chapter tries to identify what error/exception conditions exist
884	for ATA/ATAPI devices and describe how they should be handled in	884	for ATA/ATAPI devices and describe how they should be handled in
885	implementation-neutral way.	885	implementation-neutral way.
886	</para>	886	</para>
887		887
888	<para>	888	<para>
889	The term 'error' is used to describe conditions where either an	889	The term 'error' is used to describe conditions where either an
890	explicit error condition is reported from device or a command has	890	explicit error condition is reported from device or a command has
891	timed out.	891	timed out.
892	</para>	892	</para>
893		893
894	<para>	894	<para>
895	The term 'exception' is either used to describe exceptional	895	The term 'exception' is either used to describe exceptional
896	conditions which are not errors (say, power or hotplug events), or	896	conditions which are not errors (say, power or hotplug events), or
897	to describe both errors and non-error exceptional conditions. Where	897	to describe both errors and non-error exceptional conditions. Where
898	explicit distinction between error and exception is necessary, the	898	explicit distinction between error and exception is necessary, the
899	term 'non-error exception' is used.	899	term 'non-error exception' is used.
900	</para>	900	</para>
901		901
902	<sect1 id="excat">	902	<sect1 id="excat">
903	<title>Exception categories</title>	903	<title>Exception categories</title>
904	<para>	904	<para>
905	Exceptions are described primarily with respect to legacy	905	Exceptions are described primarily with respect to legacy
906	taskfile + bus master IDE interface. If a controller provides	906	taskfile + bus master IDE interface. If a controller provides
907	other better mechanism for error reporting, mapping those into	907	other better mechanism for error reporting, mapping those into
908	categories described below shouldn't be difficult.	908	categories described below shouldn't be difficult.
909	</para>	909	</para>
910		910
911	<para>	911	<para>
912	In the following sections, two recovery actions - reset and	912	In the following sections, two recovery actions - reset and
913	reconfiguring transport - are mentioned. These are described	913	reconfiguring transport - are mentioned. These are described
914	further in <xref linkend="exrec"/>.	914	further in <xref linkend="exrec"/>.
915	</para>	915	</para>
916		916
917	<sect2 id="excatHSMviolation">	917	<sect2 id="excatHSMviolation">
918	<title>HSM violation</title>	918	<title>HSM violation</title>
919	<para>	919	<para>
920	This error is indicated when STATUS value doesn't match HSM	920	This error is indicated when STATUS value doesn't match HSM
921	requirement during issuing or excution any ATA/ATAPI command.	921	requirement during issuing or execution any ATA/ATAPI command.
922	</para>	922	</para>
923		923
924	<itemizedlist>	924	<itemizedlist>
925	<title>Examples</title>	925	<title>Examples</title>
926		926
927	<listitem>	927	<listitem>
928	<para>	928	<para>
929	ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying	929	ATA_STATUS doesn't contain !BSY && DRDY && !DRQ while trying
930	to issue a command.	930	to issue a command.
931	</para>	931	</para>
932	</listitem>	932	</listitem>
933		933
934	<listitem>	934	<listitem>
935	<para>	935	<para>
936	!BSY && !DRQ during PIO data transfer.	936	!BSY && !DRQ during PIO data transfer.
937	</para>	937	</para>
938	</listitem>	938	</listitem>
939		939
940	<listitem>	940	<listitem>
941	<para>	941	<para>
942	DRQ on command completion.	942	DRQ on command completion.
943	</para>	943	</para>
944	</listitem>	944	</listitem>
945		945
946	<listitem>	946	<listitem>
947	<para>	947	<para>
948	!BSY && ERR after CDB transfer starts but before the	948	!BSY && ERR after CDB transfer starts but before the
949	last byte of CDB is transferred. ATA/ATAPI standard states	949	last byte of CDB is transferred. ATA/ATAPI standard states
950	that "The device shall not terminate the PACKET command	950	that "The device shall not terminate the PACKET command
951	with an error before the last byte of the command packet has	951	with an error before the last byte of the command packet has
952	been written" in the error outputs description of PACKET	952	been written" in the error outputs description of PACKET
953	command and the state diagram doesn't include such	953	command and the state diagram doesn't include such
954	transitions.	954	transitions.
955	</para>	955	</para>
956	</listitem>	956	</listitem>
957		957
958	</itemizedlist>	958	</itemizedlist>
959		959
960	<para>	960	<para>
961	In these cases, HSM is violated and not much information	961	In these cases, HSM is violated and not much information
962	regarding the error can be acquired from STATUS or ERROR	962	regarding the error can be acquired from STATUS or ERROR
963	register. IOW, this error can be anything - driver bug,	963	register. IOW, this error can be anything - driver bug,
964	faulty device, controller and/or cable.	964	faulty device, controller and/or cable.
965	</para>	965	</para>
966		966
967	<para>	967	<para>
968	As HSM is violated, reset is necessary to restore known state.	968	As HSM is violated, reset is necessary to restore known state.
969	Reconfiguring transport for lower speed might be helpful too	969	Reconfiguring transport for lower speed might be helpful too
970	as transmission errors sometimes cause this kind of errors.	970	as transmission errors sometimes cause this kind of errors.
971	</para>	971	</para>
972	</sect2>	972	</sect2>
973		973
974	<sect2 id="excatDevErr">	974	<sect2 id="excatDevErr">
975	<title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title>	975	<title>ATA/ATAPI device error (non-NCQ / non-CHECK CONDITION)</title>
976		976
977	<para>	977	<para>
978	These are errors detected and reported by ATA/ATAPI devices	978	These are errors detected and reported by ATA/ATAPI devices
979	indicating device problems. For this type of errors, STATUS	979	indicating device problems. For this type of errors, STATUS
980	and ERROR register values are valid and describe error	980	and ERROR register values are valid and describe error
981	condition. Note that some of ATA bus errors are detected by	981	condition. Note that some of ATA bus errors are detected by
982	ATA/ATAPI devices and reported using the same mechanism as	982	ATA/ATAPI devices and reported using the same mechanism as
983	device errors. Those cases are described later in this	983	device errors. Those cases are described later in this
984	section.	984	section.
985	</para>	985	</para>
986		986
987	<para>	987	<para>
988	For ATA commands, this type of errors are indicated by !BSY	988	For ATA commands, this type of errors are indicated by !BSY
989	&& ERR during command execution and on completion.	989	&& ERR during command execution and on completion.
990	</para>	990	</para>
991		991
992	<para>For ATAPI commands,</para>	992	<para>For ATAPI commands,</para>
993		993
994	<itemizedlist>	994	<itemizedlist>
995		995
996	<listitem>	996	<listitem>
997	<para>	997	<para>
998	!BSY && ERR && ABRT right after issuing PACKET	998	!BSY && ERR && ABRT right after issuing PACKET
999	indicates that PACKET command is not supported and falls in	999	indicates that PACKET command is not supported and falls in
1000	this category.	1000	this category.
1001	</para>	1001	</para>
1002	</listitem>	1002	</listitem>
1003		1003
1004	<listitem>	1004	<listitem>
1005	<para>	1005	<para>
1006	!BSY && ERR(==CHK) && !ABRT after the last	1006	!BSY && ERR(==CHK) && !ABRT after the last
1007	byte of CDB is transferred indicates CHECK CONDITION and	1007	byte of CDB is transferred indicates CHECK CONDITION and
1008	doesn't fall in this category.	1008	doesn't fall in this category.
1009	</para>	1009	</para>
1010	</listitem>	1010	</listitem>
1011		1011
1012	<listitem>	1012	<listitem>
1013	<para>	1013	<para>
1014	!BSY && ERR(==CHK) && ABRT after the last byte	1014	!BSY && ERR(==CHK) && ABRT after the last byte
1015	of CDB is transferred probably indicates CHECK CONDITION and	1015	of CDB is transferred probably indicates CHECK CONDITION and
1016	doesn't fall in this category.	1016	doesn't fall in this category.
1017	</para>	1017	</para>
1018	</listitem>	1018	</listitem>
1019		1019
1020	</itemizedlist>	1020	</itemizedlist>
1021		1021
1022	<para>	1022	<para>
1023	Of errors detected as above, the followings are not ATA/ATAPI	1023	Of errors detected as above, the followings are not ATA/ATAPI
1024	device errors but ATA bus errors and should be handled	1024	device errors but ATA bus errors and should be handled
1025	according to <xref linkend="excatATAbusErr"/>.	1025	according to <xref linkend="excatATAbusErr"/>.
1026	</para>	1026	</para>
1027		1027
1028	<variablelist>	1028	<variablelist>
1029		1029
1030	<varlistentry>	1030	<varlistentry>
1031	<term>CRC error during data transfer</term>	1031	<term>CRC error during data transfer</term>
1032	<listitem>	1032	<listitem>
1033	<para>	1033	<para>
1034	This is indicated by ICRC bit in the ERROR register and	1034	This is indicated by ICRC bit in the ERROR register and
1035	means that corruption occurred during data transfer. Up to	1035	means that corruption occurred during data transfer. Up to
1036	ATA/ATAPI-7, the standard specifies that this bit is only	1036	ATA/ATAPI-7, the standard specifies that this bit is only
1037	applicable to UDMA transfers but ATA/ATAPI-8 draft revision	1037	applicable to UDMA transfers but ATA/ATAPI-8 draft revision
1038	1f says that the bit may be applicable to multiword DMA and	1038	1f says that the bit may be applicable to multiword DMA and
1039	PIO.	1039	PIO.
1040	</para>	1040	</para>
1041	</listitem>	1041	</listitem>
1042	</varlistentry>	1042	</varlistentry>
1043		1043
1044	<varlistentry>	1044	<varlistentry>
1045	<term>ABRT error during data transfer or on completion</term>	1045	<term>ABRT error during data transfer or on completion</term>
1046	<listitem>	1046	<listitem>
1047	<para>	1047	<para>
1048	Up to ATA/ATAPI-7, the standard specifies that ABRT could be	1048	Up to ATA/ATAPI-7, the standard specifies that ABRT could be
1049	set on ICRC errors and on cases where a device is not able	1049	set on ICRC errors and on cases where a device is not able
1050	to complete a command. Combined with the fact that MWDMA	1050	to complete a command. Combined with the fact that MWDMA
1051	and PIO transfer errors aren't allowed to use ICRC bit up to	1051	and PIO transfer errors aren't allowed to use ICRC bit up to
1052	ATA/ATAPI-7, it seems to imply that ABRT bit alone could	1052	ATA/ATAPI-7, it seems to imply that ABRT bit alone could
1053	indicate transfer errors.	1053	indicate transfer errors.
1054	</para>	1054	</para>
1055	<para>	1055	<para>
1056	However, ATA/ATAPI-8 draft revision 1f removes the part	1056	However, ATA/ATAPI-8 draft revision 1f removes the part
1057	that ICRC errors can turn on ABRT. So, this is kind of	1057	that ICRC errors can turn on ABRT. So, this is kind of
1058	gray area. Some heuristics are needed here.	1058	gray area. Some heuristics are needed here.
1059	</para>	1059	</para>
1060	</listitem>	1060	</listitem>
1061	</varlistentry>	1061	</varlistentry>
1062		1062
1063	</variablelist>	1063	</variablelist>
1064		1064
1065	<para>	1065	<para>
1066	ATA/ATAPI device errors can be further categorized as follows.	1066	ATA/ATAPI device errors can be further categorized as follows.
1067	</para>	1067	</para>
1068		1068
1069	<variablelist>	1069	<variablelist>
1070		1070
1071	<varlistentry>	1071	<varlistentry>
1072	<term>Media errors</term>	1072	<term>Media errors</term>
1073	<listitem>	1073	<listitem>
1074	<para>	1074	<para>
1075	This is indicated by UNC bit in the ERROR register. ATA	1075	This is indicated by UNC bit in the ERROR register. ATA
1076	devices reports UNC error only after certain number of	1076	devices reports UNC error only after certain number of
1077	retries cannot recover the data, so there's nothing much	1077	retries cannot recover the data, so there's nothing much
1078	else to do other than notifying upper layer.	1078	else to do other than notifying upper layer.
1079	</para>	1079	</para>
1080	<para>	1080	<para>
1081	READ and WRITE commands report CHS or LBA of the first	1081	READ and WRITE commands report CHS or LBA of the first
1082	failed sector but ATA/ATAPI standard specifies that the	1082	failed sector but ATA/ATAPI standard specifies that the
1083	amount of transferred data on error completion is	1083	amount of transferred data on error completion is
1084	indeterminate, so we cannot assume that sectors preceding	1084	indeterminate, so we cannot assume that sectors preceding
1085	the failed sector have been transferred and thus cannot	1085	the failed sector have been transferred and thus cannot
1086	complete those sectors successfully as SCSI does.	1086	complete those sectors successfully as SCSI does.
1087	</para>	1087	</para>
1088	</listitem>	1088	</listitem>
1089	</varlistentry>	1089	</varlistentry>
1090		1090
1091	<varlistentry>	1091	<varlistentry>
1092	<term>Media changed / media change requested error</term>	1092	<term>Media changed / media change requested error</term>
1093	<listitem>	1093	<listitem>
1094	<para>	1094	<para>
1095	<<TODO: fill here>>	1095	<<TODO: fill here>>
1096	</para>	1096	</para>
1097	</listitem>	1097	</listitem>
1098	</varlistentry>	1098	</varlistentry>
1099		1099
1100	<varlistentry><term>Address error</term>	1100	<varlistentry><term>Address error</term>
1101	<listitem>	1101	<listitem>
1102	<para>	1102	<para>
1103	This is indicated by IDNF bit in the ERROR register.	1103	This is indicated by IDNF bit in the ERROR register.
1104	Report to upper layer.	1104	Report to upper layer.
1105	</para>	1105	</para>
1106	</listitem>	1106	</listitem>
1107	</varlistentry>	1107	</varlistentry>
1108		1108
1109	<varlistentry><term>Other errors</term>	1109	<varlistentry><term>Other errors</term>
1110	<listitem>	1110	<listitem>
1111	<para>	1111	<para>
1112	This can be invalid command or parameter indicated by ABRT	1112	This can be invalid command or parameter indicated by ABRT
1113	ERROR bit or some other error condition. Note that ABRT	1113	ERROR bit or some other error condition. Note that ABRT
1114	bit can indicate a lot of things including ICRC and Address	1114	bit can indicate a lot of things including ICRC and Address
1115	errors. Heuristics needed.	1115	errors. Heuristics needed.
1116	</para>	1116	</para>
1117	</listitem>	1117	</listitem>
1118	</varlistentry>	1118	</varlistentry>
1119		1119
1120	</variablelist>	1120	</variablelist>
1121		1121
1122	<para>	1122	<para>
1123	Depending on commands, not all STATUS/ERROR bits are	1123	Depending on commands, not all STATUS/ERROR bits are
1124	applicable. These non-applicable bits are marked with	1124	applicable. These non-applicable bits are marked with
1125	"na" in the output descriptions but up to ATA/ATAPI-7	1125	"na" in the output descriptions but up to ATA/ATAPI-7
1126	no definition of "na" can be found. However,	1126	no definition of "na" can be found. However,
1127	ATA/ATAPI-8 draft revision 1f describes "N/A" as	1127	ATA/ATAPI-8 draft revision 1f describes "N/A" as
1128	follows.	1128	follows.
1129	</para>	1129	</para>
1130		1130
1131	<blockquote>	1131	<blockquote>
1132	<variablelist>	1132	<variablelist>
1133	<varlistentry><term>3.2.3.3a N/A</term>	1133	<varlistentry><term>3.2.3.3a N/A</term>
1134	<listitem>	1134	<listitem>
1135	<para>	1135	<para>
1136	A keyword the indicates a field has no defined value in	1136	A keyword the indicates a field has no defined value in
1137	this standard and should not be checked by the host or	1137	this standard and should not be checked by the host or
1138	device. N/A fields should be cleared to zero.	1138	device. N/A fields should be cleared to zero.
1139	</para>	1139	</para>
1140	</listitem>	1140	</listitem>
1141	</varlistentry>	1141	</varlistentry>
1142	</variablelist>	1142	</variablelist>
1143	</blockquote>	1143	</blockquote>
1144		1144
1145	<para>	1145	<para>
1146	So, it seems reasonable to assume that "na" bits are	1146	So, it seems reasonable to assume that "na" bits are
1147	cleared to zero by devices and thus need no explicit masking.	1147	cleared to zero by devices and thus need no explicit masking.
1148	</para>	1148	</para>
1149		1149
1150	</sect2>	1150	</sect2>
1151		1151
1152	<sect2 id="excatATAPIcc">	1152	<sect2 id="excatATAPIcc">
1153	<title>ATAPI device CHECK CONDITION</title>	1153	<title>ATAPI device CHECK CONDITION</title>
1154		1154
1155	<para>	1155	<para>
1156	ATAPI device CHECK CONDITION error is indicated by set CHK bit	1156	ATAPI device CHECK CONDITION error is indicated by set CHK bit
1157	(ERR bit) in the STATUS register after the last byte of CDB is	1157	(ERR bit) in the STATUS register after the last byte of CDB is
1158	transferred for a PACKET command. For this kind of errors,	1158	transferred for a PACKET command. For this kind of errors,
1159	sense data should be acquired to gather information regarding	1159	sense data should be acquired to gather information regarding
1160	the errors. REQUEST SENSE packet command should be used to	1160	the errors. REQUEST SENSE packet command should be used to
1161	acquire sense data.	1161	acquire sense data.
1162	</para>	1162	</para>
1163		1163
1164	<para>	1164	<para>
1165	Once sense data is acquired, this type of errors can be	1165	Once sense data is acquired, this type of errors can be
1166	handled similary to other SCSI errors. Note that sense data	1166	handled similary to other SCSI errors. Note that sense data
1167	may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR	1167	may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR
1168	&& ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such	1168	&& ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such
1169	cases, the error should be considered as an ATA bus error and	1169	cases, the error should be considered as an ATA bus error and
1170	handled according to <xref linkend="excatATAbusErr"/>.	1170	handled according to <xref linkend="excatATAbusErr"/>.
1171	</para>	1171	</para>
1172		1172
1173	</sect2>	1173	</sect2>
1174		1174
1175	<sect2 id="excatNCQerr">	1175	<sect2 id="excatNCQerr">
1176	<title>ATA device error (NCQ)</title>	1176	<title>ATA device error (NCQ)</title>
1177		1177
1178	<para>	1178	<para>
1179	NCQ command error is indicated by cleared BSY and set ERR bit	1179	NCQ command error is indicated by cleared BSY and set ERR bit
1180	during NCQ command phase (one or more NCQ commands	1180	during NCQ command phase (one or more NCQ commands
1181	outstanding). Although STATUS and ERROR registers will	1181	outstanding). Although STATUS and ERROR registers will
1182	contain valid values describing the error, READ LOG EXT is	1182	contain valid values describing the error, READ LOG EXT is
1183	required to clear the error condition, determine which command	1183	required to clear the error condition, determine which command
1184	has failed and acquire more information.	1184	has failed and acquire more information.
1185	</para>	1185	</para>
1186		1186
1187	<para>	1187	<para>
1188	READ LOG EXT Log Page 10h reports which tag has failed and	1188	READ LOG EXT Log Page 10h reports which tag has failed and
1189	taskfile register values describing the error. With this	1189	taskfile register values describing the error. With this
1190	information the failed command can be handled as a normal ATA	1190	information the failed command can be handled as a normal ATA
1191	command error as in <xref linkend="excatDevErr"/> and all	1191	command error as in <xref linkend="excatDevErr"/> and all
1192	other in-flight commands must be retried. Note that this	1192	other in-flight commands must be retried. Note that this
1193	retry should not be counted - it's likely that commands	1193	retry should not be counted - it's likely that commands
1194	retried this way would have completed normally if it were not	1194	retried this way would have completed normally if it were not
1195	for the failed command.	1195	for the failed command.
1196	</para>	1196	</para>
1197		1197
1198	<para>	1198	<para>
1199	Note that ATA bus errors can be reported as ATA device NCQ	1199	Note that ATA bus errors can be reported as ATA device NCQ
1200	errors. This should be handled as described in <xref	1200	errors. This should be handled as described in <xref
1201	linkend="excatATAbusErr"/>.	1201	linkend="excatATAbusErr"/>.
1202	</para>	1202	</para>
1203		1203
1204	<para>	1204	<para>
1205	If READ LOG EXT Log Page 10h fails or reports NQ, we're	1205	If READ LOG EXT Log Page 10h fails or reports NQ, we're
1206	thoroughly screwed. This condition should be treated	1206	thoroughly screwed. This condition should be treated
1207	according to <xref linkend="excatHSMviolation"/>.	1207	according to <xref linkend="excatHSMviolation"/>.
1208	</para>	1208	</para>
1209		1209
1210	</sect2>	1210	</sect2>
1211		1211
1212	<sect2 id="excatATAbusErr">	1212	<sect2 id="excatATAbusErr">
1213	<title>ATA bus error</title>	1213	<title>ATA bus error</title>
1214		1214
1215	<para>	1215	<para>
1216	ATA bus error means that data corruption occurred during	1216	ATA bus error means that data corruption occurred during
1217	transmission over ATA bus (SATA or PATA). This type of errors	1217	transmission over ATA bus (SATA or PATA). This type of errors
1218	can be indicated by	1218	can be indicated by
1219	</para>	1219	</para>
1220		1220
1221	<itemizedlist>	1221	<itemizedlist>
1222		1222
1223	<listitem>	1223	<listitem>
1224	<para>	1224	<para>
1225	ICRC or ABRT error as described in <xref linkend="excatDevErr"/>.	1225	ICRC or ABRT error as described in <xref linkend="excatDevErr"/>.
1226	</para>	1226	</para>
1227	</listitem>	1227	</listitem>
1228		1228
1229	<listitem>	1229	<listitem>
1230	<para>	1230	<para>
1231	Controller-specific error completion with error information	1231	Controller-specific error completion with error information
1232	indicating transmission error.	1232	indicating transmission error.
1233	</para>	1233	</para>
1234	</listitem>	1234	</listitem>
1235		1235
1236	<listitem>	1236	<listitem>
1237	<para>	1237	<para>
1238	On some controllers, command timeout. In this case, there may	1238	On some controllers, command timeout. In this case, there may
1239	be a mechanism to determine that the timeout is due to	1239	be a mechanism to determine that the timeout is due to
1240	transmission error.	1240	transmission error.
1241	</para>	1241	</para>
1242	</listitem>	1242	</listitem>
1243		1243
1244	<listitem>	1244	<listitem>
1245	<para>	1245	<para>
1246	Unknown/random errors, timeouts and all sorts of weirdities.	1246	Unknown/random errors, timeouts and all sorts of weirdities.
1247	</para>	1247	</para>
1248	</listitem>	1248	</listitem>
1249		1249
1250	</itemizedlist>	1250	</itemizedlist>
1251		1251
1252	<para>	1252	<para>
1253	As described above, transmission errors can cause wide variety	1253	As described above, transmission errors can cause wide variety
1254	of symptoms ranging from device ICRC error to random device	1254	of symptoms ranging from device ICRC error to random device
1255	lockup, and, for many cases, there is no way to tell if an	1255	lockup, and, for many cases, there is no way to tell if an
1256	error condition is due to transmission error or not;	1256	error condition is due to transmission error or not;
1257	therefore, it's necessary to employ some kind of heuristic	1257	therefore, it's necessary to employ some kind of heuristic
1258	when dealing with errors and timeouts. For example,	1258	when dealing with errors and timeouts. For example,
1259	encountering repetitive ABRT errors for known supported	1259	encountering repetitive ABRT errors for known supported
1260	command is likely to indicate ATA bus error.	1260	command is likely to indicate ATA bus error.
1261	</para>	1261	</para>
1262		1262
1263	<para>	1263	<para>
1264	Once it's determined that ATA bus errors have possibly	1264	Once it's determined that ATA bus errors have possibly
1265	occurred, lowering ATA bus transmission speed is one of	1265	occurred, lowering ATA bus transmission speed is one of
1266	actions which may alleviate the problem. See <xref	1266	actions which may alleviate the problem. See <xref
1267	linkend="exrecReconf"/> for more information.	1267	linkend="exrecReconf"/> for more information.
1268	</para>	1268	</para>
1269		1269
1270	</sect2>	1270	</sect2>
1271		1271
1272	<sect2 id="excatPCIbusErr">	1272	<sect2 id="excatPCIbusErr">
1273	<title>PCI bus error</title>	1273	<title>PCI bus error</title>
1274		1274
1275	<para>	1275	<para>
1276	Data corruption or other failures during transmission over PCI	1276	Data corruption or other failures during transmission over PCI
1277	(or other system bus). For standard BMDMA, this is indicated	1277	(or other system bus). For standard BMDMA, this is indicated
1278	by Error bit in the BMDMA Status register. This type of	1278	by Error bit in the BMDMA Status register. This type of
1279	errors must be logged as it indicates something is very wrong	1279	errors must be logged as it indicates something is very wrong
1280	with the system. Resetting host controller is recommended.	1280	with the system. Resetting host controller is recommended.
1281	</para>	1281	</para>
1282		1282
1283	</sect2>	1283	</sect2>
1284		1284
1285	<sect2 id="excatLateCompletion">	1285	<sect2 id="excatLateCompletion">
1286	<title>Late completion</title>	1286	<title>Late completion</title>
1287		1287
1288	<para>	1288	<para>
1289	This occurs when timeout occurs and the timeout handler finds	1289	This occurs when timeout occurs and the timeout handler finds
1290	out that the timed out command has completed successfully or	1290	out that the timed out command has completed successfully or
1291	with error. This is usually caused by lost interrupts. This	1291	with error. This is usually caused by lost interrupts. This
1292	type of errors must be logged. Resetting host controller is	1292	type of errors must be logged. Resetting host controller is
1293	recommended.	1293	recommended.
1294	</para>	1294	</para>
1295		1295
1296	</sect2>	1296	</sect2>
1297		1297
1298	<sect2 id="excatUnknown">	1298	<sect2 id="excatUnknown">
1299	<title>Unknown error (timeout)</title>	1299	<title>Unknown error (timeout)</title>
1300		1300
1301	<para>	1301	<para>
1302	This is when timeout occurs and the command is still	1302	This is when timeout occurs and the command is still
1303	processing or the host and device are in unknown state. When	1303	processing or the host and device are in unknown state. When
1304	this occurs, HSM could be in any valid or invalid state. To	1304	this occurs, HSM could be in any valid or invalid state. To
1305	bring the device to known state and make it forget about the	1305	bring the device to known state and make it forget about the
1306	timed out command, resetting is necessary. The timed out	1306	timed out command, resetting is necessary. The timed out
1307	command may be retried.	1307	command may be retried.
1308	</para>	1308	</para>
1309		1309
1310	<para>	1310	<para>
1311	Timeouts can also be caused by transmission errors. Refer to	1311	Timeouts can also be caused by transmission errors. Refer to
1312	<xref linkend="excatATAbusErr"/> for more details.	1312	<xref linkend="excatATAbusErr"/> for more details.
1313	</para>	1313	</para>
1314		1314
1315	</sect2>	1315	</sect2>
1316		1316
1317	<sect2 id="excatHoplugPM">	1317	<sect2 id="excatHoplugPM">
1318	<title>Hotplug and power management exceptions</title>	1318	<title>Hotplug and power management exceptions</title>
1319		1319
1320	<para>	1320	<para>
1321	<<TODO: fill here>>	1321	<<TODO: fill here>>
1322	</para>	1322	</para>
1323		1323
1324	</sect2>	1324	</sect2>
1325		1325
1326	</sect1>	1326	</sect1>
1327		1327
1328	<sect1 id="exrec">	1328	<sect1 id="exrec">
1329	<title>EH recovery actions</title>	1329	<title>EH recovery actions</title>
1330		1330
1331	<para>	1331	<para>
1332	This section discusses several important recovery actions.	1332	This section discusses several important recovery actions.
1333	</para>	1333	</para>
1334		1334
1335	<sect2 id="exrecClr">	1335	<sect2 id="exrecClr">
1336	<title>Clearing error condition</title>	1336	<title>Clearing error condition</title>
1337		1337
1338	<para>	1338	<para>
1339	Many controllers require its error registers to be cleared by	1339	Many controllers require its error registers to be cleared by
1340	error handler. Different controllers may have different	1340	error handler. Different controllers may have different
1341	requirements.	1341	requirements.
1342	</para>	1342	</para>
1343		1343
1344	<para>	1344	<para>
1345	For SATA, it's strongly recommended to clear at least SError	1345	For SATA, it's strongly recommended to clear at least SError
1346	register during error handling.	1346	register during error handling.
1347	</para>	1347	</para>
1348	</sect2>	1348	</sect2>
1349		1349
1350	<sect2 id="exrecRst">	1350	<sect2 id="exrecRst">
1351	<title>Reset</title>	1351	<title>Reset</title>
1352		1352
1353	<para>	1353	<para>
1354	During EH, resetting is necessary in the following cases.	1354	During EH, resetting is necessary in the following cases.
1355	</para>	1355	</para>
1356		1356
1357	<itemizedlist>	1357	<itemizedlist>
1358		1358
1359	<listitem>	1359	<listitem>
1360	<para>	1360	<para>
1361	HSM is in unknown or invalid state	1361	HSM is in unknown or invalid state
1362	</para>	1362	</para>
1363	</listitem>	1363	</listitem>
1364		1364
1365	<listitem>	1365	<listitem>
1366	<para>	1366	<para>
1367	HBA is in unknown or invalid state	1367	HBA is in unknown or invalid state
1368	</para>	1368	</para>
1369	</listitem>	1369	</listitem>
1370		1370
1371	<listitem>	1371	<listitem>
1372	<para>	1372	<para>
1373	EH needs to make HBA/device forget about in-flight commands	1373	EH needs to make HBA/device forget about in-flight commands
1374	</para>	1374	</para>
1375	</listitem>	1375	</listitem>
1376		1376
1377	<listitem>	1377	<listitem>
1378	<para>	1378	<para>
1379	HBA/device behaves weirdly	1379	HBA/device behaves weirdly
1380	</para>	1380	</para>
1381	</listitem>	1381	</listitem>
1382		1382
1383	</itemizedlist>	1383	</itemizedlist>
1384		1384
1385	<para>	1385	<para>
1386	Resetting during EH might be a good idea regardless of error	1386	Resetting during EH might be a good idea regardless of error
1387	condition to improve EH robustness. Whether to reset both or	1387	condition to improve EH robustness. Whether to reset both or
1388	either one of HBA and device depends on situation but the	1388	either one of HBA and device depends on situation but the
1389	following scheme is recommended.	1389	following scheme is recommended.
1390	</para>	1390	</para>
1391		1391
1392	<itemizedlist>	1392	<itemizedlist>
1393		1393
1394	<listitem>	1394	<listitem>
1395	<para>	1395	<para>
1396	When it's known that HBA is in ready state but ATA/ATAPI	1396	When it's known that HBA is in ready state but ATA/ATAPI
1397	device is in unknown state, reset only device.	1397	device is in unknown state, reset only device.
1398	</para>	1398	</para>
1399	</listitem>	1399	</listitem>
1400		1400
1401	<listitem>	1401	<listitem>
1402	<para>	1402	<para>
1403	If HBA is in unknown state, reset both HBA and device.	1403	If HBA is in unknown state, reset both HBA and device.
1404	</para>	1404	</para>
1405	</listitem>	1405	</listitem>
1406		1406
1407	</itemizedlist>	1407	</itemizedlist>
1408		1408
1409	<para>	1409	<para>
1410	HBA resetting is implementation specific. For a controller	1410	HBA resetting is implementation specific. For a controller
1411	complying to taskfile/BMDMA PCI IDE, stopping active DMA	1411	complying to taskfile/BMDMA PCI IDE, stopping active DMA
1412	transaction may be sufficient iff BMDMA state is the only HBA	1412	transaction may be sufficient iff BMDMA state is the only HBA
1413	context. But even mostly taskfile/BMDMA PCI IDE complying	1413	context. But even mostly taskfile/BMDMA PCI IDE complying
1414	controllers may have implementation specific requirements and	1414	controllers may have implementation specific requirements and
1415	mechanism to reset themselves. This must be addressed by	1415	mechanism to reset themselves. This must be addressed by
1416	specific drivers.	1416	specific drivers.
1417	</para>	1417	</para>
1418		1418
1419	<para>	1419	<para>
1420	OTOH, ATA/ATAPI standard describes in detail ways to reset	1420	OTOH, ATA/ATAPI standard describes in detail ways to reset
1421	ATA/ATAPI devices.	1421	ATA/ATAPI devices.
1422	</para>	1422	</para>
1423		1423
1424	<variablelist>	1424	<variablelist>
1425		1425
1426	<varlistentry><term>PATA hardware reset</term>	1426	<varlistentry><term>PATA hardware reset</term>
1427	<listitem>	1427	<listitem>
1428	<para>	1428	<para>
1429	This is hardware initiated device reset signalled with	1429	This is hardware initiated device reset signalled with
1430	asserted PATA RESET- signal. There is no standard way to	1430	asserted PATA RESET- signal. There is no standard way to
1431	initiate hardware reset from software although some	1431	initiate hardware reset from software although some
1432	hardware provides registers that allow driver to directly	1432	hardware provides registers that allow driver to directly
1433	tweak the RESET- signal.	1433	tweak the RESET- signal.
1434	</para>	1434	</para>
1435	</listitem>	1435	</listitem>
1436	</varlistentry>	1436	</varlistentry>
1437		1437
1438	<varlistentry><term>Software reset</term>	1438	<varlistentry><term>Software reset</term>
1439	<listitem>	1439	<listitem>
1440	<para>	1440	<para>
1441	This is achieved by turning CONTROL SRST bit on for at	1441	This is achieved by turning CONTROL SRST bit on for at
1442	least 5us. Both PATA and SATA support it but, in case of	1442	least 5us. Both PATA and SATA support it but, in case of
1443	SATA, this may require controller-specific support as the	1443	SATA, this may require controller-specific support as the
1444	second Register FIS to clear SRST should be transmitted	1444	second Register FIS to clear SRST should be transmitted
1445	while BSY bit is still set. Note that on PATA, this resets	1445	while BSY bit is still set. Note that on PATA, this resets
1446	both master and slave devices on a channel.	1446	both master and slave devices on a channel.
1447	</para>	1447	</para>
1448	</listitem>	1448	</listitem>
1449	</varlistentry>	1449	</varlistentry>
1450		1450
1451	<varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term>	1451	<varlistentry><term>EXECUTE DEVICE DIAGNOSTIC command</term>
1452	<listitem>	1452	<listitem>
1453	<para>	1453	<para>
1454	Although ATA/ATAPI standard doesn't describe exactly, EDD	1454	Although ATA/ATAPI standard doesn't describe exactly, EDD
1455	implies some level of resetting, possibly similar level	1455	implies some level of resetting, possibly similar level
1456	with software reset. Host-side EDD protocol can be handled	1456	with software reset. Host-side EDD protocol can be handled
1457	with normal command processing and most SATA controllers	1457	with normal command processing and most SATA controllers
1458	should be able to handle EDD's just like other commands.	1458	should be able to handle EDD's just like other commands.
1459	As in software reset, EDD affects both devices on a PATA	1459	As in software reset, EDD affects both devices on a PATA
1460	bus.	1460	bus.
1461	</para>	1461	</para>
1462	<para>	1462	<para>
1463	Although EDD does reset devices, this doesn't suit error	1463	Although EDD does reset devices, this doesn't suit error
1464	handling as EDD cannot be issued while BSY is set and it's	1464	handling as EDD cannot be issued while BSY is set and it's
1465	unclear how it will act when device is in unknown/weird	1465	unclear how it will act when device is in unknown/weird
1466	state.	1466	state.
1467	</para>	1467	</para>
1468	</listitem>	1468	</listitem>
1469	</varlistentry>	1469	</varlistentry>
1470		1470
1471	<varlistentry><term>ATAPI DEVICE RESET command</term>	1471	<varlistentry><term>ATAPI DEVICE RESET command</term>
1472	<listitem>	1472	<listitem>
1473	<para>	1473	<para>
1474	This is very similar to software reset except that reset	1474	This is very similar to software reset except that reset
1475	can be restricted to the selected device without affecting	1475	can be restricted to the selected device without affecting
1476	the other device sharing the cable.	1476	the other device sharing the cable.
1477	</para>	1477	</para>
1478	</listitem>	1478	</listitem>
1479	</varlistentry>	1479	</varlistentry>
1480		1480
1481	<varlistentry><term>SATA phy reset</term>	1481	<varlistentry><term>SATA phy reset</term>
1482	<listitem>	1482	<listitem>
1483	<para>	1483	<para>
1484	This is the preferred way of resetting a SATA device. In	1484	This is the preferred way of resetting a SATA device. In
1485	effect, it's identical to PATA hardware reset. Note that	1485	effect, it's identical to PATA hardware reset. Note that
1486	this can be done with the standard SCR Control register.	1486	this can be done with the standard SCR Control register.
1487	As such, it's usually easier to implement than software	1487	As such, it's usually easier to implement than software
1488	reset.	1488	reset.
1489	</para>	1489	</para>
1490	</listitem>	1490	</listitem>
1491	</varlistentry>	1491	</varlistentry>
1492		1492
1493	</variablelist>	1493	</variablelist>
1494		1494
1495	<para>	1495	<para>
1496	One more thing to consider when resetting devices is that	1496	One more thing to consider when resetting devices is that
1497	resetting clears certain configuration parameters and they	1497	resetting clears certain configuration parameters and they
1498	need to be set to their previous or newly adjusted values	1498	need to be set to their previous or newly adjusted values
1499	after reset.	1499	after reset.
1500	</para>	1500	</para>
1501		1501
1502	<para>	1502	<para>
1503	Parameters affected are.	1503	Parameters affected are.
1504	</para>	1504	</para>
1505		1505
1506	<itemizedlist>	1506	<itemizedlist>
1507		1507
1508	<listitem>	1508	<listitem>
1509	<para>	1509	<para>
1510	CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)	1510	CHS set up with INITIALIZE DEVICE PARAMETERS (seldom used)
1511	</para>	1511	</para>
1512	</listitem>	1512	</listitem>
1513		1513
1514	<listitem>	1514	<listitem>
1515	<para>	1515	<para>
1516	Parameters set with SET FEATURES including transfer mode setting	1516	Parameters set with SET FEATURES including transfer mode setting
1517	</para>	1517	</para>
1518	</listitem>	1518	</listitem>
1519		1519
1520	<listitem>	1520	<listitem>
1521	<para>	1521	<para>
1522	Block count set with SET MULTIPLE MODE	1522	Block count set with SET MULTIPLE MODE
1523	</para>	1523	</para>
1524	</listitem>	1524	</listitem>
1525		1525
1526	<listitem>	1526	<listitem>
1527	<para>	1527	<para>
1528	Other parameters (SET MAX, MEDIA LOCK...)	1528	Other parameters (SET MAX, MEDIA LOCK...)
1529	</para>	1529	</para>
1530	</listitem>	1530	</listitem>
1531		1531
1532	</itemizedlist>	1532	</itemizedlist>
1533		1533
1534	<para>	1534	<para>
1535	ATA/ATAPI standard specifies that some parameters must be	1535	ATA/ATAPI standard specifies that some parameters must be
1536	maintained across hardware or software reset, but doesn't	1536	maintained across hardware or software reset, but doesn't
1537	strictly specify all of them. Always reconfiguring needed	1537	strictly specify all of them. Always reconfiguring needed
1538	parameters after reset is required for robustness. Note that	1538	parameters after reset is required for robustness. Note that
1539	this also applies when resuming from deep sleep (power-off).	1539	this also applies when resuming from deep sleep (power-off).
1540	</para>	1540	</para>
1541		1541
1542	<para>	1542	<para>
1543	Also, ATA/ATAPI standard requires that IDENTIFY DEVICE /	1543	Also, ATA/ATAPI standard requires that IDENTIFY DEVICE /
1544	IDENTIFY PACKET DEVICE is issued after any configuration	1544	IDENTIFY PACKET DEVICE is issued after any configuration
1545	parameter is updated or a hardware reset and the result used	1545	parameter is updated or a hardware reset and the result used
1546	for further operation. OS driver is required to implement	1546	for further operation. OS driver is required to implement
1547	revalidation mechanism to support this.	1547	revalidation mechanism to support this.
1548	</para>	1548	</para>
1549		1549
1550	</sect2>	1550	</sect2>
1551		1551
1552	<sect2 id="exrecReconf">	1552	<sect2 id="exrecReconf">
1553	<title>Reconfigure transport</title>	1553	<title>Reconfigure transport</title>
1554		1554
1555	<para>	1555	<para>
1556	For both PATA and SATA, a lot of corners are cut for cheap	1556	For both PATA and SATA, a lot of corners are cut for cheap
1557	connectors, cables or controllers and it's quite common to see	1557	connectors, cables or controllers and it's quite common to see
1558	high transmission error rate. This can be mitigated by	1558	high transmission error rate. This can be mitigated by
1559	lowering transmission speed.	1559	lowering transmission speed.
1560	</para>	1560	</para>
1561		1561
1562	<para>	1562	<para>
1563	The following is a possible scheme Jeff Garzik suggested.	1563	The following is a possible scheme Jeff Garzik suggested.
1564	</para>	1564	</para>
1565		1565
1566	<blockquote>	1566	<blockquote>
1567	<para>	1567	<para>
1568	If more than $N (3?) transmission errors happen in 15 minutes,	1568	If more than $N (3?) transmission errors happen in 15 minutes,
1569	</para>	1569	</para>
1570	<itemizedlist>	1570	<itemizedlist>
1571	<listitem>	1571	<listitem>
1572	<para>	1572	<para>
1573	if SATA, decrease SATA PHY speed. if speed cannot be decreased,	1573	if SATA, decrease SATA PHY speed. if speed cannot be decreased,
1574	</para>	1574	</para>
1575	</listitem>	1575	</listitem>
1576	<listitem>	1576	<listitem>
1577	<para>	1577	<para>
1578	decrease UDMA xfer speed. if at UDMA0, switch to PIO4,	1578	decrease UDMA xfer speed. if at UDMA0, switch to PIO4,
1579	</para>	1579	</para>
1580	</listitem>	1580	</listitem>
1581	<listitem>	1581	<listitem>
1582	<para>	1582	<para>
1583	decrease PIO xfer speed. if at PIO3, complain, but continue	1583	decrease PIO xfer speed. if at PIO3, complain, but continue
1584	</para>	1584	</para>
1585	</listitem>	1585	</listitem>
1586	</itemizedlist>	1586	</itemizedlist>
1587	</blockquote>	1587	</blockquote>
1588		1588
1589	</sect2>	1589	</sect2>
1590		1590
1591	</sect1>	1591	</sect1>
1592		1592
1593	</chapter>	1593	</chapter>
1594		1594
1595	<chapter id="PiixInt">	1595	<chapter id="PiixInt">
1596	<title>ata_piix Internals</title>	1596	<title>ata_piix Internals</title>
1597	!Idrivers/ata/ata_piix.c	1597	!Idrivers/ata/ata_piix.c
1598	</chapter>	1598	</chapter>
1599		1599
1600	<chapter id="SILInt">	1600	<chapter id="SILInt">
1601	<title>sata_sil Internals</title>	1601	<title>sata_sil Internals</title>
1602	!Idrivers/ata/sata_sil.c	1602	!Idrivers/ata/sata_sil.c
1603	</chapter>	1603	</chapter>
1604		1604
1605	<chapter id="libataThanks">	1605	<chapter id="libataThanks">
1606	<title>Thanks</title>	1606	<title>Thanks</title>
1607	<para>	1607	<para>
1608	The bulk of the ATA knowledge comes thanks to long conversations with	1608	The bulk of the ATA knowledge comes thanks to long conversations with
1609	Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA	1609	Andre Hedrick (www.linux-ide.org), and long hours pondering the ATA
1610	and SCSI specifications.	1610	and SCSI specifications.
1611	</para>	1611	</para>
1612	<para>	1612	<para>
1613	Thanks to Alan Cox for pointing out similarities	1613	Thanks to Alan Cox for pointing out similarities
1614	between SATA and SCSI, and in general for motivation to hack on	1614	between SATA and SCSI, and in general for motivation to hack on
1615	libata.	1615	libata.
1616	</para>	1616	</para>
1617	<para>	1617	<para>
1618	libata's device detection	1618	libata's device detection
1619	method, ata_pio_devchk, and in general all the early probing was	1619	method, ata_pio_devchk, and in general all the early probing was
1620	based on extensive study of Hale Landis's probe/reset code in his	1620	based on extensive study of Hale Landis's probe/reset code in his
1621	ATADRVR driver (www.ata-atapi.com).	1621	ATADRVR driver (www.ata-atapi.com).
1622	</para>	1622	</para>
1623	</chapter>	1623	</chapter>
1624		1624
1625	</book>	1625	</book>
1626		1626

Documentation/DocBook/media/v4l/controls.xml

Diff comments View file @ c94bed8

1	<section id="control">	1	<section id="control">
2	<title>User Controls</title>	2	<title>User Controls</title>
3		3
4	<para>Devices typically have a number of user-settable controls	4	<para>Devices typically have a number of user-settable controls
5	such as brightness, saturation and so on, which would be presented to	5	such as brightness, saturation and so on, which would be presented to
6	the user on a graphical user interface. But, different devices	6	the user on a graphical user interface. But, different devices
7	will have different controls available, and furthermore, the range of	7	will have different controls available, and furthermore, the range of
8	possible values, and the default value will vary from device to	8	possible values, and the default value will vary from device to
9	device. The control ioctls provide the information and a mechanism to	9	device. The control ioctls provide the information and a mechanism to
10	create a nice user interface for these controls that will work	10	create a nice user interface for these controls that will work
11	correctly with any device.</para>	11	correctly with any device.</para>
12		12
13	<para>All controls are accessed using an ID value. V4L2 defines	13	<para>All controls are accessed using an ID value. V4L2 defines
14	several IDs for specific purposes. Drivers can also implement their	14	several IDs for specific purposes. Drivers can also implement their
15	own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>	15	own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
16	and higher values. The pre-defined control IDs have the prefix	16	and higher values. The pre-defined control IDs have the prefix
17	<constant>V4L2_CID_</constant>, and are listed in <xref	17	<constant>V4L2_CID_</constant>, and are listed in <xref
18	linkend="control-id" />. The ID is used when querying the attributes of	18	linkend="control-id" />. The ID is used when querying the attributes of
19	a control, and when getting or setting the current value.</para>	19	a control, and when getting or setting the current value.</para>
20		20
21	<para>Generally applications should present controls to the user	21	<para>Generally applications should present controls to the user
22	without assumptions about their purpose. Each control comes with a	22	without assumptions about their purpose. Each control comes with a
23	name string the user is supposed to understand. When the purpose is	23	name string the user is supposed to understand. When the purpose is
24	non-intuitive the driver writer should provide a user manual, a user	24	non-intuitive the driver writer should provide a user manual, a user
25	interface plug-in or a driver specific panel application. Predefined	25	interface plug-in or a driver specific panel application. Predefined
26	IDs were introduced to change a few controls programmatically, for	26	IDs were introduced to change a few controls programmatically, for
27	example to mute a device during a channel switch.</para>	27	example to mute a device during a channel switch.</para>
28		28
29	<para>Drivers may enumerate different controls after switching	29	<para>Drivers may enumerate different controls after switching
30	the current video input or output, tuner or modulator, or audio input	30	the current video input or output, tuner or modulator, or audio input
31	or output. Different in the sense of other bounds, another default and	31	or output. Different in the sense of other bounds, another default and
32	current value, step size or other menu items. A control with a certain	32	current value, step size or other menu items. A control with a certain
33	<emphasis>custom</emphasis> ID can also change name and	33	<emphasis>custom</emphasis> ID can also change name and
34	type.<footnote>	34	type.<footnote>
35	<para>It will be more convenient for applications if drivers	35	<para>It will be more convenient for applications if drivers
36	make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but	36	make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but
37	that was never required.</para>	37	that was never required.</para>
38	</footnote> Control values are stored globally, they do not	38	</footnote> Control values are stored globally, they do not
39	change when switching except to stay within the reported bounds. They	39	change when switching except to stay within the reported bounds. They
40	also do not change &eg; when the device is opened or closed, when the	40	also do not change &eg; when the device is opened or closed, when the
41	tuner radio frequency is changed or generally never without	41	tuner radio frequency is changed or generally never without
42	application request. Since V4L2 specifies no event mechanism, panel	42	application request. Since V4L2 specifies no event mechanism, panel
43	applications intended to cooperate with other panel applications (be	43	applications intended to cooperate with other panel applications (be
44	they built into a larger application, as a TV viewer) may need to	44	they built into a larger application, as a TV viewer) may need to
45	regularly poll control values to update their user	45	regularly poll control values to update their user
46	interface.<footnote>	46	interface.<footnote>
47	<para>Applications could call an ioctl to request events.	47	<para>Applications could call an ioctl to request events.
48	After another process called &VIDIOC-S-CTRL; or another ioctl changing	48	After another process called &VIDIOC-S-CTRL; or another ioctl changing
49	shared properties the &func-select; function would indicate	49	shared properties the &func-select; function would indicate
50	readability until any ioctl (querying the properties) is	50	readability until any ioctl (querying the properties) is
51	called.</para>	51	called.</para>
52	</footnote></para>	52	</footnote></para>
53		53
54	<para>	54	<para>
55	All controls use machine endianness.	55	All controls use machine endianness.
56	</para>	56	</para>
57		57
58	<table pgwide="1" frame="none" id="control-id">	58	<table pgwide="1" frame="none" id="control-id">
59	<title>Control IDs</title>	59	<title>Control IDs</title>
60	<tgroup cols="3">	60	<tgroup cols="3">
61	&cs-def;	61	&cs-def;
62	<thead>	62	<thead>
63	<row>	63	<row>
64	<entry>ID</entry>	64	<entry>ID</entry>
65	<entry>Type</entry>	65	<entry>Type</entry>
66	<entry>Description</entry>	66	<entry>Description</entry>
67	</row>	67	</row>
68	</thead>	68	</thead>
69	<tbody valign="top">	69	<tbody valign="top">
70	<row>	70	<row>
71	<entry><constant>V4L2_CID_BASE</constant></entry>	71	<entry><constant>V4L2_CID_BASE</constant></entry>
72	<entry></entry>	72	<entry></entry>
73	<entry>First predefined ID, equal to	73	<entry>First predefined ID, equal to
74	<constant>V4L2_CID_BRIGHTNESS</constant>.</entry>	74	<constant>V4L2_CID_BRIGHTNESS</constant>.</entry>
75	</row>	75	</row>
76	<row>	76	<row>
77	<entry><constant>V4L2_CID_USER_BASE</constant></entry>	77	<entry><constant>V4L2_CID_USER_BASE</constant></entry>
78	<entry></entry>	78	<entry></entry>
79	<entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry>	79	<entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry>
80	</row>	80	</row>
81	<row>	81	<row>
82	<entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>	82	<entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
83	<entry>integer</entry>	83	<entry>integer</entry>
84	<entry>Picture brightness, or more precisely, the black	84	<entry>Picture brightness, or more precisely, the black
85	level.</entry>	85	level.</entry>
86	</row>	86	</row>
87	<row>	87	<row>
88	<entry><constant>V4L2_CID_CONTRAST</constant></entry>	88	<entry><constant>V4L2_CID_CONTRAST</constant></entry>
89	<entry>integer</entry>	89	<entry>integer</entry>
90	<entry>Picture contrast or luma gain.</entry>	90	<entry>Picture contrast or luma gain.</entry>
91	</row>	91	</row>
92	<row>	92	<row>
93	<entry><constant>V4L2_CID_SATURATION</constant></entry>	93	<entry><constant>V4L2_CID_SATURATION</constant></entry>
94	<entry>integer</entry>	94	<entry>integer</entry>
95	<entry>Picture color saturation or chroma gain.</entry>	95	<entry>Picture color saturation or chroma gain.</entry>
96	</row>	96	</row>
97	<row>	97	<row>
98	<entry><constant>V4L2_CID_HUE</constant></entry>	98	<entry><constant>V4L2_CID_HUE</constant></entry>
99	<entry>integer</entry>	99	<entry>integer</entry>
100	<entry>Hue or color balance.</entry>	100	<entry>Hue or color balance.</entry>
101	</row>	101	</row>
102	<row>	102	<row>
103	<entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>	103	<entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
104	<entry>integer</entry>	104	<entry>integer</entry>
105	<entry>Overall audio volume. Note some drivers also	105	<entry>Overall audio volume. Note some drivers also
106	provide an OSS or ALSA mixer interface.</entry>	106	provide an OSS or ALSA mixer interface.</entry>
107	</row>	107	</row>
108	<row>	108	<row>
109	<entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>	109	<entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
110	<entry>integer</entry>	110	<entry>integer</entry>
111	<entry>Audio stereo balance. Minimum corresponds to all	111	<entry>Audio stereo balance. Minimum corresponds to all
112	the way left, maximum to right.</entry>	112	the way left, maximum to right.</entry>
113	</row>	113	</row>
114	<row>	114	<row>
115	<entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>	115	<entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
116	<entry>integer</entry>	116	<entry>integer</entry>
117	<entry>Audio bass adjustment.</entry>	117	<entry>Audio bass adjustment.</entry>
118	</row>	118	</row>
119	<row>	119	<row>
120	<entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>	120	<entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
121	<entry>integer</entry>	121	<entry>integer</entry>
122	<entry>Audio treble adjustment.</entry>	122	<entry>Audio treble adjustment.</entry>
123	</row>	123	</row>
124	<row>	124	<row>
125	<entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry>	125	<entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry>
126	<entry>boolean</entry>	126	<entry>boolean</entry>
127	<entry>Mute audio, &ie; set the volume to zero, however	127	<entry>Mute audio, &ie; set the volume to zero, however
128	without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like	128	without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like
129	ALSA drivers, V4L2 drivers must mute at load time to avoid excessive	129	ALSA drivers, V4L2 drivers must mute at load time to avoid excessive
130	noise. Actually the entire device should be reset to a low power	130	noise. Actually the entire device should be reset to a low power
131	consumption state.</entry>	131	consumption state.</entry>
132	</row>	132	</row>
133	<row>	133	<row>
134	<entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry>	134	<entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry>
135	<entry>boolean</entry>	135	<entry>boolean</entry>
136	<entry>Loudness mode (bass boost).</entry>	136	<entry>Loudness mode (bass boost).</entry>
137	</row>	137	</row>
138	<row>	138	<row>
139	<entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry>	139	<entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry>
140	<entry>integer</entry>	140	<entry>integer</entry>
141	<entry>Another name for brightness (not a synonym of	141	<entry>Another name for brightness (not a synonym of
142	<constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated	142	<constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated
143	and should not be used in new drivers and applications.</entry>	143	and should not be used in new drivers and applications.</entry>
144	</row>	144	</row>
145	<row>	145	<row>
146	<entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry>	146	<entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry>
147	<entry>boolean</entry>	147	<entry>boolean</entry>
148	<entry>Automatic white balance (cameras).</entry>	148	<entry>Automatic white balance (cameras).</entry>
149	</row>	149	</row>
150	<row>	150	<row>
151	<entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry>	151	<entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry>
152	<entry>button</entry>	152	<entry>button</entry>
153	<entry>This is an action control. When set (the value is	153	<entry>This is an action control. When set (the value is
154	ignored), the device will do a white balance and then hold the current	154	ignored), the device will do a white balance and then hold the current
155	setting. Contrast this with the boolean	155	setting. Contrast this with the boolean
156	<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when	156	<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when
157	activated, keeps adjusting the white balance.</entry>	157	activated, keeps adjusting the white balance.</entry>
158	</row>	158	</row>
159	<row>	159	<row>
160	<entry><constant>V4L2_CID_RED_BALANCE</constant></entry>	160	<entry><constant>V4L2_CID_RED_BALANCE</constant></entry>
161	<entry>integer</entry>	161	<entry>integer</entry>
162	<entry>Red chroma balance.</entry>	162	<entry>Red chroma balance.</entry>
163	</row>	163	</row>
164	<row>	164	<row>
165	<entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry>	165	<entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry>
166	<entry>integer</entry>	166	<entry>integer</entry>
167	<entry>Blue chroma balance.</entry>	167	<entry>Blue chroma balance.</entry>
168	</row>	168	</row>
169	<row>	169	<row>
170	<entry><constant>V4L2_CID_GAMMA</constant></entry>	170	<entry><constant>V4L2_CID_GAMMA</constant></entry>
171	<entry>integer</entry>	171	<entry>integer</entry>
172	<entry>Gamma adjust.</entry>	172	<entry>Gamma adjust.</entry>
173	</row>	173	</row>
174	<row>	174	<row>
175	<entry><constant>V4L2_CID_WHITENESS</constant></entry>	175	<entry><constant>V4L2_CID_WHITENESS</constant></entry>
176	<entry>integer</entry>	176	<entry>integer</entry>
177	<entry>Whiteness for grey-scale devices. This is a synonym	177	<entry>Whiteness for grey-scale devices. This is a synonym
178	for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated	178	for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated
179	and should not be used in new drivers and applications.</entry>	179	and should not be used in new drivers and applications.</entry>
180	</row>	180	</row>
181	<row>	181	<row>
182	<entry><constant>V4L2_CID_EXPOSURE</constant></entry>	182	<entry><constant>V4L2_CID_EXPOSURE</constant></entry>
183	<entry>integer</entry>	183	<entry>integer</entry>
184	<entry>Exposure (cameras). [Unit?]</entry>	184	<entry>Exposure (cameras). [Unit?]</entry>
185	</row>	185	</row>
186	<row>	186	<row>
187	<entry><constant>V4L2_CID_AUTOGAIN</constant></entry>	187	<entry><constant>V4L2_CID_AUTOGAIN</constant></entry>
188	<entry>boolean</entry>	188	<entry>boolean</entry>
189	<entry>Automatic gain/exposure control.</entry>	189	<entry>Automatic gain/exposure control.</entry>
190	</row>	190	</row>
191	<row>	191	<row>
192	<entry><constant>V4L2_CID_GAIN</constant></entry>	192	<entry><constant>V4L2_CID_GAIN</constant></entry>
193	<entry>integer</entry>	193	<entry>integer</entry>
194	<entry>Gain control.</entry>	194	<entry>Gain control.</entry>
195	</row>	195	</row>
196	<row>	196	<row>
197	<entry><constant>V4L2_CID_HFLIP</constant></entry>	197	<entry><constant>V4L2_CID_HFLIP</constant></entry>
198	<entry>boolean</entry>	198	<entry>boolean</entry>
199	<entry>Mirror the picture horizontally.</entry>	199	<entry>Mirror the picture horizontally.</entry>
200	</row>	200	</row>
201	<row>	201	<row>
202	<entry><constant>V4L2_CID_VFLIP</constant></entry>	202	<entry><constant>V4L2_CID_VFLIP</constant></entry>
203	<entry>boolean</entry>	203	<entry>boolean</entry>
204	<entry>Mirror the picture vertically.</entry>	204	<entry>Mirror the picture vertically.</entry>
205	</row>	205	</row>
206	<row>	206	<row>
207	<entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry>	207	<entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry>
208	<entry>integer</entry>	208	<entry>integer</entry>
209	<entry>Horizontal image centering. This control is	209	<entry>Horizontal image centering. This control is
210	deprecated. New drivers and applications should use the <link	210	deprecated. New drivers and applications should use the <link
211	linkend="camera-controls">Camera class controls</link>	211	linkend="camera-controls">Camera class controls</link>
212	<constant>V4L2_CID_PAN_ABSOLUTE</constant>,	212	<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
213	<constant>V4L2_CID_PAN_RELATIVE</constant> and	213	<constant>V4L2_CID_PAN_RELATIVE</constant> and
214	<constant>V4L2_CID_PAN_RESET</constant> instead.</entry>	214	<constant>V4L2_CID_PAN_RESET</constant> instead.</entry>
215	</row>	215	</row>
216	<row>	216	<row>
217	<entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant>	217	<entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant>
218	(formerly <constant>V4L2_CID_VCENTER</constant>)</entry>	218	(formerly <constant>V4L2_CID_VCENTER</constant>)</entry>
219	<entry>integer</entry>	219	<entry>integer</entry>
220	<entry>Vertical image centering. Centering is intended to	220	<entry>Vertical image centering. Centering is intended to
221	<emphasis>physically</emphasis> adjust cameras. For image cropping see	221	<emphasis>physically</emphasis> adjust cameras. For image cropping see
222	<xref linkend="crop" />, for clipping <xref linkend="overlay" />. This	222	<xref linkend="crop" />, for clipping <xref linkend="overlay" />. This
223	control is deprecated. New drivers and applications should use the	223	control is deprecated. New drivers and applications should use the
224	<link linkend="camera-controls">Camera class controls</link>	224	<link linkend="camera-controls">Camera class controls</link>
225	<constant>V4L2_CID_TILT_ABSOLUTE</constant>,	225	<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
226	<constant>V4L2_CID_TILT_RELATIVE</constant> and	226	<constant>V4L2_CID_TILT_RELATIVE</constant> and
227	<constant>V4L2_CID_TILT_RESET</constant> instead.</entry>	227	<constant>V4L2_CID_TILT_RESET</constant> instead.</entry>
228	</row>	228	</row>
229	<row id="v4l2-power-line-frequency">	229	<row id="v4l2-power-line-frequency">
230	<entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry>	230	<entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry>
231	<entry>enum</entry>	231	<entry>enum</entry>
232	<entry>Enables a power line frequency filter to avoid	232	<entry>Enables a power line frequency filter to avoid
233	flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are:	233	flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are:
234	<constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0),	234	<constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0),
235	<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1),	235	<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1),
236	<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2) and	236	<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2) and
237	<constant>V4L2_CID_POWER_LINE_FREQUENCY_AUTO</constant> (3).</entry>	237	<constant>V4L2_CID_POWER_LINE_FREQUENCY_AUTO</constant> (3).</entry>
238	</row>	238	</row>
239	<row>	239	<row>
240	<entry><constant>V4L2_CID_HUE_AUTO</constant></entry>	240	<entry><constant>V4L2_CID_HUE_AUTO</constant></entry>
241	<entry>boolean</entry>	241	<entry>boolean</entry>
242	<entry>Enables automatic hue control by the device. The	242	<entry>Enables automatic hue control by the device. The
243	effect of setting <constant>V4L2_CID_HUE</constant> while automatic	243	effect of setting <constant>V4L2_CID_HUE</constant> while automatic
244	hue control is enabled is undefined, drivers should ignore such	244	hue control is enabled is undefined, drivers should ignore such
245	request.</entry>	245	request.</entry>
246	</row>	246	</row>
247	<row>	247	<row>
248	<entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry>	248	<entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry>
249	<entry>integer</entry>	249	<entry>integer</entry>
250	<entry>This control specifies the white balance settings	250	<entry>This control specifies the white balance settings
251	as a color temperature in Kelvin. A driver should have a minimum of	251	as a color temperature in Kelvin. A driver should have a minimum of
252	2800 (incandescent) to 6500 (daylight). For more information about	252	2800 (incandescent) to 6500 (daylight). For more information about
253	color temperature see <ulink	253	color temperature see <ulink
254	url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry>	254	url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry>
255	</row>	255	</row>
256	<row>	256	<row>
257	<entry><constant>V4L2_CID_SHARPNESS</constant></entry>	257	<entry><constant>V4L2_CID_SHARPNESS</constant></entry>
258	<entry>integer</entry>	258	<entry>integer</entry>
259	<entry>Adjusts the sharpness filters in a camera. The	259	<entry>Adjusts the sharpness filters in a camera. The
260	minimum value disables the filters, higher values give a sharper	260	minimum value disables the filters, higher values give a sharper
261	picture.</entry>	261	picture.</entry>
262	</row>	262	</row>
263	<row>	263	<row>
264	<entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry>	264	<entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry>
265	<entry>integer</entry>	265	<entry>integer</entry>
266	<entry>Adjusts the backlight compensation in a camera. The	266	<entry>Adjusts the backlight compensation in a camera. The
267	minimum value disables backlight compensation.</entry>	267	minimum value disables backlight compensation.</entry>
268	</row>	268	</row>
269	<row>	269	<row>
270	<entry><constant>V4L2_CID_CHROMA_AGC</constant></entry>	270	<entry><constant>V4L2_CID_CHROMA_AGC</constant></entry>
271	<entry>boolean</entry>	271	<entry>boolean</entry>
272	<entry>Chroma automatic gain control.</entry>	272	<entry>Chroma automatic gain control.</entry>
273	</row>	273	</row>
274	<row>	274	<row>
275	<entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry>	275	<entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry>
276	<entry>integer</entry>	276	<entry>integer</entry>
277	<entry>Adjusts the Chroma gain control (for use when chroma AGC	277	<entry>Adjusts the Chroma gain control (for use when chroma AGC
278	is disabled).</entry>	278	is disabled).</entry>
279	</row>	279	</row>
280	<row>	280	<row>
281	<entry><constant>V4L2_CID_COLOR_KILLER</constant></entry>	281	<entry><constant>V4L2_CID_COLOR_KILLER</constant></entry>
282	<entry>boolean</entry>	282	<entry>boolean</entry>
283	<entry>Enable the color killer (&ie; force a black & white image in case of a weak video signal).</entry>	283	<entry>Enable the color killer (&ie; force a black & white image in case of a weak video signal).</entry>
284	</row>	284	</row>
285	<row id="v4l2-colorfx">	285	<row id="v4l2-colorfx">
286	<entry><constant>V4L2_CID_COLORFX</constant></entry>	286	<entry><constant>V4L2_CID_COLORFX</constant></entry>
287	<entry>enum</entry>	287	<entry>enum</entry>
288	<entry>Selects a color effect. Possible values for	288	<entry>Selects a color effect. Possible values for
289	<constant>enum v4l2_colorfx</constant> are:	289	<constant>enum v4l2_colorfx</constant> are:
290	<constant>V4L2_COLORFX_NONE</constant> (0),	290	<constant>V4L2_COLORFX_NONE</constant> (0),
291	<constant>V4L2_COLORFX_BW</constant> (1),	291	<constant>V4L2_COLORFX_BW</constant> (1),
292	<constant>V4L2_COLORFX_SEPIA</constant> (2),	292	<constant>V4L2_COLORFX_SEPIA</constant> (2),
293	<constant>V4L2_COLORFX_NEGATIVE</constant> (3),	293	<constant>V4L2_COLORFX_NEGATIVE</constant> (3),
294	<constant>V4L2_COLORFX_EMBOSS</constant> (4),	294	<constant>V4L2_COLORFX_EMBOSS</constant> (4),
295	<constant>V4L2_COLORFX_SKETCH</constant> (5),	295	<constant>V4L2_COLORFX_SKETCH</constant> (5),
296	<constant>V4L2_COLORFX_SKY_BLUE</constant> (6),	296	<constant>V4L2_COLORFX_SKY_BLUE</constant> (6),
297	<constant>V4L2_COLORFX_GRASS_GREEN</constant> (7),	297	<constant>V4L2_COLORFX_GRASS_GREEN</constant> (7),
298	<constant>V4L2_COLORFX_SKIN_WHITEN</constant> (8) and	298	<constant>V4L2_COLORFX_SKIN_WHITEN</constant> (8) and
299	<constant>V4L2_COLORFX_VIVID</constant> (9).</entry>	299	<constant>V4L2_COLORFX_VIVID</constant> (9).</entry>
300	</row>	300	</row>
301	<row>	301	<row>
302	<entry><constant>V4L2_CID_ROTATE</constant></entry>	302	<entry><constant>V4L2_CID_ROTATE</constant></entry>
303	<entry>integer</entry>	303	<entry>integer</entry>
304	<entry>Rotates the image by specified angle. Common angles are 90,	304	<entry>Rotates the image by specified angle. Common angles are 90,
305	270 and 180. Rotating the image to 90 and 270 will reverse the height	305	270 and 180. Rotating the image to 90 and 270 will reverse the height
306	and width of the display window. It is necessary to set the new height and	306	and width of the display window. It is necessary to set the new height and
307	width of the picture using the &VIDIOC-S-FMT; ioctl according to	307	width of the picture using the &VIDIOC-S-FMT; ioctl according to
308	the rotation angle selected.</entry>	308	the rotation angle selected.</entry>
309	</row>	309	</row>
310	<row>	310	<row>
311	<entry><constant>V4L2_CID_BG_COLOR</constant></entry>	311	<entry><constant>V4L2_CID_BG_COLOR</constant></entry>
312	<entry>integer</entry>	312	<entry>integer</entry>
313	<entry>Sets the background color on the current output device.	313	<entry>Sets the background color on the current output device.
314	Background color needs to be specified in the RGB24 format. The	314	Background color needs to be specified in the RGB24 format. The
315	supplied 32 bit value is interpreted as bits 0-7 Red color information,	315	supplied 32 bit value is interpreted as bits 0-7 Red color information,
316	bits 8-15 Green color information, bits 16-23 Blue color	316	bits 8-15 Green color information, bits 16-23 Blue color
317	information and bits 24-31 must be zero.</entry>	317	information and bits 24-31 must be zero.</entry>
318	</row>	318	</row>
319	<row>	319	<row>
320	<entry><constant>V4L2_CID_ILLUMINATORS_1</constant>	320	<entry><constant>V4L2_CID_ILLUMINATORS_1</constant>
321	<constant>V4L2_CID_ILLUMINATORS_2</constant></entry>	321	<constant>V4L2_CID_ILLUMINATORS_2</constant></entry>
322	<entry>boolean</entry>	322	<entry>boolean</entry>
323	<entry>Switch on or off the illuminator 1 or 2 of the device	323	<entry>Switch on or off the illuminator 1 or 2 of the device
324	(usually a microscope).</entry>	324	(usually a microscope).</entry>
325	</row>	325	</row>
326	<row>	326	<row>
327	<entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry>	327	<entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry>
328	<entry>integer</entry>	328	<entry>integer</entry>
329	<entry>This is a read-only control that can be read by the application	329	<entry>This is a read-only control that can be read by the application
330	and used as a hint to determine the number of CAPTURE buffers to pass to REQBUFS.	330	and used as a hint to determine the number of CAPTURE buffers to pass to REQBUFS.
331	The value is the minimum number of CAPTURE buffers that is necessary for hardware	331	The value is the minimum number of CAPTURE buffers that is necessary for hardware
332	to work.</entry>	332	to work.</entry>
333	</row>	333	</row>
334	<row>	334	<row>
335	<entry><constant>V4L2_CID_MIN_BUFFERS_FOR_OUTPUT</constant></entry>	335	<entry><constant>V4L2_CID_MIN_BUFFERS_FOR_OUTPUT</constant></entry>
336	<entry>integer</entry>	336	<entry>integer</entry>
337	<entry>This is a read-only control that can be read by the application	337	<entry>This is a read-only control that can be read by the application
338	and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS.	338	and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS.
339	The value is the minimum number of OUTPUT buffers that is necessary for hardware	339	The value is the minimum number of OUTPUT buffers that is necessary for hardware
340	to work.</entry>	340	to work.</entry>
341	</row>	341	</row>
342	<row id="v4l2-alpha-component">	342	<row id="v4l2-alpha-component">
343	<entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry>	343	<entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry>
344	<entry>integer</entry>	344	<entry>integer</entry>
345	<entry> Sets the alpha color component on the capture device or on	345	<entry> Sets the alpha color component on the capture device or on
346	the capture buffer queue of a mem-to-mem device. When a mem-to-mem	346	the capture buffer queue of a mem-to-mem device. When a mem-to-mem
347	device produces frame format that includes an alpha component	347	device produces frame format that includes an alpha component
348	(e.g. <link linkend="rgb-formats">packed RGB image formats</link>)	348	(e.g. <link linkend="rgb-formats">packed RGB image formats</link>)
349	and the alpha value is not defined by the mem-to-mem input data	349	and the alpha value is not defined by the mem-to-mem input data
350	this control lets you select the alpha component value of all	350	this control lets you select the alpha component value of all
351	pixels. It is applicable to any pixel format that contains an alpha	351	pixels. It is applicable to any pixel format that contains an alpha
352	component.	352	component.
353	</entry>	353	</entry>
354	</row>	354	</row>
355	<row>	355	<row>
356	<entry><constant>V4L2_CID_LASTP1</constant></entry>	356	<entry><constant>V4L2_CID_LASTP1</constant></entry>
357	<entry></entry>	357	<entry></entry>
358	<entry>End of the predefined control IDs (currently	358	<entry>End of the predefined control IDs (currently
359	<constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry>	359	<constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry>
360	</row>	360	</row>
361	<row>	361	<row>
362	<entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry>	362	<entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry>
363	<entry></entry>	363	<entry></entry>
364	<entry>ID of the first custom (driver specific) control.	364	<entry>ID of the first custom (driver specific) control.
365	Applications depending on particular custom controls should check the	365	Applications depending on particular custom controls should check the
366	driver name and version, see <xref linkend="querycap" />.</entry>	366	driver name and version, see <xref linkend="querycap" />.</entry>
367	</row>	367	</row>
368	</tbody>	368	</tbody>
369	</tgroup>	369	</tgroup>
370	</table>	370	</table>
371		371
372	<para>Applications can enumerate the available controls with the	372	<para>Applications can enumerate the available controls with the
373	&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a	373	&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a
374	control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.	374	control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.
375	Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,	375	Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
376	<constant>VIDIOC_G_CTRL</constant> and	376	<constant>VIDIOC_G_CTRL</constant> and
377	<constant>VIDIOC_S_CTRL</constant> when the device has one or more	377	<constant>VIDIOC_S_CTRL</constant> when the device has one or more
378	controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or	378	controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
379	more menu type controls.</para>	379	more menu type controls.</para>
380		380
381	<example>	381	<example>
382	<title>Enumerating all controls</title>	382	<title>Enumerating all controls</title>
383		383
384	<programlisting>	384	<programlisting>
385	&v4l2-queryctrl; queryctrl;	385	&v4l2-queryctrl; queryctrl;
386	&v4l2-querymenu; querymenu;	386	&v4l2-querymenu; querymenu;
387		387
388	static void	388	static void
389	enumerate_menu (void)	389	enumerate_menu (void)
390	{	390	{
391	printf (" Menu items:\n");	391	printf (" Menu items:\n");
392		392
393	memset (&querymenu, 0, sizeof (querymenu));	393	memset (&querymenu, 0, sizeof (querymenu));
394	querymenu.id = queryctrl.id;	394	querymenu.id = queryctrl.id;
395		395
396	for (querymenu.index = queryctrl.minimum;	396	for (querymenu.index = queryctrl.minimum;
397	querymenu.index <= queryctrl.maximum;	397	querymenu.index <= queryctrl.maximum;
398	querymenu.index++) {	398	querymenu.index++) {
399	if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) {	399	if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &querymenu)) {
400	printf (" %s\n", querymenu.name);	400	printf (" %s\n", querymenu.name);
401	}	401	}
402	}	402	}
403	}	403	}
404		404
405	memset (&queryctrl, 0, sizeof (queryctrl));	405	memset (&queryctrl, 0, sizeof (queryctrl));
406		406
407	for (queryctrl.id = V4L2_CID_BASE;	407	for (queryctrl.id = V4L2_CID_BASE;
408	queryctrl.id < V4L2_CID_LASTP1;	408	queryctrl.id < V4L2_CID_LASTP1;
409	queryctrl.id++) {	409	queryctrl.id++) {
410	if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) {	410	if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) {
411	if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)	411	if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
412	continue;	412	continue;
413		413
414	printf ("Control %s\n", queryctrl.name);	414	printf ("Control %s\n", queryctrl.name);
415		415
416	if (queryctrl.type == V4L2_CTRL_TYPE_MENU)	416	if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
417	enumerate_menu ();	417	enumerate_menu ();
418	} else {	418	} else {
419	if (errno == EINVAL)	419	if (errno == EINVAL)
420	continue;	420	continue;
421		421
422	perror ("VIDIOC_QUERYCTRL");	422	perror ("VIDIOC_QUERYCTRL");
423	exit (EXIT_FAILURE);	423	exit (EXIT_FAILURE);
424	}	424	}
425	}	425	}
426		426
427	for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;	427	for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
428	queryctrl.id++) {	428	queryctrl.id++) {
429	if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) {	429	if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) {
430	if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)	430	if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
431	continue;	431	continue;
432		432
433	printf ("Control %s\n", queryctrl.name);	433	printf ("Control %s\n", queryctrl.name);
434		434
435	if (queryctrl.type == V4L2_CTRL_TYPE_MENU)	435	if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
436	enumerate_menu ();	436	enumerate_menu ();
437	} else {	437	} else {
438	if (errno == EINVAL)	438	if (errno == EINVAL)
439	break;	439	break;
440		440
441	perror ("VIDIOC_QUERYCTRL");	441	perror ("VIDIOC_QUERYCTRL");
442	exit (EXIT_FAILURE);	442	exit (EXIT_FAILURE);
443	}	443	}
444	}	444	}
445	</programlisting>	445	</programlisting>
446	</example>	446	</example>
447		447
448	<example>	448	<example>
449	<title>Changing controls</title>	449	<title>Changing controls</title>
450		450
451	<programlisting>	451	<programlisting>
452	&v4l2-queryctrl; queryctrl;	452	&v4l2-queryctrl; queryctrl;
453	&v4l2-control; control;	453	&v4l2-control; control;
454		454
455	memset (&queryctrl, 0, sizeof (queryctrl));	455	memset (&queryctrl, 0, sizeof (queryctrl));
456	queryctrl.id = V4L2_CID_BRIGHTNESS;	456	queryctrl.id = V4L2_CID_BRIGHTNESS;
457		457
458	if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) {	458	if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &queryctrl)) {
459	if (errno != EINVAL) {	459	if (errno != EINVAL) {
460	perror ("VIDIOC_QUERYCTRL");	460	perror ("VIDIOC_QUERYCTRL");
461	exit (EXIT_FAILURE);	461	exit (EXIT_FAILURE);
462	} else {	462	} else {
463	printf ("V4L2_CID_BRIGHTNESS is not supported\n");	463	printf ("V4L2_CID_BRIGHTNESS is not supported\n");
464	}	464	}
465	} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {	465	} else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
466	printf ("V4L2_CID_BRIGHTNESS is not supported\n");	466	printf ("V4L2_CID_BRIGHTNESS is not supported\n");
467	} else {	467	} else {
468	memset (&control, 0, sizeof (control));	468	memset (&control, 0, sizeof (control));
469	control.id = V4L2_CID_BRIGHTNESS;	469	control.id = V4L2_CID_BRIGHTNESS;
470	control.value = queryctrl.default_value;	470	control.value = queryctrl.default_value;
471		471
472	if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)) {	472	if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)) {
473	perror ("VIDIOC_S_CTRL");	473	perror ("VIDIOC_S_CTRL");
474	exit (EXIT_FAILURE);	474	exit (EXIT_FAILURE);
475	}	475	}
476	}	476	}
477		477
478	memset (&control, 0, sizeof (control));	478	memset (&control, 0, sizeof (control));
479	control.id = V4L2_CID_CONTRAST;	479	control.id = V4L2_CID_CONTRAST;
480		480
481	if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &control)) {	481	if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &control)) {
482	control.value += 1;	482	control.value += 1;
483		483
484	/* The driver may clamp the value or return ERANGE, ignored here */	484	/* The driver may clamp the value or return ERANGE, ignored here */
485		485
486	if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)	486	if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &control)
487	&& errno != ERANGE) {	487	&& errno != ERANGE) {
488	perror ("VIDIOC_S_CTRL");	488	perror ("VIDIOC_S_CTRL");
489	exit (EXIT_FAILURE);	489	exit (EXIT_FAILURE);
490	}	490	}
491	/* Ignore if V4L2_CID_CONTRAST is unsupported */	491	/* Ignore if V4L2_CID_CONTRAST is unsupported */
492	} else if (errno != EINVAL) {	492	} else if (errno != EINVAL) {
493	perror ("VIDIOC_G_CTRL");	493	perror ("VIDIOC_G_CTRL");
494	exit (EXIT_FAILURE);	494	exit (EXIT_FAILURE);
495	}	495	}
496		496
497	control.id = V4L2_CID_AUDIO_MUTE;	497	control.id = V4L2_CID_AUDIO_MUTE;
498	control.value = TRUE; /* silence */	498	control.value = TRUE; /* silence */
499		499
500	/* Errors ignored */	500	/* Errors ignored */
501	ioctl (fd, VIDIOC_S_CTRL, &control);	501	ioctl (fd, VIDIOC_S_CTRL, &control);
502	</programlisting>	502	</programlisting>
503	</example>	503	</example>
504	</section>	504	</section>
505		505
506	<section id="extended-controls">	506	<section id="extended-controls">
507	<title>Extended Controls</title>	507	<title>Extended Controls</title>
508		508
509	<section>	509	<section>
510	<title>Introduction</title>	510	<title>Introduction</title>
511		511
512	<para>The control mechanism as originally designed was meant	512	<para>The control mechanism as originally designed was meant
513	to be used for user settings (brightness, saturation, etc). However,	513	to be used for user settings (brightness, saturation, etc). However,
514	it turned out to be a very useful model for implementing more	514	it turned out to be a very useful model for implementing more
515	complicated driver APIs where each driver implements only a subset of	515	complicated driver APIs where each driver implements only a subset of
516	a larger API.</para>	516	a larger API.</para>
517		517
518	<para>The MPEG encoding API was the driving force behind	518	<para>The MPEG encoding API was the driving force behind
519	designing and implementing this extended control mechanism: the MPEG	519	designing and implementing this extended control mechanism: the MPEG
520	standard is quite large and the currently supported hardware MPEG	520	standard is quite large and the currently supported hardware MPEG
521	encoders each only implement a subset of this standard. Further more,	521	encoders each only implement a subset of this standard. Further more,
522	many parameters relating to how the video is encoded into an MPEG	522	many parameters relating to how the video is encoded into an MPEG
523	stream are specific to the MPEG encoding chip since the MPEG standard	523	stream are specific to the MPEG encoding chip since the MPEG standard
524	only defines the format of the resulting MPEG stream, not how the	524	only defines the format of the resulting MPEG stream, not how the
525	video is actually encoded into that format.</para>	525	video is actually encoded into that format.</para>
526		526
527	<para>Unfortunately, the original control API lacked some	527	<para>Unfortunately, the original control API lacked some
528	features needed for these new uses and so it was extended into the	528	features needed for these new uses and so it was extended into the
529	(not terribly originally named) extended control API.</para>	529	(not terribly originally named) extended control API.</para>
530		530
531	<para>Even though the MPEG encoding API was the first effort	531	<para>Even though the MPEG encoding API was the first effort
532	to use the Extended Control API, nowadays there are also other classes	532	to use the Extended Control API, nowadays there are also other classes
533	of Extended Controls, such as Camera Controls and FM Transmitter Controls.	533	of Extended Controls, such as Camera Controls and FM Transmitter Controls.
534	The Extended Controls API as well as all Extended Controls classes are	534	The Extended Controls API as well as all Extended Controls classes are
535	described in the following text.</para>	535	described in the following text.</para>
536	</section>	536	</section>
537		537
538	<section>	538	<section>
539	<title>The Extended Control API</title>	539	<title>The Extended Control API</title>
540		540
541	<para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;,	541	<para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;,
542	&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on	542	&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on
543	arrays of controls (as opposed to the &VIDIOC-G-CTRL; and	543	arrays of controls (as opposed to the &VIDIOC-G-CTRL; and
544	&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed	544	&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed
545	since it is often required to atomically change several controls at	545	since it is often required to atomically change several controls at
546	once.</para>	546	once.</para>
547		547
548	<para>Each of the new ioctls expects a pointer to a	548	<para>Each of the new ioctls expects a pointer to a
549	&v4l2-ext-controls;. This structure contains a pointer to the control	549	&v4l2-ext-controls;. This structure contains a pointer to the control
550	array, a count of the number of controls in that array and a control	550	array, a count of the number of controls in that array and a control
551	class. Control classes are used to group similar controls into a	551	class. Control classes are used to group similar controls into a
552	single class. For example, control class	552	single class. For example, control class
553	<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls	553	<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls
554	(&ie; all controls that can also be set using the old	554	(&ie; all controls that can also be set using the old
555	<constant>VIDIOC_S_CTRL</constant> ioctl). Control class	555	<constant>VIDIOC_S_CTRL</constant> ioctl). Control class
556	<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls	556	<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls
557	relating to MPEG encoding, etc.</para>	557	relating to MPEG encoding, etc.</para>
558		558
559	<para>All controls in the control array must belong to the	559	<para>All controls in the control array must belong to the
560	specified control class. An error is returned if this is not the	560	specified control class. An error is returned if this is not the
561	case.</para>	561	case.</para>
562		562
563	<para>It is also possible to use an empty control array (count	563	<para>It is also possible to use an empty control array (count
564	== 0) to check whether the specified control class is	564	== 0) to check whether the specified control class is
565	supported.</para>	565	supported.</para>
566		566
567	<para>The control array is a &v4l2-ext-control; array. The	567	<para>The control array is a &v4l2-ext-control; array. The
568	<structname>v4l2_ext_control</structname> structure is very similar to	568	<structname>v4l2_ext_control</structname> structure is very similar to
569	&v4l2-control;, except for the fact that it also allows for 64-bit	569	&v4l2-control;, except for the fact that it also allows for 64-bit
570	values and pointers to be passed.</para>	570	values and pointers to be passed.</para>
571		571
572	<para>It is important to realize that due to the flexibility of	572	<para>It is important to realize that due to the flexibility of
573	controls it is necessary to check whether the control you want to set	573	controls it is necessary to check whether the control you want to set
574	actually is supported in the driver and what the valid range of values	574	actually is supported in the driver and what the valid range of values
575	is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to	575	is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to
576	check this. Also note that it is possible that some of the menu	576	check this. Also note that it is possible that some of the menu
577	indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>	577	indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>
578	may not be supported (<constant>VIDIOC_QUERYMENU</constant> will	578	may not be supported (<constant>VIDIOC_QUERYMENU</constant> will
579	return an error). A good example is the list of supported MPEG audio	579	return an error). A good example is the list of supported MPEG audio
580	bitrates. Some drivers only support one or two bitrates, others	580	bitrates. Some drivers only support one or two bitrates, others
581	support a wider range.</para>	581	support a wider range.</para>
582		582
583	<para>	583	<para>
584	All controls use machine endianness.	584	All controls use machine endianness.
585	</para>	585	</para>
586	</section>	586	</section>
587		587
588	<section>	588	<section>
589	<title>Enumerating Extended Controls</title>	589	<title>Enumerating Extended Controls</title>
590		590
591	<para>The recommended way to enumerate over the extended	591	<para>The recommended way to enumerate over the extended
592	controls is by using &VIDIOC-QUERYCTRL; in combination with the	592	controls is by using &VIDIOC-QUERYCTRL; in combination with the
593	<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para>	593	<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para>
594		594
595	<informalexample>	595	<informalexample>
596	<programlisting>	596	<programlisting>
597	&v4l2-queryctrl; qctrl;	597	&v4l2-queryctrl; qctrl;
598		598
599	qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;	599	qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
600	while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) {	600	while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) {
601	/* ... */	601	/* ... */
602	qctrl.id \|= V4L2_CTRL_FLAG_NEXT_CTRL;	602	qctrl.id \|= V4L2_CTRL_FLAG_NEXT_CTRL;
603	}	603	}
604	</programlisting>	604	</programlisting>
605	</informalexample>	605	</informalexample>
606		606
607	<para>The initial control ID is set to 0 ORed with the	607	<para>The initial control ID is set to 0 ORed with the
608	<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The	608	<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The
609	<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first	609	<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first
610	control with a higher ID than the specified one. When no such controls	610	control with a higher ID than the specified one. When no such controls
611	are found an error is returned.</para>	611	are found an error is returned.</para>
612		612
613	<para>If you want to get all controls within a specific control	613	<para>If you want to get all controls within a specific control
614	class, then you can set the initial	614	class, then you can set the initial
615	<structfield>qctrl.id</structfield> value to the control class and add	615	<structfield>qctrl.id</structfield> value to the control class and add
616	an extra check to break out of the loop when a control of another	616	an extra check to break out of the loop when a control of another
617	control class is found:</para>	617	control class is found:</para>
618		618
619	<informalexample>	619	<informalexample>
620	<programlisting>	620	<programlisting>
621	qctrl.id = V4L2_CTRL_CLASS_MPEG \| V4L2_CTRL_FLAG_NEXT_CTRL;	621	qctrl.id = V4L2_CTRL_CLASS_MPEG \| V4L2_CTRL_FLAG_NEXT_CTRL;
622	while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) {	622	while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &qctrl)) {
623	if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)	623	if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
624	break;	624	break;
625	/* ... */	625	/* ... */
626	qctrl.id \|= V4L2_CTRL_FLAG_NEXT_CTRL;	626	qctrl.id \|= V4L2_CTRL_FLAG_NEXT_CTRL;
627	}	627	}
628	</programlisting>	628	</programlisting>
629	</informalexample>	629	</informalexample>
630		630
631	<para>The 32-bit <structfield>qctrl.id</structfield> value is	631	<para>The 32-bit <structfield>qctrl.id</structfield> value is
632	subdivided into three bit ranges: the top 4 bits are reserved for	632	subdivided into three bit ranges: the top 4 bits are reserved for
633	flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not	633	flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not
634	actually part of the ID. The remaining 28 bits form the control ID, of	634	actually part of the ID. The remaining 28 bits form the control ID, of
635	which the most significant 12 bits define the control class and the	635	which the most significant 12 bits define the control class and the
636	least significant 16 bits identify the control within the control	636	least significant 16 bits identify the control within the control
637	class. It is guaranteed that these last 16 bits are always non-zero	637	class. It is guaranteed that these last 16 bits are always non-zero
638	for controls. The range of 0x1000 and up are reserved for	638	for controls. The range of 0x1000 and up are reserved for
639	driver-specific controls. The macro	639	driver-specific controls. The macro
640	<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class	640	<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class
641	ID based on a control ID.</para>	641	ID based on a control ID.</para>
642		642
643	<para>If the driver does not support extended controls, then	643	<para>If the driver does not support extended controls, then
644	<constant>VIDIOC_QUERYCTRL</constant> will fail when used in	644	<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
645	combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In	645	combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
646	that case the old method of enumerating control should be used (see	646	that case the old method of enumerating control should be used (see
647	1.8). But if it is supported, then it is guaranteed to enumerate over	647	1.8). But if it is supported, then it is guaranteed to enumerate over
648	all controls, including driver-private controls.</para>	648	all controls, including driver-private controls.</para>
649	</section>	649	</section>
650		650
651	<section>	651	<section>
652	<title>Creating Control Panels</title>	652	<title>Creating Control Panels</title>
653		653
654	<para>It is possible to create control panels for a graphical	654	<para>It is possible to create control panels for a graphical
655	user interface where the user can select the various controls.	655	user interface where the user can select the various controls.
656	Basically you will have to iterate over all controls using the method	656	Basically you will have to iterate over all controls using the method
657	described above. Each control class starts with a control of type	657	described above. Each control class starts with a control of type
658	<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>.	658	<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>.
659	<constant>VIDIOC_QUERYCTRL</constant> will return the name of this	659	<constant>VIDIOC_QUERYCTRL</constant> will return the name of this
660	control class which can be used as the title of a tab page within a	660	control class which can be used as the title of a tab page within a
661	control panel.</para>	661	control panel.</para>
662		662
663	<para>The flags field of &v4l2-queryctrl; also contains hints on	663	<para>The flags field of &v4l2-queryctrl; also contains hints on
664	the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation	664	the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation
665	for more details.</para>	665	for more details.</para>
666	</section>	666	</section>
667		667
668	<section id="mpeg-controls">	668	<section id="mpeg-controls">
669	<title>MPEG Control Reference</title>	669	<title>MPEG Control Reference</title>
670		670
671	<para>Below all controls within the MPEG control class are	671	<para>Below all controls within the MPEG control class are
672	described. First the generic controls, then controls specific for	672	described. First the generic controls, then controls specific for
673	certain hardware.</para>	673	certain hardware.</para>
674		674
675	<section>	675	<section>
676	<title>Generic MPEG Controls</title>	676	<title>Generic MPEG Controls</title>
677		677
678	<table pgwide="1" frame="none" id="mpeg-control-id">	678	<table pgwide="1" frame="none" id="mpeg-control-id">
679	<title>MPEG Control IDs</title>	679	<title>MPEG Control IDs</title>
680	<tgroup cols="4">	680	<tgroup cols="4">
681	<colspec colname="c1" colwidth="1*" />	681	<colspec colname="c1" colwidth="1*" />
682	<colspec colname="c2" colwidth="6*" />	682	<colspec colname="c2" colwidth="6*" />
683	<colspec colname="c3" colwidth="2*" />	683	<colspec colname="c3" colwidth="2*" />
684	<colspec colname="c4" colwidth="6*" />	684	<colspec colname="c4" colwidth="6*" />
685	<spanspec namest="c1" nameend="c2" spanname="id" />	685	<spanspec namest="c1" nameend="c2" spanname="id" />
686	<spanspec namest="c2" nameend="c4" spanname="descr" />	686	<spanspec namest="c2" nameend="c4" spanname="descr" />
687	<thead>	687	<thead>
688	<row>	688	<row>
689	<entry spanname="id" align="left">ID</entry>	689	<entry spanname="id" align="left">ID</entry>
690	<entry align="left">Type</entry>	690	<entry align="left">Type</entry>
691	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>	691	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
692	</row>	692	</row>
693	</thead>	693	</thead>
694	<tbody valign="top">	694	<tbody valign="top">
695	<row><entry></entry></row>	695	<row><entry></entry></row>
696	<row>	696	<row>
697	<entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant> </entry>	697	<entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant> </entry>
698	<entry>class</entry>	698	<entry>class</entry>
699	</row><row><entry spanname="descr">The MPEG class	699	</row><row><entry spanname="descr">The MPEG class
700	descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a	700	descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
701	description of this control class. This description can be used as the	701	description of this control class. This description can be used as the
702	caption of a Tab page in a GUI, for example.</entry>	702	caption of a Tab page in a GUI, for example.</entry>
703	</row>	703	</row>
704	<row><entry></entry></row>	704	<row><entry></entry></row>
705	<row id="v4l2-mpeg-stream-type">	705	<row id="v4l2-mpeg-stream-type">
706	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant> </entry>	706	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant> </entry>
707	<entry>enum v4l2_mpeg_stream_type</entry>	707	<entry>enum v4l2_mpeg_stream_type</entry>
708	</row><row><entry spanname="descr">The MPEG-1, -2 or -4	708	</row><row><entry spanname="descr">The MPEG-1, -2 or -4
709	output stream type. One cannot assume anything here. Each hardware	709	output stream type. One cannot assume anything here. Each hardware
710	MPEG encoder tends to support different subsets of the available MPEG	710	MPEG encoder tends to support different subsets of the available MPEG
711	stream types. This control is specific to multiplexed MPEG streams.	711	stream types. This control is specific to multiplexed MPEG streams.
712	The currently defined stream types are:</entry>	712	The currently defined stream types are:</entry>
713	</row>	713	</row>
714	<row>	714	<row>
715	<entrytbl spanname="descr" cols="2">	715	<entrytbl spanname="descr" cols="2">
716	<tbody valign="top">	716	<tbody valign="top">
717	<row>	717	<row>
718	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant> </entry>	718	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant> </entry>
719	<entry>MPEG-2 program stream</entry>	719	<entry>MPEG-2 program stream</entry>
720	</row>	720	</row>
721	<row>	721	<row>
722	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant> </entry>	722	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant> </entry>
723	<entry>MPEG-2 transport stream</entry>	723	<entry>MPEG-2 transport stream</entry>
724	</row>	724	</row>
725	<row>	725	<row>
726	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant> </entry>	726	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant> </entry>
727	<entry>MPEG-1 system stream</entry>	727	<entry>MPEG-1 system stream</entry>
728	</row>	728	</row>
729	<row>	729	<row>
730	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant> </entry>	730	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant> </entry>
731	<entry>MPEG-2 DVD-compatible stream</entry>	731	<entry>MPEG-2 DVD-compatible stream</entry>
732	</row>	732	</row>
733	<row>	733	<row>
734	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant> </entry>	734	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant> </entry>
735	<entry>MPEG-1 VCD-compatible stream</entry>	735	<entry>MPEG-1 VCD-compatible stream</entry>
736	</row>	736	</row>
737	<row>	737	<row>
738	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant> </entry>	738	<entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant> </entry>
739	<entry>MPEG-2 SVCD-compatible stream</entry>	739	<entry>MPEG-2 SVCD-compatible stream</entry>
740	</row>	740	</row>
741	</tbody>	741	</tbody>
742	</entrytbl>	742	</entrytbl>
743	</row>	743	</row>
744	<row><entry></entry></row>	744	<row><entry></entry></row>
745	<row>	745	<row>
746	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant> </entry>	746	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant> </entry>
747	<entry>integer</entry>	747	<entry>integer</entry>
748	</row><row><entry spanname="descr">Program Map Table	748	</row><row><entry spanname="descr">Program Map Table
749	Packet ID for the MPEG transport stream (default 16)</entry>	749	Packet ID for the MPEG transport stream (default 16)</entry>
750	</row>	750	</row>
751	<row><entry></entry></row>	751	<row><entry></entry></row>
752	<row>	752	<row>
753	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant> </entry>	753	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant> </entry>
754	<entry>integer</entry>	754	<entry>integer</entry>
755	</row><row><entry spanname="descr">Audio Packet ID for	755	</row><row><entry spanname="descr">Audio Packet ID for
756	the MPEG transport stream (default 256)</entry>	756	the MPEG transport stream (default 256)</entry>
757	</row>	757	</row>
758	<row><entry></entry></row>	758	<row><entry></entry></row>
759	<row>	759	<row>
760	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant> </entry>	760	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant> </entry>
761	<entry>integer</entry>	761	<entry>integer</entry>
762	</row><row><entry spanname="descr">Video Packet ID for	762	</row><row><entry spanname="descr">Video Packet ID for
763	the MPEG transport stream (default 260)</entry>	763	the MPEG transport stream (default 260)</entry>
764	</row>	764	</row>
765	<row><entry></entry></row>	765	<row><entry></entry></row>
766	<row>	766	<row>
767	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant> </entry>	767	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant> </entry>
768	<entry>integer</entry>	768	<entry>integer</entry>
769	</row><row><entry spanname="descr">Packet ID for the	769	</row><row><entry spanname="descr">Packet ID for the
770	MPEG transport stream carrying PCR fields (default 259)</entry>	770	MPEG transport stream carrying PCR fields (default 259)</entry>
771	</row>	771	</row>
772	<row><entry></entry></row>	772	<row><entry></entry></row>
773	<row>	773	<row>
774	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant> </entry>	774	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant> </entry>
775	<entry>integer</entry>	775	<entry>integer</entry>
776	</row><row><entry spanname="descr">Audio ID for MPEG	776	</row><row><entry spanname="descr">Audio ID for MPEG
777	PES</entry>	777	PES</entry>
778	</row>	778	</row>
779	<row><entry></entry></row>	779	<row><entry></entry></row>
780	<row>	780	<row>
781	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant> </entry>	781	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant> </entry>
782	<entry>integer</entry>	782	<entry>integer</entry>
783	</row><row><entry spanname="descr">Video ID for MPEG	783	</row><row><entry spanname="descr">Video ID for MPEG
784	PES</entry>	784	PES</entry>
785	</row>	785	</row>
786	<row><entry></entry></row>	786	<row><entry></entry></row>
787	<row id="v4l2-mpeg-stream-vbi-fmt">	787	<row id="v4l2-mpeg-stream-vbi-fmt">
788	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant> </entry>	788	<entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant> </entry>
789	<entry>enum v4l2_mpeg_stream_vbi_fmt</entry>	789	<entry>enum v4l2_mpeg_stream_vbi_fmt</entry>
790	</row><row><entry spanname="descr">Some cards can embed	790	</row><row><entry spanname="descr">Some cards can embed
791	VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This	791	VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This
792	control selects whether VBI data should be embedded, and if so, what	792	control selects whether VBI data should be embedded, and if so, what
793	embedding method should be used. The list of possible VBI formats	793	embedding method should be used. The list of possible VBI formats
794	depends on the driver. The currently defined VBI format types	794	depends on the driver. The currently defined VBI format types
795	are:</entry>	795	are:</entry>
796	</row>	796	</row>
797	<row>	797	<row>
798	<entrytbl spanname="descr" cols="2">	798	<entrytbl spanname="descr" cols="2">
799	<tbody valign="top">	799	<tbody valign="top">
800	<row>	800	<row>
801	<entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant> </entry>	801	<entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant> </entry>
802	<entry>No VBI in the MPEG stream</entry>	802	<entry>No VBI in the MPEG stream</entry>
803	</row>	803	</row>
804	<row>	804	<row>
805	<entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant> </entry>	805	<entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant> </entry>
806	<entry>VBI in private packets, IVTV format (documented	806	<entry>VBI in private packets, IVTV format (documented
807	in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry>	807	in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry>
808	</row>	808	</row>
809	</tbody>	809	</tbody>
810	</entrytbl>	810	</entrytbl>
811	</row>	811	</row>
812	<row><entry></entry></row>	812	<row><entry></entry></row>
813	<row id="v4l2-mpeg-audio-sampling-freq">	813	<row id="v4l2-mpeg-audio-sampling-freq">
814	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant> </entry>	814	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant> </entry>
815	<entry>enum v4l2_mpeg_audio_sampling_freq</entry>	815	<entry>enum v4l2_mpeg_audio_sampling_freq</entry>
816	</row><row><entry spanname="descr">MPEG Audio sampling	816	</row><row><entry spanname="descr">MPEG Audio sampling
817	frequency. Possible values are:</entry>	817	frequency. Possible values are:</entry>
818	</row>	818	</row>
819	<row>	819	<row>
820	<entrytbl spanname="descr" cols="2">	820	<entrytbl spanname="descr" cols="2">
821	<tbody valign="top">	821	<tbody valign="top">
822	<row>	822	<row>
823	<entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant> </entry>	823	<entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant> </entry>
824	<entry>44.1 kHz</entry>	824	<entry>44.1 kHz</entry>
825	</row>	825	</row>
826	<row>	826	<row>
827	<entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant> </entry>	827	<entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant> </entry>
828	<entry>48 kHz</entry>	828	<entry>48 kHz</entry>
829	</row>	829	</row>
830	<row>	830	<row>
831	<entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant> </entry>	831	<entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant> </entry>
832	<entry>32 kHz</entry>	832	<entry>32 kHz</entry>
833	</row>	833	</row>
834	</tbody>	834	</tbody>
835	</entrytbl>	835	</entrytbl>
836	</row>	836	</row>
837	<row><entry></entry></row>	837	<row><entry></entry></row>
838	<row id="v4l2-mpeg-audio-encoding">	838	<row id="v4l2-mpeg-audio-encoding">
839	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant> </entry>	839	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant> </entry>
840	<entry>enum v4l2_mpeg_audio_encoding</entry>	840	<entry>enum v4l2_mpeg_audio_encoding</entry>
841	</row><row><entry spanname="descr">MPEG Audio encoding.	841	</row><row><entry spanname="descr">MPEG Audio encoding.
842	This control is specific to multiplexed MPEG streams.	842	This control is specific to multiplexed MPEG streams.
843	Possible values are:</entry>	843	Possible values are:</entry>
844	</row>	844	</row>
845	<row>	845	<row>
846	<entrytbl spanname="descr" cols="2">	846	<entrytbl spanname="descr" cols="2">
847	<tbody valign="top">	847	<tbody valign="top">
848	<row>	848	<row>
849	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant> </entry>	849	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant> </entry>
850	<entry>MPEG-1/2 Layer I encoding</entry>	850	<entry>MPEG-1/2 Layer I encoding</entry>
851	</row>	851	</row>
852	<row>	852	<row>
853	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant> </entry>	853	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant> </entry>
854	<entry>MPEG-1/2 Layer II encoding</entry>	854	<entry>MPEG-1/2 Layer II encoding</entry>
855	</row>	855	</row>
856	<row>	856	<row>
857	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant> </entry>	857	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant> </entry>
858	<entry>MPEG-1/2 Layer III encoding</entry>	858	<entry>MPEG-1/2 Layer III encoding</entry>
859	</row>	859	</row>
860	<row>	860	<row>
861	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> </entry>	861	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> </entry>
862	<entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>	862	<entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>
863	</row>	863	</row>
864	<row>	864	<row>
865	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> </entry>	865	<entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> </entry>
866	<entry>AC-3 aka ATSC A/52 encoding</entry>	866	<entry>AC-3 aka ATSC A/52 encoding</entry>
867	</row>	867	</row>
868	</tbody>	868	</tbody>
869	</entrytbl>	869	</entrytbl>
870	</row>	870	</row>
871	<row><entry></entry></row>	871	<row><entry></entry></row>
872	<row id="v4l2-mpeg-audio-l1-bitrate">	872	<row id="v4l2-mpeg-audio-l1-bitrate">
873	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant> </entry>	873	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant> </entry>
874	<entry>enum v4l2_mpeg_audio_l1_bitrate</entry>	874	<entry>enum v4l2_mpeg_audio_l1_bitrate</entry>
875	</row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.	875	</row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.
876	Possible values are:</entry>	876	Possible values are:</entry>
877	</row>	877	</row>
878	<row>	878	<row>
879	<entrytbl spanname="descr" cols="2">	879	<entrytbl spanname="descr" cols="2">
880	<tbody valign="top">	880	<tbody valign="top">
881	<row>	881	<row>
882	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant> </entry>	882	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant> </entry>
883	<entry>32 kbit/s</entry></row>	883	<entry>32 kbit/s</entry></row>
884	<row>	884	<row>
885	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant> </entry>	885	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant> </entry>
886	<entry>64 kbit/s</entry>	886	<entry>64 kbit/s</entry>
887	</row>	887	</row>
888	<row>	888	<row>
889	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant> </entry>	889	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant> </entry>
890	<entry>96 kbit/s</entry>	890	<entry>96 kbit/s</entry>
891	</row>	891	</row>
892	<row>	892	<row>
893	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant> </entry>	893	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant> </entry>
894	<entry>128 kbit/s</entry>	894	<entry>128 kbit/s</entry>
895	</row>	895	</row>
896	<row>	896	<row>
897	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant> </entry>	897	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant> </entry>
898	<entry>160 kbit/s</entry>	898	<entry>160 kbit/s</entry>
899	</row>	899	</row>
900	<row>	900	<row>
901	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant> </entry>	901	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant> </entry>
902	<entry>192 kbit/s</entry>	902	<entry>192 kbit/s</entry>
903	</row>	903	</row>
904	<row>	904	<row>
905	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant> </entry>	905	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant> </entry>
906	<entry>224 kbit/s</entry>	906	<entry>224 kbit/s</entry>
907	</row>	907	</row>
908	<row>	908	<row>
909	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant> </entry>	909	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant> </entry>
910	<entry>256 kbit/s</entry>	910	<entry>256 kbit/s</entry>
911	</row>	911	</row>
912	<row>	912	<row>
913	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant> </entry>	913	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant> </entry>
914	<entry>288 kbit/s</entry>	914	<entry>288 kbit/s</entry>
915	</row>	915	</row>
916	<row>	916	<row>
917	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant> </entry>	917	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant> </entry>
918	<entry>320 kbit/s</entry>	918	<entry>320 kbit/s</entry>
919	</row>	919	</row>
920	<row>	920	<row>
921	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant> </entry>	921	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant> </entry>
922	<entry>352 kbit/s</entry>	922	<entry>352 kbit/s</entry>
923	</row>	923	</row>
924	<row>	924	<row>
925	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant> </entry>	925	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant> </entry>
926	<entry>384 kbit/s</entry>	926	<entry>384 kbit/s</entry>
927	</row>	927	</row>
928	<row>	928	<row>
929	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant> </entry>	929	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant> </entry>
930	<entry>416 kbit/s</entry>	930	<entry>416 kbit/s</entry>
931	</row>	931	</row>
932	<row>	932	<row>
933	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant> </entry>	933	<entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant> </entry>
934	<entry>448 kbit/s</entry>	934	<entry>448 kbit/s</entry>
935	</row>	935	</row>
936	</tbody>	936	</tbody>
937	</entrytbl>	937	</entrytbl>
938	</row>	938	</row>
939	<row><entry></entry></row>	939	<row><entry></entry></row>
940	<row id="v4l2-mpeg-audio-l2-bitrate">	940	<row id="v4l2-mpeg-audio-l2-bitrate">
941	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant> </entry>	941	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant> </entry>
942	<entry>enum v4l2_mpeg_audio_l2_bitrate</entry>	942	<entry>enum v4l2_mpeg_audio_l2_bitrate</entry>
943	</row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.	943	</row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.
944	Possible values are:</entry>	944	Possible values are:</entry>
945	</row>	945	</row>
946	<row>	946	<row>
947	<entrytbl spanname="descr" cols="2">	947	<entrytbl spanname="descr" cols="2">
948	<tbody valign="top">	948	<tbody valign="top">
949	<row>	949	<row>
950	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant> </entry>	950	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant> </entry>
951	<entry>32 kbit/s</entry>	951	<entry>32 kbit/s</entry>
952	</row>	952	</row>
953	<row>	953	<row>
954	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant> </entry>	954	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant> </entry>
955	<entry>48 kbit/s</entry>	955	<entry>48 kbit/s</entry>
956	</row>	956	</row>
957	<row>	957	<row>
958	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant> </entry>	958	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant> </entry>
959	<entry>56 kbit/s</entry>	959	<entry>56 kbit/s</entry>
960	</row>	960	</row>
961	<row>	961	<row>
962	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant> </entry>	962	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant> </entry>
963	<entry>64 kbit/s</entry>	963	<entry>64 kbit/s</entry>
964	</row>	964	</row>
965	<row>	965	<row>
966	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant> </entry>	966	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant> </entry>
967	<entry>80 kbit/s</entry>	967	<entry>80 kbit/s</entry>
968	</row>	968	</row>
969	<row>	969	<row>
970	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant> </entry>	970	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant> </entry>
971	<entry>96 kbit/s</entry>	971	<entry>96 kbit/s</entry>
972	</row>	972	</row>
973	<row>	973	<row>
974	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant> </entry>	974	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant> </entry>
975	<entry>112 kbit/s</entry>	975	<entry>112 kbit/s</entry>
976	</row>	976	</row>
977	<row>	977	<row>
978	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant> </entry>	978	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant> </entry>
979	<entry>128 kbit/s</entry>	979	<entry>128 kbit/s</entry>
980	</row>	980	</row>
981	<row>	981	<row>
982	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant> </entry>	982	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant> </entry>
983	<entry>160 kbit/s</entry>	983	<entry>160 kbit/s</entry>
984	</row>	984	</row>
985	<row>	985	<row>
986	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant> </entry>	986	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant> </entry>
987	<entry>192 kbit/s</entry>	987	<entry>192 kbit/s</entry>
988	</row>	988	</row>
989	<row>	989	<row>
990	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant> </entry>	990	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant> </entry>
991	<entry>224 kbit/s</entry>	991	<entry>224 kbit/s</entry>
992	</row>	992	</row>
993	<row>	993	<row>
994	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant> </entry>	994	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant> </entry>
995	<entry>256 kbit/s</entry>	995	<entry>256 kbit/s</entry>
996	</row>	996	</row>
997	<row>	997	<row>
998	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant> </entry>	998	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant> </entry>
999	<entry>320 kbit/s</entry>	999	<entry>320 kbit/s</entry>
1000	</row>	1000	</row>
1001	<row>	1001	<row>
1002	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant> </entry>	1002	<entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant> </entry>
1003	<entry>384 kbit/s</entry>	1003	<entry>384 kbit/s</entry>
1004	</row>	1004	</row>
1005	</tbody>	1005	</tbody>
1006	</entrytbl>	1006	</entrytbl>
1007	</row>	1007	</row>
1008	<row><entry></entry></row>	1008	<row><entry></entry></row>
1009	<row id="v4l2-mpeg-audio-l3-bitrate">	1009	<row id="v4l2-mpeg-audio-l3-bitrate">
1010	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant> </entry>	1010	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant> </entry>
1011	<entry>enum v4l2_mpeg_audio_l3_bitrate</entry>	1011	<entry>enum v4l2_mpeg_audio_l3_bitrate</entry>
1012	</row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.	1012	</row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.
1013	Possible values are:</entry>	1013	Possible values are:</entry>
1014	</row>	1014	</row>
1015	<row>	1015	<row>
1016	<entrytbl spanname="descr" cols="2">	1016	<entrytbl spanname="descr" cols="2">
1017	<tbody valign="top">	1017	<tbody valign="top">
1018	<row>	1018	<row>
1019	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant> </entry>	1019	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant> </entry>
1020	<entry>32 kbit/s</entry>	1020	<entry>32 kbit/s</entry>
1021	</row>	1021	</row>
1022	<row>	1022	<row>
1023	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant> </entry>	1023	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant> </entry>
1024	<entry>40 kbit/s</entry>	1024	<entry>40 kbit/s</entry>
1025	</row>	1025	</row>
1026	<row>	1026	<row>
1027	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant> </entry>	1027	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant> </entry>
1028	<entry>48 kbit/s</entry>	1028	<entry>48 kbit/s</entry>
1029	</row>	1029	</row>
1030	<row>	1030	<row>
1031	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant> </entry>	1031	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant> </entry>
1032	<entry>56 kbit/s</entry>	1032	<entry>56 kbit/s</entry>
1033	</row>	1033	</row>
1034	<row>	1034	<row>
1035	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant> </entry>	1035	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant> </entry>
1036	<entry>64 kbit/s</entry>	1036	<entry>64 kbit/s</entry>
1037	</row>	1037	</row>
1038	<row>	1038	<row>
1039	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant> </entry>	1039	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant> </entry>
1040	<entry>80 kbit/s</entry>	1040	<entry>80 kbit/s</entry>
1041	</row>	1041	</row>
1042	<row>	1042	<row>
1043	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant> </entry>	1043	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant> </entry>
1044	<entry>96 kbit/s</entry>	1044	<entry>96 kbit/s</entry>
1045	</row>	1045	</row>
1046	<row>	1046	<row>
1047	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant> </entry>	1047	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant> </entry>
1048	<entry>112 kbit/s</entry>	1048	<entry>112 kbit/s</entry>
1049	</row>	1049	</row>
1050	<row>	1050	<row>
1051	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant> </entry>	1051	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant> </entry>
1052	<entry>128 kbit/s</entry>	1052	<entry>128 kbit/s</entry>
1053	</row>	1053	</row>
1054	<row>	1054	<row>
1055	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant> </entry>	1055	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant> </entry>
1056	<entry>160 kbit/s</entry>	1056	<entry>160 kbit/s</entry>
1057	</row>	1057	</row>
1058	<row>	1058	<row>
1059	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant> </entry>	1059	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant> </entry>
1060	<entry>192 kbit/s</entry>	1060	<entry>192 kbit/s</entry>
1061	</row>	1061	</row>
1062	<row>	1062	<row>
1063	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant> </entry>	1063	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant> </entry>
1064	<entry>224 kbit/s</entry>	1064	<entry>224 kbit/s</entry>
1065	</row>	1065	</row>
1066	<row>	1066	<row>
1067	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant> </entry>	1067	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant> </entry>
1068	<entry>256 kbit/s</entry>	1068	<entry>256 kbit/s</entry>
1069	</row>	1069	</row>
1070	<row>	1070	<row>
1071	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant> </entry>	1071	<entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant> </entry>
1072	<entry>320 kbit/s</entry>	1072	<entry>320 kbit/s</entry>
1073	</row>	1073	</row>
1074	</tbody>	1074	</tbody>
1075	</entrytbl>	1075	</entrytbl>
1076	</row>	1076	</row>
1077	<row><entry></entry></row>	1077	<row><entry></entry></row>
1078	<row>	1078	<row>
1079	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant> </entry>	1079	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant> </entry>
1080	<entry>integer</entry>	1080	<entry>integer</entry>
1081	</row><row><entry spanname="descr">AAC bitrate in bits per second.</entry>	1081	</row><row><entry spanname="descr">AAC bitrate in bits per second.</entry>
1082	</row>	1082	</row>
1083	<row><entry></entry></row>	1083	<row><entry></entry></row>
1084	<row id="v4l2-mpeg-audio-ac3-bitrate">	1084	<row id="v4l2-mpeg-audio-ac3-bitrate">
1085	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant> </entry>	1085	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant> </entry>
1086	<entry>enum v4l2_mpeg_audio_ac3_bitrate</entry>	1086	<entry>enum v4l2_mpeg_audio_ac3_bitrate</entry>
1087	</row><row><entry spanname="descr">AC-3 bitrate.	1087	</row><row><entry spanname="descr">AC-3 bitrate.
1088	Possible values are:</entry>	1088	Possible values are:</entry>
1089	</row>	1089	</row>
1090	<row>	1090	<row>
1091	<entrytbl spanname="descr" cols="2">	1091	<entrytbl spanname="descr" cols="2">
1092	<tbody valign="top">	1092	<tbody valign="top">
1093	<row>	1093	<row>
1094	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant> </entry>	1094	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant> </entry>
1095	<entry>32 kbit/s</entry>	1095	<entry>32 kbit/s</entry>
1096	</row>	1096	</row>
1097	<row>	1097	<row>
1098	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant> </entry>	1098	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant> </entry>
1099	<entry>40 kbit/s</entry>	1099	<entry>40 kbit/s</entry>
1100	</row>	1100	</row>
1101	<row>	1101	<row>
1102	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant> </entry>	1102	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant> </entry>
1103	<entry>48 kbit/s</entry>	1103	<entry>48 kbit/s</entry>
1104	</row>	1104	</row>
1105	<row>	1105	<row>
1106	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant> </entry>	1106	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant> </entry>
1107	<entry>56 kbit/s</entry>	1107	<entry>56 kbit/s</entry>
1108	</row>	1108	</row>
1109	<row>	1109	<row>
1110	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant> </entry>	1110	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant> </entry>
1111	<entry>64 kbit/s</entry>	1111	<entry>64 kbit/s</entry>
1112	</row>	1112	</row>
1113	<row>	1113	<row>
1114	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant> </entry>	1114	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant> </entry>
1115	<entry>80 kbit/s</entry>	1115	<entry>80 kbit/s</entry>
1116	</row>	1116	</row>
1117	<row>	1117	<row>
1118	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant> </entry>	1118	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant> </entry>
1119	<entry>96 kbit/s</entry>	1119	<entry>96 kbit/s</entry>
1120	</row>	1120	</row>
1121	<row>	1121	<row>
1122	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant> </entry>	1122	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant> </entry>
1123	<entry>112 kbit/s</entry>	1123	<entry>112 kbit/s</entry>
1124	</row>	1124	</row>
1125	<row>	1125	<row>
1126	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant> </entry>	1126	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant> </entry>
1127	<entry>128 kbit/s</entry>	1127	<entry>128 kbit/s</entry>
1128	</row>	1128	</row>
1129	<row>	1129	<row>
1130	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant> </entry>	1130	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant> </entry>
1131	<entry>160 kbit/s</entry>	1131	<entry>160 kbit/s</entry>
1132	</row>	1132	</row>
1133	<row>	1133	<row>
1134	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant> </entry>	1134	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant> </entry>
1135	<entry>192 kbit/s</entry>	1135	<entry>192 kbit/s</entry>
1136	</row>	1136	</row>
1137	<row>	1137	<row>
1138	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant> </entry>	1138	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant> </entry>
1139	<entry>224 kbit/s</entry>	1139	<entry>224 kbit/s</entry>
1140	</row>	1140	</row>
1141	<row>	1141	<row>
1142	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant> </entry>	1142	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant> </entry>
1143	<entry>256 kbit/s</entry>	1143	<entry>256 kbit/s</entry>
1144	</row>	1144	</row>
1145	<row>	1145	<row>
1146	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant> </entry>	1146	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant> </entry>
1147	<entry>320 kbit/s</entry>	1147	<entry>320 kbit/s</entry>
1148	</row>	1148	</row>
1149	<row>	1149	<row>
1150	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant> </entry>	1150	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant> </entry>
1151	<entry>384 kbit/s</entry>	1151	<entry>384 kbit/s</entry>
1152	</row>	1152	</row>
1153	<row>	1153	<row>
1154	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant> </entry>	1154	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant> </entry>
1155	<entry>448 kbit/s</entry>	1155	<entry>448 kbit/s</entry>
1156	</row>	1156	</row>
1157	<row>	1157	<row>
1158	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant> </entry>	1158	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant> </entry>
1159	<entry>512 kbit/s</entry>	1159	<entry>512 kbit/s</entry>
1160	</row>	1160	</row>
1161	<row>	1161	<row>
1162	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant> </entry>	1162	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant> </entry>
1163	<entry>576 kbit/s</entry>	1163	<entry>576 kbit/s</entry>
1164	</row>	1164	</row>
1165	<row>	1165	<row>
1166	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant> </entry>	1166	<entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant> </entry>
1167	<entry>640 kbit/s</entry>	1167	<entry>640 kbit/s</entry>
1168	</row>	1168	</row>
1169	</tbody>	1169	</tbody>
1170	</entrytbl>	1170	</entrytbl>
1171	</row>	1171	</row>
1172	<row><entry></entry></row>	1172	<row><entry></entry></row>
1173	<row id="v4l2-mpeg-audio-mode">	1173	<row id="v4l2-mpeg-audio-mode">
1174	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant> </entry>	1174	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant> </entry>
1175	<entry>enum v4l2_mpeg_audio_mode</entry>	1175	<entry>enum v4l2_mpeg_audio_mode</entry>
1176	</row><row><entry spanname="descr">MPEG Audio mode.	1176	</row><row><entry spanname="descr">MPEG Audio mode.
1177	Possible values are:</entry>	1177	Possible values are:</entry>
1178	</row>	1178	</row>
1179	<row>	1179	<row>
1180	<entrytbl spanname="descr" cols="2">	1180	<entrytbl spanname="descr" cols="2">
1181	<tbody valign="top">	1181	<tbody valign="top">
1182	<row>	1182	<row>
1183	<entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant> </entry>	1183	<entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant> </entry>
1184	<entry>Stereo</entry>	1184	<entry>Stereo</entry>
1185	</row>	1185	</row>
1186	<row>	1186	<row>
1187	<entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant> </entry>	1187	<entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant> </entry>
1188	<entry>Joint Stereo</entry>	1188	<entry>Joint Stereo</entry>
1189	</row>	1189	</row>
1190	<row>	1190	<row>
1191	<entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant> </entry>	1191	<entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant> </entry>
1192	<entry>Bilingual</entry>	1192	<entry>Bilingual</entry>
1193	</row>	1193	</row>
1194	<row>	1194	<row>
1195	<entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant> </entry>	1195	<entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant> </entry>
1196	<entry>Mono</entry>	1196	<entry>Mono</entry>
1197	</row>	1197	</row>
1198	</tbody>	1198	</tbody>
1199	</entrytbl>	1199	</entrytbl>
1200	</row>	1200	</row>
1201	<row><entry></entry></row>	1201	<row><entry></entry></row>
1202	<row id="v4l2-mpeg-audio-mode-extension">	1202	<row id="v4l2-mpeg-audio-mode-extension">
1203	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant> </entry>	1203	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant> </entry>
1204	<entry>enum v4l2_mpeg_audio_mode_extension</entry>	1204	<entry>enum v4l2_mpeg_audio_mode_extension</entry>
1205	</row><row><entry spanname="descr">Joint Stereo	1205	</row><row><entry spanname="descr">Joint Stereo
1206	audio mode extension. In Layer I and II they indicate which subbands	1206	audio mode extension. In Layer I and II they indicate which subbands
1207	are in intensity stereo. All other subbands are coded in stereo. Layer	1207	are in intensity stereo. All other subbands are coded in stereo. Layer
1208	III is not (yet) supported. Possible values	1208	III is not (yet) supported. Possible values
1209	are:</entry>	1209	are:</entry>
1210	</row>	1210	</row>
1211	<row>	1211	<row>
1212	<entrytbl spanname="descr" cols="2">	1212	<entrytbl spanname="descr" cols="2">
1213	<tbody valign="top">	1213	<tbody valign="top">
1214	<row>	1214	<row>
1215	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant> </entry>	1215	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant> </entry>
1216	<entry>Subbands 4-31 in intensity stereo</entry>	1216	<entry>Subbands 4-31 in intensity stereo</entry>
1217	</row>	1217	</row>
1218	<row>	1218	<row>
1219	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant> </entry>	1219	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant> </entry>
1220	<entry>Subbands 8-31 in intensity stereo</entry>	1220	<entry>Subbands 8-31 in intensity stereo</entry>
1221	</row>	1221	</row>
1222	<row>	1222	<row>
1223	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant> </entry>	1223	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant> </entry>
1224	<entry>Subbands 12-31 in intensity stereo</entry>	1224	<entry>Subbands 12-31 in intensity stereo</entry>
1225	</row>	1225	</row>
1226	<row>	1226	<row>
1227	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant> </entry>	1227	<entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant> </entry>
1228	<entry>Subbands 16-31 in intensity stereo</entry>	1228	<entry>Subbands 16-31 in intensity stereo</entry>
1229	</row>	1229	</row>
1230	</tbody>	1230	</tbody>
1231	</entrytbl>	1231	</entrytbl>
1232	</row>	1232	</row>
1233	<row><entry></entry></row>	1233	<row><entry></entry></row>
1234	<row id="v4l2-mpeg-audio-emphasis">	1234	<row id="v4l2-mpeg-audio-emphasis">
1235	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant> </entry>	1235	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant> </entry>
1236	<entry>enum v4l2_mpeg_audio_emphasis</entry>	1236	<entry>enum v4l2_mpeg_audio_emphasis</entry>
1237	</row><row><entry spanname="descr">Audio Emphasis.	1237	</row><row><entry spanname="descr">Audio Emphasis.
1238	Possible values are:</entry>	1238	Possible values are:</entry>
1239	</row>	1239	</row>
1240	<row>	1240	<row>
1241	<entrytbl spanname="descr" cols="2">	1241	<entrytbl spanname="descr" cols="2">
1242	<tbody valign="top">	1242	<tbody valign="top">
1243	<row>	1243	<row>
1244	<entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant> </entry>	1244	<entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant> </entry>
1245	<entry>None</entry>	1245	<entry>None</entry>
1246	</row>	1246	</row>
1247	<row>	1247	<row>
1248	<entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant> </entry>	1248	<entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant> </entry>
1249	<entry>50/15 microsecond emphasis</entry>	1249	<entry>50/15 microsecond emphasis</entry>
1250	</row>	1250	</row>
1251	<row>	1251	<row>
1252	<entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant> </entry>	1252	<entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant> </entry>
1253	<entry>CCITT J.17</entry>	1253	<entry>CCITT J.17</entry>
1254	</row>	1254	</row>
1255	</tbody>	1255	</tbody>
1256	</entrytbl>	1256	</entrytbl>
1257	</row>	1257	</row>
1258	<row><entry></entry></row>	1258	<row><entry></entry></row>
1259	<row id="v4l2-mpeg-audio-crc">	1259	<row id="v4l2-mpeg-audio-crc">
1260	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant> </entry>	1260	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant> </entry>
1261	<entry>enum v4l2_mpeg_audio_crc</entry>	1261	<entry>enum v4l2_mpeg_audio_crc</entry>
1262	</row><row><entry spanname="descr">CRC method. Possible	1262	</row><row><entry spanname="descr">CRC method. Possible
1263	values are:</entry>	1263	values are:</entry>
1264	</row>	1264	</row>
1265	<row>	1265	<row>
1266	<entrytbl spanname="descr" cols="2">	1266	<entrytbl spanname="descr" cols="2">
1267	<tbody valign="top">	1267	<tbody valign="top">
1268	<row>	1268	<row>
1269	<entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant> </entry>	1269	<entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant> </entry>
1270	<entry>None</entry>	1270	<entry>None</entry>
1271	</row>	1271	</row>
1272	<row>	1272	<row>
1273	<entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant> </entry>	1273	<entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant> </entry>
1274	<entry>16 bit parity check</entry>	1274	<entry>16 bit parity check</entry>
1275	</row>	1275	</row>
1276	</tbody>	1276	</tbody>
1277	</entrytbl>	1277	</entrytbl>
1278	</row>	1278	</row>
1279	<row><entry></entry></row>	1279	<row><entry></entry></row>
1280	<row>	1280	<row>
1281	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant> </entry>	1281	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant> </entry>
1282	<entry>boolean</entry>	1282	<entry>boolean</entry>
1283	</row><row><entry spanname="descr">Mutes the audio when	1283	</row><row><entry spanname="descr">Mutes the audio when
1284	capturing. This is not done by muting audio hardware, which can still	1284	capturing. This is not done by muting audio hardware, which can still
1285	produce a slight hiss, but in the encoder itself, guaranteeing a fixed	1285	produce a slight hiss, but in the encoder itself, guaranteeing a fixed
1286	and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry>	1286	and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry>
1287	</row>	1287	</row>
1288	<row><entry></entry></row>	1288	<row><entry></entry></row>
1289	<row id="v4l2-mpeg-audio-dec-playback">	1289	<row id="v4l2-mpeg-audio-dec-playback">
1290	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> </entry>	1290	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> </entry>
1291	<entry>enum v4l2_mpeg_audio_dec_playback</entry>	1291	<entry>enum v4l2_mpeg_audio_dec_playback</entry>
1292	</row><row><entry spanname="descr">Determines how monolingual audio should be played back.	1292	</row><row><entry spanname="descr">Determines how monolingual audio should be played back.
1293	Possible values are:</entry>	1293	Possible values are:</entry>
1294	</row>	1294	</row>
1295	<row>	1295	<row>
1296	<entrytbl spanname="descr" cols="2">	1296	<entrytbl spanname="descr" cols="2">
1297	<tbody valign="top">	1297	<tbody valign="top">
1298	<row>	1298	<row>
1299	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO</constant> </entry>	1299	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO</constant> </entry>
1300	<entry>Automatically determines the best playback mode.</entry>	1300	<entry>Automatically determines the best playback mode.</entry>
1301	</row>	1301	</row>
1302	<row>	1302	<row>
1303	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO</constant> </entry>	1303	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO</constant> </entry>
1304	<entry>Stereo playback.</entry>	1304	<entry>Stereo playback.</entry>
1305	</row>	1305	</row>
1306	<row>	1306	<row>
1307	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT</constant> </entry>	1307	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT</constant> </entry>
1308	<entry>Left channel playback.</entry>	1308	<entry>Left channel playback.</entry>
1309	</row>	1309	</row>
1310	<row>	1310	<row>
1311	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT</constant> </entry>	1311	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT</constant> </entry>
1312	<entry>Right channel playback.</entry>	1312	<entry>Right channel playback.</entry>
1313	</row>	1313	</row>
1314	<row>	1314	<row>
1315	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO</constant> </entry>	1315	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO</constant> </entry>
1316	<entry>Mono playback.</entry>	1316	<entry>Mono playback.</entry>
1317	</row>	1317	</row>
1318	<row>	1318	<row>
1319	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO</constant> </entry>	1319	<entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO</constant> </entry>
1320	<entry>Stereo playback with swapped left and right channels.</entry>	1320	<entry>Stereo playback with swapped left and right channels.</entry>
1321	</row>	1321	</row>
1322	</tbody>	1322	</tbody>
1323	</entrytbl>	1323	</entrytbl>
1324	</row>	1324	</row>
1325	<row><entry></entry></row>	1325	<row><entry></entry></row>
1326	<row id="v4l2-mpeg-audio-dec-multilingual-playback">	1326	<row id="v4l2-mpeg-audio-dec-multilingual-playback">
1327	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> </entry>	1327	<entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> </entry>
1328	<entry>enum v4l2_mpeg_audio_dec_playback</entry>	1328	<entry>enum v4l2_mpeg_audio_dec_playback</entry>
1329	</row><row><entry spanname="descr">Determines how multilingual audio should be played back.</entry>	1329	</row><row><entry spanname="descr">Determines how multilingual audio should be played back.</entry>
1330	</row>	1330	</row>
1331	<row><entry></entry></row>	1331	<row><entry></entry></row>
1332	<row id="v4l2-mpeg-video-encoding">	1332	<row id="v4l2-mpeg-video-encoding">
1333	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant> </entry>	1333	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant> </entry>
1334	<entry>enum v4l2_mpeg_video_encoding</entry>	1334	<entry>enum v4l2_mpeg_video_encoding</entry>
1335	</row><row><entry spanname="descr">MPEG Video encoding	1335	</row><row><entry spanname="descr">MPEG Video encoding
1336	method. This control is specific to multiplexed MPEG streams.	1336	method. This control is specific to multiplexed MPEG streams.
1337	Possible values are:</entry>	1337	Possible values are:</entry>
1338	</row>	1338	</row>
1339	<row>	1339	<row>
1340	<entrytbl spanname="descr" cols="2">	1340	<entrytbl spanname="descr" cols="2">
1341	<tbody valign="top">	1341	<tbody valign="top">
1342	<row>	1342	<row>
1343	<entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant> </entry>	1343	<entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant> </entry>
1344	<entry>MPEG-1 Video encoding</entry>	1344	<entry>MPEG-1 Video encoding</entry>
1345	</row>	1345	</row>
1346	<row>	1346	<row>
1347	<entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant> </entry>	1347	<entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant> </entry>
1348	<entry>MPEG-2 Video encoding</entry>	1348	<entry>MPEG-2 Video encoding</entry>
1349	</row>	1349	</row>
1350	<row>	1350	<row>
1351	<entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> </entry>	1351	<entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> </entry>
1352	<entry>MPEG-4 AVC (H.264) Video encoding</entry>	1352	<entry>MPEG-4 AVC (H.264) Video encoding</entry>
1353	</row>	1353	</row>
1354	</tbody>	1354	</tbody>
1355	</entrytbl>	1355	</entrytbl>
1356	</row>	1356	</row>
1357	<row><entry></entry></row>	1357	<row><entry></entry></row>
1358	<row id="v4l2-mpeg-video-aspect">	1358	<row id="v4l2-mpeg-video-aspect">
1359	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant> </entry>	1359	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant> </entry>
1360	<entry>enum v4l2_mpeg_video_aspect</entry>	1360	<entry>enum v4l2_mpeg_video_aspect</entry>
1361	</row><row><entry spanname="descr">Video aspect.	1361	</row><row><entry spanname="descr">Video aspect.
1362	Possible values are:</entry>	1362	Possible values are:</entry>
1363	</row>	1363	</row>
1364	<row>	1364	<row>
1365	<entrytbl spanname="descr" cols="2">	1365	<entrytbl spanname="descr" cols="2">
1366	<tbody valign="top">	1366	<tbody valign="top">
1367	<row>	1367	<row>
1368	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant> </entry>	1368	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant> </entry>
1369	</row>	1369	</row>
1370	<row>	1370	<row>
1371	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant> </entry>	1371	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant> </entry>
1372	</row>	1372	</row>
1373	<row>	1373	<row>
1374	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant> </entry>	1374	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant> </entry>
1375	</row>	1375	</row>
1376	<row>	1376	<row>
1377	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant> </entry>	1377	<entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant> </entry>
1378	</row>	1378	</row>
1379	</tbody>	1379	</tbody>
1380	</entrytbl>	1380	</entrytbl>
1381	</row>	1381	</row>
1382	<row><entry></entry></row>	1382	<row><entry></entry></row>
1383	<row>	1383	<row>
1384	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant> </entry>	1384	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant> </entry>
1385	<entry>integer</entry>	1385	<entry>integer</entry>
1386	</row><row><entry spanname="descr">Number of B-Frames	1386	</row><row><entry spanname="descr">Number of B-Frames
1387	(default 2)</entry>	1387	(default 2)</entry>
1388	</row>	1388	</row>
1389	<row><entry></entry></row>	1389	<row><entry></entry></row>
1390	<row>	1390	<row>
1391	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant> </entry>	1391	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant> </entry>
1392	<entry>integer</entry>	1392	<entry>integer</entry>
1393	</row><row><entry spanname="descr">GOP size (default	1393	</row><row><entry spanname="descr">GOP size (default
1394	12)</entry>	1394	12)</entry>
1395	</row>	1395	</row>
1396	<row><entry></entry></row>	1396	<row><entry></entry></row>
1397	<row>	1397	<row>
1398	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant> </entry>	1398	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant> </entry>
1399	<entry>boolean</entry>	1399	<entry>boolean</entry>
1400	</row><row><entry spanname="descr">GOP closure (default	1400	</row><row><entry spanname="descr">GOP closure (default
1401	1)</entry>	1401	1)</entry>
1402	</row>	1402	</row>
1403	<row><entry></entry></row>	1403	<row><entry></entry></row>
1404	<row>	1404	<row>
1405	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant> </entry>	1405	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant> </entry>
1406	<entry>boolean</entry>	1406	<entry>boolean</entry>
1407	</row><row><entry spanname="descr">Enable 3:2 pulldown	1407	</row><row><entry spanname="descr">Enable 3:2 pulldown
1408	(default 0)</entry>	1408	(default 0)</entry>
1409	</row>	1409	</row>
1410	<row><entry></entry></row>	1410	<row><entry></entry></row>
1411	<row id="v4l2-mpeg-video-bitrate-mode">	1411	<row id="v4l2-mpeg-video-bitrate-mode">
1412	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant> </entry>	1412	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant> </entry>
1413	<entry>enum v4l2_mpeg_video_bitrate_mode</entry>	1413	<entry>enum v4l2_mpeg_video_bitrate_mode</entry>
1414	</row><row><entry spanname="descr">Video bitrate mode.	1414	</row><row><entry spanname="descr">Video bitrate mode.
1415	Possible values are:</entry>	1415	Possible values are:</entry>
1416	</row>	1416	</row>
1417	<row>	1417	<row>
1418	<entrytbl spanname="descr" cols="2">	1418	<entrytbl spanname="descr" cols="2">
1419	<tbody valign="top">	1419	<tbody valign="top">
1420	<row>	1420	<row>
1421	<entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant> </entry>	1421	<entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant> </entry>
1422	<entry>Variable bitrate</entry>	1422	<entry>Variable bitrate</entry>
1423	</row>	1423	</row>
1424	<row>	1424	<row>
1425	<entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant> </entry>	1425	<entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant> </entry>
1426	<entry>Constant bitrate</entry>	1426	<entry>Constant bitrate</entry>
1427	</row>	1427	</row>
1428	</tbody>	1428	</tbody>
1429	</entrytbl>	1429	</entrytbl>
1430	</row>	1430	</row>
1431	<row><entry></entry></row>	1431	<row><entry></entry></row>
1432	<row>	1432	<row>
1433	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant> </entry>	1433	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant> </entry>
1434	<entry>integer</entry>	1434	<entry>integer</entry>
1435	</row><row><entry spanname="descr">Video bitrate in bits	1435	</row><row><entry spanname="descr">Video bitrate in bits
1436	per second.</entry>	1436	per second.</entry>
1437	</row>	1437	</row>
1438	<row><entry></entry></row>	1438	<row><entry></entry></row>
1439	<row>	1439	<row>
1440	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant> </entry>	1440	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant> </entry>
1441	<entry>integer</entry>	1441	<entry>integer</entry>
1442	</row><row><entry spanname="descr">Peak video bitrate in	1442	</row><row><entry spanname="descr">Peak video bitrate in
1443	bits per second. Must be larger or equal to the average video bitrate.	1443	bits per second. Must be larger or equal to the average video bitrate.
1444	It is ignored if the video bitrate mode is set to constant	1444	It is ignored if the video bitrate mode is set to constant
1445	bitrate.</entry>	1445	bitrate.</entry>
1446	</row>	1446	</row>
1447	<row><entry></entry></row>	1447	<row><entry></entry></row>
1448	<row>	1448	<row>
1449	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant> </entry>	1449	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant> </entry>
1450	<entry>integer</entry>	1450	<entry>integer</entry>
1451	</row><row><entry spanname="descr">For every captured	1451	</row><row><entry spanname="descr">For every captured
1452	frame, skip this many subsequent frames (default 0).</entry>	1452	frame, skip this many subsequent frames (default 0).</entry>
1453	</row>	1453	</row>
1454	<row><entry></entry></row>	1454	<row><entry></entry></row>
1455	<row>	1455	<row>
1456	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant> </entry>	1456	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant> </entry>
1457	<entry>boolean</entry>	1457	<entry>boolean</entry>
1458	</row>	1458	</row>
1459	<row><entry spanname="descr">"Mutes" the video to a	1459	<row><entry spanname="descr">"Mutes" the video to a
1460	fixed color when capturing. This is useful for testing, to produce a	1460	fixed color when capturing. This is useful for testing, to produce a
1461	fixed video bitstream. 0 = unmuted, 1 = muted.</entry>	1461	fixed video bitstream. 0 = unmuted, 1 = muted.</entry>
1462	</row>	1462	</row>
1463	<row><entry></entry></row>	1463	<row><entry></entry></row>
1464	<row>	1464	<row>
1465	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant> </entry>	1465	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant> </entry>
1466	<entry>integer</entry>	1466	<entry>integer</entry>
1467	</row><row><entry spanname="descr">Sets the "mute" color	1467	</row><row><entry spanname="descr">Sets the "mute" color
1468	of the video. The supplied 32-bit integer is interpreted as follows (bit	1468	of the video. The supplied 32-bit integer is interpreted as follows (bit
1469	0 = least significant bit):</entry>	1469	0 = least significant bit):</entry>
1470	</row>	1470	</row>
1471	<row>	1471	<row>
1472	<entrytbl spanname="descr" cols="2">	1472	<entrytbl spanname="descr" cols="2">
1473	<tbody valign="top">	1473	<tbody valign="top">
1474	<row>	1474	<row>
1475	<entry>Bit 0:7</entry>	1475	<entry>Bit 0:7</entry>
1476	<entry>V chrominance information</entry>	1476	<entry>V chrominance information</entry>
1477	</row>	1477	</row>
1478	<row>	1478	<row>
1479	<entry>Bit 8:15</entry>	1479	<entry>Bit 8:15</entry>
1480	<entry>U chrominance information</entry>	1480	<entry>U chrominance information</entry>
1481	</row>	1481	</row>
1482	<row>	1482	<row>
1483	<entry>Bit 16:23</entry>	1483	<entry>Bit 16:23</entry>
1484	<entry>Y luminance information</entry>	1484	<entry>Y luminance information</entry>
1485	</row>	1485	</row>
1486	<row>	1486	<row>
1487	<entry>Bit 24:31</entry>	1487	<entry>Bit 24:31</entry>
1488	<entry>Must be zero.</entry>	1488	<entry>Must be zero.</entry>
1489	</row>	1489	</row>
1490	</tbody>	1490	</tbody>
1491	</entrytbl>	1491	</entrytbl>
1492	</row>	1492	</row>
1493	<row><entry></entry></row>	1493	<row><entry></entry></row>
1494	<row id="v4l2-mpeg-video-dec-pts">	1494	<row id="v4l2-mpeg-video-dec-pts">
1495	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> </entry>	1495	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> </entry>
1496	<entry>integer64</entry>	1496	<entry>integer64</entry>
1497	</row><row><entry spanname="descr">This read-only control returns the	1497	</row><row><entry spanname="descr">This read-only control returns the
1498	33-bit video Presentation Time Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of	1498	33-bit video Presentation Time Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of
1499	the currently displayed frame. This is the same PTS as is used in &VIDIOC-DECODER-CMD;.</entry>	1499	the currently displayed frame. This is the same PTS as is used in &VIDIOC-DECODER-CMD;.</entry>
1500	</row>	1500	</row>
1501	<row><entry></entry></row>	1501	<row><entry></entry></row>
1502	<row id="v4l2-mpeg-video-dec-frame">	1502	<row id="v4l2-mpeg-video-dec-frame">
1503	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> </entry>	1503	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> </entry>
1504	<entry>integer64</entry>	1504	<entry>integer64</entry>
1505	</row><row><entry spanname="descr">This read-only control returns the	1505	</row><row><entry spanname="descr">This read-only control returns the
1506	frame counter of the frame that is currently displayed (decoded). This value is reset to 0 whenever	1506	frame counter of the frame that is currently displayed (decoded). This value is reset to 0 whenever
1507	the decoder is started.</entry>	1507	the decoder is started.</entry>
1508	</row>	1508	</row>
1509		1509
1510		1510
1511	<row><entry></entry></row>	1511	<row><entry></entry></row>
1512	<row>	1512	<row>
1513	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE</constant> </entry>	1513	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE</constant> </entry>
1514	<entry>boolean</entry>	1514	<entry>boolean</entry>
1515	</row>	1515	</row>
1516	<row><entry spanname="descr">If enabled the decoder expects to receive a single slice per buffer, otherwise	1516	<row><entry spanname="descr">If enabled the decoder expects to receive a single slice per buffer, otherwise
1517	the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs.	1517	the decoder expects a single frame in per buffer. Applicable to the decoder, all codecs.
1518	</entry>	1518	</entry>
1519	</row>	1519	</row>
1520		1520
1521	<row><entry></entry></row>	1521	<row><entry></entry></row>
1522	<row>	1522	<row>
1523	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE</constant> </entry>	1523	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE</constant> </entry>
1524	<entry>boolean</entry>	1524	<entry>boolean</entry>
1525	</row>	1525	</row>
1526	<row><entry spanname="descr">Enable writing sample aspect ratio in the Video Usability Information.	1526	<row><entry spanname="descr">Enable writing sample aspect ratio in the Video Usability Information.
1527	Applicable to the H264 encoder.</entry>	1527	Applicable to the H264 encoder.</entry>
1528	</row>	1528	</row>
1529		1529
1530	<row><entry></entry></row>	1530	<row><entry></entry></row>
1531	<row id="v4l2-mpeg-video-h264-vui-sar-idc">	1531	<row id="v4l2-mpeg-video-h264-vui-sar-idc">
1532	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC</constant> </entry>	1532	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC</constant> </entry>
1533	<entry>enum v4l2_mpeg_video_h264_vui_sar_idc</entry>	1533	<entry>enum v4l2_mpeg_video_h264_vui_sar_idc</entry>
1534	</row>	1534	</row>
1535	<row><entry spanname="descr">VUI sample aspect ratio indicator for H.264 encoding. The value	1535	<row><entry spanname="descr">VUI sample aspect ratio indicator for H.264 encoding. The value
1536	is defined in the table E-1 in the standard. Applicable to the H264 encoder.</entry>	1536	is defined in the table E-1 in the standard. Applicable to the H264 encoder.</entry>
1537	</row>	1537	</row>
1538	<row>	1538	<row>
1539	<entrytbl spanname="descr" cols="2">	1539	<entrytbl spanname="descr" cols="2">
1540	<tbody valign="top">	1540	<tbody valign="top">
1541		1541
1542	<row>	1542	<row>
1543	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED</constant> </entry>	1543	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED</constant> </entry>
1544	<entry>Unspecified</entry>	1544	<entry>Unspecified</entry>
1545	</row>	1545	</row>
1546	<row>	1546	<row>
1547	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1</constant> </entry>	1547	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1</constant> </entry>
1548	<entry>1x1</entry>	1548	<entry>1x1</entry>
1549	</row>	1549	</row>
1550	<row>	1550	<row>
1551	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11</constant> </entry>	1551	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11</constant> </entry>
1552	<entry>12x11</entry>	1552	<entry>12x11</entry>
1553	</row>	1553	</row>
1554	<row>	1554	<row>
1555	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11</constant> </entry>	1555	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11</constant> </entry>
1556	<entry>10x11</entry>	1556	<entry>10x11</entry>
1557	</row>	1557	</row>
1558	<row>	1558	<row>
1559	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11</constant> </entry>	1559	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11</constant> </entry>
1560	<entry>16x11</entry>	1560	<entry>16x11</entry>
1561	</row>	1561	</row>
1562	<row>	1562	<row>
1563	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33</constant> </entry>	1563	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33</constant> </entry>
1564	<entry>40x33</entry>	1564	<entry>40x33</entry>
1565	</row>	1565	</row>
1566	<row>	1566	<row>
1567	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11</constant> </entry>	1567	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11</constant> </entry>
1568	<entry>24x11</entry>	1568	<entry>24x11</entry>
1569	</row>	1569	</row>
1570	<row>	1570	<row>
1571	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11</constant> </entry>	1571	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11</constant> </entry>
1572	<entry>20x11</entry>	1572	<entry>20x11</entry>
1573	</row>	1573	</row>
1574	<row>	1574	<row>
1575	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11</constant> </entry>	1575	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11</constant> </entry>
1576	<entry>32x11</entry>	1576	<entry>32x11</entry>
1577	</row>	1577	</row>
1578	<row>	1578	<row>
1579	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33</constant> </entry>	1579	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33</constant> </entry>
1580	<entry>80x33</entry>	1580	<entry>80x33</entry>
1581	</row>	1581	</row>
1582	<row>	1582	<row>
1583	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11</constant> </entry>	1583	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11</constant> </entry>
1584	<entry>18x11</entry>	1584	<entry>18x11</entry>
1585	</row>	1585	</row>
1586	<row>	1586	<row>
1587	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11</constant> </entry>	1587	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11</constant> </entry>
1588	<entry>15x11</entry>	1588	<entry>15x11</entry>
1589	</row>	1589	</row>
1590	<row>	1590	<row>
1591	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33</constant> </entry>	1591	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33</constant> </entry>
1592	<entry>64x33</entry>	1592	<entry>64x33</entry>
1593	</row>	1593	</row>
1594	<row>	1594	<row>
1595	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99</constant> </entry>	1595	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99</constant> </entry>
1596	<entry>160x99</entry>	1596	<entry>160x99</entry>
1597	</row>	1597	</row>
1598	<row>	1598	<row>
1599	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3</constant> </entry>	1599	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3</constant> </entry>
1600	<entry>4x3</entry>	1600	<entry>4x3</entry>
1601	</row>	1601	</row>
1602	<row>	1602	<row>
1603	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2</constant> </entry>	1603	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2</constant> </entry>
1604	<entry>3x2</entry>	1604	<entry>3x2</entry>
1605	</row>	1605	</row>
1606	<row>	1606	<row>
1607	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1</constant> </entry>	1607	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1</constant> </entry>
1608	<entry>2x1</entry>	1608	<entry>2x1</entry>
1609	</row>	1609	</row>
1610	<row>	1610	<row>
1611	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED</constant> </entry>	1611	<entry><constant>V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED</constant> </entry>
1612	<entry>Extended SAR</entry>	1612	<entry>Extended SAR</entry>
1613	</row>	1613	</row>
1614	</tbody>	1614	</tbody>
1615	</entrytbl>	1615	</entrytbl>
1616	</row>	1616	</row>
1617		1617
1618	<row><entry></entry></row>	1618	<row><entry></entry></row>
1619	<row>	1619	<row>
1620	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH</constant> </entry>	1620	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH</constant> </entry>
1621	<entry>integer</entry>	1621	<entry>integer</entry>
1622	</row>	1622	</row>
1623	<row><entry spanname="descr">Extended sample aspect ratio width for H.264 VUI encoding.	1623	<row><entry spanname="descr">Extended sample aspect ratio width for H.264 VUI encoding.
1624	Applicable to the H264 encoder.</entry>	1624	Applicable to the H264 encoder.</entry>
1625	</row>	1625	</row>
1626		1626
1627	<row><entry></entry></row>	1627	<row><entry></entry></row>
1628	<row>	1628	<row>
1629	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT</constant> </entry>	1629	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT</constant> </entry>
1630	<entry>integer</entry>	1630	<entry>integer</entry>
1631	</row>	1631	</row>
1632	<row><entry spanname="descr">Extended sample aspect ratio height for H.264 VUI encoding.	1632	<row><entry spanname="descr">Extended sample aspect ratio height for H.264 VUI encoding.
1633	Applicable to the H264 encoder.</entry>	1633	Applicable to the H264 encoder.</entry>
1634	</row>	1634	</row>
1635		1635
1636	<row><entry></entry></row>	1636	<row><entry></entry></row>
1637	<row id="v4l2-mpeg-video-h264-level">	1637	<row id="v4l2-mpeg-video-h264-level">
1638	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LEVEL</constant> </entry>	1638	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LEVEL</constant> </entry>
1639	<entry>enum v4l2_mpeg_video_h264_level</entry>	1639	<entry>enum v4l2_mpeg_video_h264_level</entry>
1640	</row>	1640	</row>
1641	<row><entry spanname="descr">The level information for the H264 video elementary stream.	1641	<row><entry spanname="descr">The level information for the H264 video elementary stream.
1642	Applicable to the H264 encoder.	1642	Applicable to the H264 encoder.
1643	Possible values are:</entry>	1643	Possible values are:</entry>
1644	</row>	1644	</row>
1645	<row>	1645	<row>
1646	<entrytbl spanname="descr" cols="2">	1646	<entrytbl spanname="descr" cols="2">
1647	<tbody valign="top">	1647	<tbody valign="top">
1648	<row>	1648	<row>
1649	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_0</constant> </entry>	1649	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_0</constant> </entry>
1650	<entry>Level 1.0</entry>	1650	<entry>Level 1.0</entry>
1651	</row>	1651	</row>
1652	<row>	1652	<row>
1653	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1B</constant> </entry>	1653	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1B</constant> </entry>
1654	<entry>Level 1B</entry>	1654	<entry>Level 1B</entry>
1655	</row>	1655	</row>
1656	<row>	1656	<row>
1657	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_1</constant> </entry>	1657	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_1</constant> </entry>
1658	<entry>Level 1.1</entry>	1658	<entry>Level 1.1</entry>
1659	</row>	1659	</row>
1660	<row>	1660	<row>
1661	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_2</constant> </entry>	1661	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_2</constant> </entry>
1662	<entry>Level 1.2</entry>	1662	<entry>Level 1.2</entry>
1663	</row>	1663	</row>
1664	<row>	1664	<row>
1665	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_3</constant> </entry>	1665	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_1_3</constant> </entry>
1666	<entry>Level 1.3</entry>	1666	<entry>Level 1.3</entry>
1667	</row>	1667	</row>
1668	<row>	1668	<row>
1669	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_0</constant> </entry>	1669	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_0</constant> </entry>
1670	<entry>Level 2.0</entry>	1670	<entry>Level 2.0</entry>
1671	</row>	1671	</row>
1672	<row>	1672	<row>
1673	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_1</constant> </entry>	1673	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_1</constant> </entry>
1674	<entry>Level 2.1</entry>	1674	<entry>Level 2.1</entry>
1675	</row>	1675	</row>
1676	<row>	1676	<row>
1677	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_2</constant> </entry>	1677	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_2_2</constant> </entry>
1678	<entry>Level 2.2</entry>	1678	<entry>Level 2.2</entry>
1679	</row>	1679	</row>
1680	<row>	1680	<row>
1681	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_0</constant> </entry>	1681	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_0</constant> </entry>
1682	<entry>Level 3.0</entry>	1682	<entry>Level 3.0</entry>
1683	</row>	1683	</row>
1684	<row>	1684	<row>
1685	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_1</constant> </entry>	1685	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_1</constant> </entry>
1686	<entry>Level 3.1</entry>	1686	<entry>Level 3.1</entry>
1687	</row>	1687	</row>
1688	<row>	1688	<row>
1689	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_2</constant> </entry>	1689	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_3_2</constant> </entry>
1690	<entry>Level 3.2</entry>	1690	<entry>Level 3.2</entry>
1691	</row>	1691	</row>
1692	<row>	1692	<row>
1693	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_0</constant> </entry>	1693	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_0</constant> </entry>
1694	<entry>Level 4.0</entry>	1694	<entry>Level 4.0</entry>
1695	</row>	1695	</row>
1696	<row>	1696	<row>
1697	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_1</constant> </entry>	1697	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_1</constant> </entry>
1698	<entry>Level 4.1</entry>	1698	<entry>Level 4.1</entry>
1699	</row>	1699	</row>
1700	<row>	1700	<row>
1701	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_2</constant> </entry>	1701	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_4_2</constant> </entry>
1702	<entry>Level 4.2</entry>	1702	<entry>Level 4.2</entry>
1703	</row>	1703	</row>
1704	<row>	1704	<row>
1705	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_0</constant> </entry>	1705	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_0</constant> </entry>
1706	<entry>Level 5.0</entry>	1706	<entry>Level 5.0</entry>
1707	</row>	1707	</row>
1708	<row>	1708	<row>
1709	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_1</constant> </entry>	1709	<entry><constant>V4L2_MPEG_VIDEO_H264_LEVEL_5_1</constant> </entry>
1710	<entry>Level 5.1</entry>	1710	<entry>Level 5.1</entry>
1711	</row>	1711	</row>
1712	</tbody>	1712	</tbody>
1713	</entrytbl>	1713	</entrytbl>
1714	</row>	1714	</row>
1715		1715
1716	<row><entry></entry></row>	1716	<row><entry></entry></row>
1717	<row id="v4l2-mpeg-video-mpeg4-level">	1717	<row id="v4l2-mpeg-video-mpeg4-level">
1718	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL</constant> </entry>	1718	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL</constant> </entry>
1719	<entry>enum v4l2_mpeg_video_mpeg4_level</entry>	1719	<entry>enum v4l2_mpeg_video_mpeg4_level</entry>
1720	</row>	1720	</row>
1721	<row><entry spanname="descr">The level information for the MPEG4 elementary stream.	1721	<row><entry spanname="descr">The level information for the MPEG4 elementary stream.
1722	Applicable to the MPEG4 encoder.	1722	Applicable to the MPEG4 encoder.
1723	Possible values are:</entry>	1723	Possible values are:</entry>
1724	</row>	1724	</row>
1725	<row>	1725	<row>
1726	<entrytbl spanname="descr" cols="2">	1726	<entrytbl spanname="descr" cols="2">
1727	<tbody valign="top">	1727	<tbody valign="top">
1728	<row>	1728	<row>
1729	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_0</constant> </entry>	1729	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_0</constant> </entry>
1730	<entry>Level 0</entry>	1730	<entry>Level 0</entry>
1731	</row>	1731	</row>
1732	<row>	1732	<row>
1733	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_0B</constant> </entry>	1733	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_0B</constant> </entry>
1734	<entry>Level 0b</entry>	1734	<entry>Level 0b</entry>
1735	</row>	1735	</row>
1736	<row>	1736	<row>
1737	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_1</constant> </entry>	1737	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_1</constant> </entry>
1738	<entry>Level 1</entry>	1738	<entry>Level 1</entry>
1739	</row>	1739	</row>
1740	<row>	1740	<row>
1741	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_2</constant> </entry>	1741	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_2</constant> </entry>
1742	<entry>Level 2</entry>	1742	<entry>Level 2</entry>
1743	</row>	1743	</row>
1744	<row>	1744	<row>
1745	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_3</constant> </entry>	1745	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_3</constant> </entry>
1746	<entry>Level 3</entry>	1746	<entry>Level 3</entry>
1747	</row>	1747	</row>
1748	<row>	1748	<row>
1749	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_3B</constant> </entry>	1749	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_3B</constant> </entry>
1750	<entry>Level 3b</entry>	1750	<entry>Level 3b</entry>
1751	</row>	1751	</row>
1752	<row>	1752	<row>
1753	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_4</constant> </entry>	1753	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_4</constant> </entry>
1754	<entry>Level 4</entry>	1754	<entry>Level 4</entry>
1755	</row>	1755	</row>
1756	<row>	1756	<row>
1757	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_5</constant> </entry>	1757	<entry><constant>V4L2_MPEG_VIDEO_LEVEL_5</constant> </entry>
1758	<entry>Level 5</entry>	1758	<entry>Level 5</entry>
1759	</row>	1759	</row>
1760	</tbody>	1760	</tbody>
1761	</entrytbl>	1761	</entrytbl>
1762	</row>	1762	</row>
1763		1763
1764	<row><entry></entry></row>	1764	<row><entry></entry></row>
1765	<row id="v4l2-mpeg-video-h264-profile">	1765	<row id="v4l2-mpeg-video-h264-profile">
1766	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_PROFILE</constant> </entry>	1766	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_PROFILE</constant> </entry>
1767	<entry>enum v4l2_mpeg_video_h264_profile</entry>	1767	<entry>enum v4l2_mpeg_video_h264_profile</entry>
1768	</row>	1768	</row>
1769	<row><entry spanname="descr">The profile information for H264.	1769	<row><entry spanname="descr">The profile information for H264.
1770	Applicable to the H264 encoder.	1770	Applicable to the H264 encoder.
1771	Possible values are:</entry>	1771	Possible values are:</entry>
1772	</row>	1772	</row>
1773	<row>	1773	<row>
1774	<entrytbl spanname="descr" cols="2">	1774	<entrytbl spanname="descr" cols="2">
1775	<tbody valign="top">	1775	<tbody valign="top">
1776	<row>	1776	<row>
1777	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE</constant> </entry>	1777	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE</constant> </entry>
1778	<entry>Baseline profile</entry>	1778	<entry>Baseline profile</entry>
1779	</row>	1779	</row>
1780	<row>	1780	<row>
1781	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE</constant> </entry>	1781	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE</constant> </entry>
1782	<entry>Constrained Baseline profile</entry>	1782	<entry>Constrained Baseline profile</entry>
1783	</row>	1783	</row>
1784	<row>	1784	<row>
1785	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MAIN</constant> </entry>	1785	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MAIN</constant> </entry>
1786	<entry>Main profile</entry>	1786	<entry>Main profile</entry>
1787	</row>	1787	</row>
1788	<row>	1788	<row>
1789	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED</constant> </entry>	1789	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED</constant> </entry>
1790	<entry>Extended profile</entry>	1790	<entry>Extended profile</entry>
1791	</row>	1791	</row>
1792	<row>	1792	<row>
1793	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH</constant> </entry>	1793	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH</constant> </entry>
1794	<entry>High profile</entry>	1794	<entry>High profile</entry>
1795	</row>	1795	</row>
1796	<row>	1796	<row>
1797	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10</constant> </entry>	1797	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10</constant> </entry>
1798	<entry>High 10 profile</entry>	1798	<entry>High 10 profile</entry>
1799	</row>	1799	</row>
1800	<row>	1800	<row>
1801	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422</constant> </entry>	1801	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422</constant> </entry>
1802	<entry>High 422 profile</entry>	1802	<entry>High 422 profile</entry>
1803	</row>	1803	</row>
1804	<row>	1804	<row>
1805	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE</constant> </entry>	1805	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE</constant> </entry>
1806	<entry>High 444 Predictive profile</entry>	1806	<entry>High 444 Predictive profile</entry>
1807	</row>	1807	</row>
1808	<row>	1808	<row>
1809	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA</constant> </entry>	1809	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA</constant> </entry>
1810	<entry>High 10 Intra profile</entry>	1810	<entry>High 10 Intra profile</entry>
1811	</row>	1811	</row>
1812	<row>	1812	<row>
1813	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA</constant> </entry>	1813	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA</constant> </entry>
1814	<entry>High 422 Intra profile</entry>	1814	<entry>High 422 Intra profile</entry>
1815	</row>	1815	</row>
1816	<row>	1816	<row>
1817	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA</constant> </entry>	1817	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA</constant> </entry>
1818	<entry>High 444 Intra profile</entry>	1818	<entry>High 444 Intra profile</entry>
1819	</row>	1819	</row>
1820	<row>	1820	<row>
1821	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA</constant> </entry>	1821	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA</constant> </entry>
1822	<entry>CAVLC 444 Intra profile</entry>	1822	<entry>CAVLC 444 Intra profile</entry>
1823	</row>	1823	</row>
1824	<row>	1824	<row>
1825	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE</constant> </entry>	1825	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE</constant> </entry>
1826	<entry>Scalable Baseline profile</entry>	1826	<entry>Scalable Baseline profile</entry>
1827	</row>	1827	</row>
1828	<row>	1828	<row>
1829	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH</constant> </entry>	1829	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH</constant> </entry>
1830	<entry>Scalable High profile</entry>	1830	<entry>Scalable High profile</entry>
1831	</row>	1831	</row>
1832	<row>	1832	<row>
1833	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA</constant> </entry>	1833	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA</constant> </entry>
1834	<entry>Scalable High Intra profile</entry>	1834	<entry>Scalable High Intra profile</entry>
1835	</row>	1835	</row>
1836	<row>	1836	<row>
1837	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH</constant> </entry>	1837	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH</constant> </entry>
1838	<entry>Stereo High profile</entry>	1838	<entry>Stereo High profile</entry>
1839	</row>	1839	</row>
1840	<row>	1840	<row>
1841	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH</constant> </entry>	1841	<entry><constant>V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH</constant> </entry>
1842	<entry>Multiview High profile</entry>	1842	<entry>Multiview High profile</entry>
1843	</row>	1843	</row>
1844		1844
1845	</tbody>	1845	</tbody>
1846	</entrytbl>	1846	</entrytbl>
1847	</row>	1847	</row>
1848		1848
1849	<row><entry></entry></row>	1849	<row><entry></entry></row>
1850	<row id="v4l2-mpeg-video-mpeg4-profile">	1850	<row id="v4l2-mpeg-video-mpeg4-profile">
1851	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE</constant> </entry>	1851	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE</constant> </entry>
1852	<entry>enum v4l2_mpeg_video_mpeg4_profile</entry>	1852	<entry>enum v4l2_mpeg_video_mpeg4_profile</entry>
1853	</row>	1853	</row>
1854	<row><entry spanname="descr">The profile information for MPEG4.	1854	<row><entry spanname="descr">The profile information for MPEG4.
1855	Applicable to the MPEG4 encoder.	1855	Applicable to the MPEG4 encoder.
1856	Possible values are:</entry>	1856	Possible values are:</entry>
1857	</row>	1857	</row>
1858	<row>	1858	<row>
1859	<entrytbl spanname="descr" cols="2">	1859	<entrytbl spanname="descr" cols="2">
1860	<tbody valign="top">	1860	<tbody valign="top">
1861	<row>	1861	<row>
1862	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE</constant> </entry>	1862	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE</constant> </entry>
1863	<entry>Simple profile</entry>	1863	<entry>Simple profile</entry>
1864	</row>	1864	</row>
1865	<row>	1865	<row>
1866	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE</constant> </entry>	1866	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE</constant> </entry>
1867	<entry>Advanced Simple profile</entry>	1867	<entry>Advanced Simple profile</entry>
1868	</row>	1868	</row>
1869	<row>	1869	<row>
1870	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_CORE</constant> </entry>	1870	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_CORE</constant> </entry>
1871	<entry>Core profile</entry>	1871	<entry>Core profile</entry>
1872	</row>	1872	</row>
1873	<row>	1873	<row>
1874	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE</constant> </entry>	1874	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE</constant> </entry>
1875	<entry>Simple Scalable profile</entry>	1875	<entry>Simple Scalable profile</entry>
1876	</row>	1876	</row>
1877	<row>	1877	<row>
1878	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY</constant> </entry>	1878	<entry><constant>V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY</constant> </entry>
1879	<entry></entry>	1879	<entry></entry>
1880	</row>	1880	</row>
1881	</tbody>	1881	</tbody>
1882	</entrytbl>	1882	</entrytbl>
1883	</row>	1883	</row>
1884		1884
1885	<row><entry></entry></row>	1885	<row><entry></entry></row>
1886	<row>	1886	<row>
1887	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MAX_REF_PIC</constant> </entry>	1887	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MAX_REF_PIC</constant> </entry>
1888	<entry>integer</entry>	1888	<entry>integer</entry>
1889	</row>	1889	</row>
1890	<row><entry spanname="descr">The maximum number of reference pictures used for encoding.	1890	<row><entry spanname="descr">The maximum number of reference pictures used for encoding.
1891	Applicable to the encoder.	1891	Applicable to the encoder.
1892	</entry>	1892	</entry>
1893	</row>	1893	</row>
1894		1894
1895	<row><entry></entry></row>	1895	<row><entry></entry></row>
1896	<row id="v4l2-mpeg-video-multi-slice-mode">	1896	<row id="v4l2-mpeg-video-multi-slice-mode">
1897	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> </entry>	1897	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> </entry>
1898	<entry>enum v4l2_mpeg_video_multi_slice_mode</entry>	1898	<entry>enum v4l2_mpeg_video_multi_slice_mode</entry>
1899	</row>	1899	</row>
1900	<row><entry spanname="descr">Determines how the encoder should handle division of frame into slices.	1900	<row><entry spanname="descr">Determines how the encoder should handle division of frame into slices.
1901	Applicable to the encoder.	1901	Applicable to the encoder.
1902	Possible values are:</entry>	1902	Possible values are:</entry>
1903	</row>	1903	</row>
1904	<row>	1904	<row>
1905	<entrytbl spanname="descr" cols="2">	1905	<entrytbl spanname="descr" cols="2">
1906	<tbody valign="top">	1906	<tbody valign="top">
1907	<row>	1907	<row>
1908	<entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE</constant> </entry>	1908	<entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE</constant> </entry>
1909	<entry>Single slice per frame.</entry>	1909	<entry>Single slice per frame.</entry>
1910	</row>	1910	</row>
1911	<row>	1911	<row>
1912	<entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant> </entry>	1912	<entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant> </entry>
1913	<entry>Multiple slices with set maximum number of macroblocks per slice.</entry>	1913	<entry>Multiple slices with set maximum number of macroblocks per slice.</entry>
1914	</row>	1914	</row>
1915	<row>	1915	<row>
1916	<entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant> </entry>	1916	<entry><constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant> </entry>
1917	<entry>Multiple slice with set maximum size in bytes per slice.</entry>	1917	<entry>Multiple slice with set maximum size in bytes per slice.</entry>
1918	</row>	1918	</row>
1919	</tbody>	1919	</tbody>
1920	</entrytbl>	1920	</entrytbl>
1921	</row>	1921	</row>
1922		1922
1923	<row><entry></entry></row>	1923	<row><entry></entry></row>
1924	<row>	1924	<row>
1925	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB</constant> </entry>	1925	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB</constant> </entry>
1926	<entry>integer</entry>	1926	<entry>integer</entry>
1927	</row>	1927	</row>
1928	<row><entry spanname="descr">The maximum number of macroblocks in a slice. Used when	1928	<row><entry spanname="descr">The maximum number of macroblocks in a slice. Used when
1929	<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>.	1929	<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB</constant>.
1930	Applicable to the encoder.</entry>	1930	Applicable to the encoder.</entry>
1931	</row>	1931	</row>
1932		1932
1933	<row><entry></entry></row>	1933	<row><entry></entry></row>
1934	<row>	1934	<row>
1935	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES</constant> </entry>	1935	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES</constant> </entry>
1936	<entry>integer</entry>	1936	<entry>integer</entry>
1937	</row>	1937	</row>
1938	<row><entry spanname="descr">The maximum size of a slice in bytes. Used when	1938	<row><entry spanname="descr">The maximum size of a slice in bytes. Used when
1939	<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>.	1939	<constant>V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE</constant> is set to <constant>V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES</constant>.
1940	Applicable to the encoder.</entry>	1940	Applicable to the encoder.</entry>
1941	</row>	1941	</row>
1942		1942
1943	<row><entry></entry></row>	1943	<row><entry></entry></row>
1944	<row id="v4l2-mpeg-video-h264-loop-filter-mode">	1944	<row id="v4l2-mpeg-video-h264-loop-filter-mode">
1945	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE</constant> </entry>	1945	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE</constant> </entry>
1946	<entry>enum v4l2_mpeg_video_h264_loop_filter_mode</entry>	1946	<entry>enum v4l2_mpeg_video_h264_loop_filter_mode</entry>
1947	</row>	1947	</row>
1948	<row><entry spanname="descr">Loop filter mode for H264 encoder.	1948	<row><entry spanname="descr">Loop filter mode for H264 encoder.
1949	Possible values are:</entry>	1949	Possible values are:</entry>
1950	</row>	1950	</row>
1951	<row>	1951	<row>
1952	<entrytbl spanname="descr" cols="2">	1952	<entrytbl spanname="descr" cols="2">
1953	<tbody valign="top">	1953	<tbody valign="top">
1954	<row>	1954	<row>
1955	<entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED</constant> </entry>	1955	<entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED</constant> </entry>
1956	<entry>Loop filter is enabled.</entry>	1956	<entry>Loop filter is enabled.</entry>
1957	</row>	1957	</row>
1958	<row>	1958	<row>
1959	<entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED</constant> </entry>	1959	<entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED</constant> </entry>
1960	<entry>Loop filter is disabled.</entry>	1960	<entry>Loop filter is disabled.</entry>
1961	</row>	1961	</row>
1962	<row>	1962	<row>
1963	<entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY</constant> </entry>	1963	<entry><constant>V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY</constant> </entry>
1964	<entry>Loop filter is disabled at the slice boundary.</entry>	1964	<entry>Loop filter is disabled at the slice boundary.</entry>
1965	</row>	1965	</row>
1966	</tbody>	1966	</tbody>
1967	</entrytbl>	1967	</entrytbl>
1968	</row>	1968	</row>
1969		1969
1970	<row><entry></entry></row>	1970	<row><entry></entry></row>
1971	<row>	1971	<row>
1972	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA</constant> </entry>	1972	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA</constant> </entry>
1973	<entry>integer</entry>	1973	<entry>integer</entry>
1974	</row>	1974	</row>
1975	<row><entry spanname="descr">Loop filter alpha coefficient, defined in the H264 standard.	1975	<row><entry spanname="descr">Loop filter alpha coefficient, defined in the H264 standard.
1976	Applicable to the H264 encoder.</entry>	1976	Applicable to the H264 encoder.</entry>
1977	</row>	1977	</row>
1978		1978
1979	<row><entry></entry></row>	1979	<row><entry></entry></row>
1980	<row>	1980	<row>
1981	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA</constant> </entry>	1981	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA</constant> </entry>
1982	<entry>integer</entry>	1982	<entry>integer</entry>
1983	</row>	1983	</row>
1984	<row><entry spanname="descr">Loop filter beta coefficient, defined in the H264 standard.	1984	<row><entry spanname="descr">Loop filter beta coefficient, defined in the H264 standard.
1985	Applicable to the H264 encoder.</entry>	1985	Applicable to the H264 encoder.</entry>
1986	</row>	1986	</row>
1987		1987
1988	<row><entry></entry></row>	1988	<row><entry></entry></row>
1989	<row id="v4l2-mpeg-video-h264-entropy-mode">	1989	<row id="v4l2-mpeg-video-h264-entropy-mode">
1990	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE</constant> </entry>	1990	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE</constant> </entry>
1991	<entry>enum v4l2_mpeg_video_h264_entropy_mode</entry>	1991	<entry>enum v4l2_mpeg_video_h264_entropy_mode</entry>
1992	</row>	1992	</row>
1993	<row><entry spanname="descr">Entropy coding mode for H264 - CABAC/CAVALC.	1993	<row><entry spanname="descr">Entropy coding mode for H264 - CABAC/CAVALC.
1994	Applicable to the H264 encoder.	1994	Applicable to the H264 encoder.
1995	Possible values are:</entry>	1995	Possible values are:</entry>
1996	</row>	1996	</row>
1997	<row>	1997	<row>
1998	<entrytbl spanname="descr" cols="2">	1998	<entrytbl spanname="descr" cols="2">
1999	<tbody valign="top">	1999	<tbody valign="top">
2000	<row>	2000	<row>
2001	<entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC</constant> </entry>	2001	<entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC</constant> </entry>
2002	<entry>Use CAVLC entropy coding.</entry>	2002	<entry>Use CAVLC entropy coding.</entry>
2003	</row>	2003	</row>
2004	<row>	2004	<row>
2005	<entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC</constant> </entry>	2005	<entry><constant>V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC</constant> </entry>
2006	<entry>Use CABAC entropy coding.</entry>	2006	<entry>Use CABAC entropy coding.</entry>
2007	</row>	2007	</row>
2008	</tbody>	2008	</tbody>
2009	</entrytbl>	2009	</entrytbl>
2010	</row>	2010	</row>
2011		2011
2012	<row><entry></entry></row>	2012	<row><entry></entry></row>
2013	<row>	2013	<row>
2014	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM</constant> </entry>	2014	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM</constant> </entry>
2015	<entry>boolean</entry>	2015	<entry>boolean</entry>
2016	</row>	2016	</row>
2017	<row><entry spanname="descr">Enable 8X8 transform for H264. Applicable to the H264 encoder.</entry>	2017	<row><entry spanname="descr">Enable 8X8 transform for H264. Applicable to the H264 encoder.</entry>
2018	</row>	2018	</row>
2019		2019
2020	<row><entry></entry></row>	2020	<row><entry></entry></row>
2021	<row>	2021	<row>
2022	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB</constant> </entry>	2022	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB</constant> </entry>
2023	<entry>integer</entry>	2023	<entry>integer</entry>
2024	</row>	2024	</row>
2025	<row><entry spanname="descr">Cyclic intra macroblock refresh. This is the number of continuous macroblocks	2025	<row><entry spanname="descr">Cyclic intra macroblock refresh. This is the number of continuous macroblocks
2026	refreshed every frame. Each frame a succesive set of macroblocks is refreshed until the cycle completes and starts from the	2026	refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from the
2027	top of the frame. Applicable to H264, H263 and MPEG4 encoder.</entry>	2027	top of the frame. Applicable to H264, H263 and MPEG4 encoder.</entry>
2028	</row>	2028	</row>
2029		2029
2030	<row><entry></entry></row>	2030	<row><entry></entry></row>
2031	<row>	2031	<row>
2032	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE</constant> </entry>	2032	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE</constant> </entry>
2033	<entry>boolean</entry>	2033	<entry>boolean</entry>
2034	</row>	2034	</row>
2035	<row><entry spanname="descr">Frame level rate control enable.	2035	<row><entry spanname="descr">Frame level rate control enable.
2036	If this control is disabled then the quantization parameter for each frame type is constant and set with appropriate controls	2036	If this control is disabled then the quantization parameter for each frame type is constant and set with appropriate controls
2037	(e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>).	2037	(e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant>).
2038	If frame rate control is enabled then quantization parameter is adjusted to meet the chosen bitrate. Minimum and maximum value	2038	If frame rate control is enabled then quantization parameter is adjusted to meet the chosen bitrate. Minimum and maximum value
2039	for the quantization parameter can be set with appropriate controls (e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>).	2039	for the quantization parameter can be set with appropriate controls (e.g. <constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant>).
2040	Applicable to encoders.</entry>	2040	Applicable to encoders.</entry>
2041	</row>	2041	</row>
2042		2042
2043	<row><entry></entry></row>	2043	<row><entry></entry></row>
2044	<row>	2044	<row>
2045	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant> </entry>	2045	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant> </entry>
2046	<entry>boolean</entry>	2046	<entry>boolean</entry>
2047	</row>	2047	</row>
2048	<row><entry spanname="descr">Macroblock level rate control enable.	2048	<row><entry spanname="descr">Macroblock level rate control enable.
2049	Applicable to the MPEG4 and H264 encoders.</entry>	2049	Applicable to the MPEG4 and H264 encoders.</entry>
2050	</row>	2050	</row>
2051		2051
2052	<row><entry></entry></row>	2052	<row><entry></entry></row>
2053	<row>	2053	<row>
2054	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_QPEL</constant> </entry>	2054	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_QPEL</constant> </entry>
2055	<entry>boolean</entry>	2055	<entry>boolean</entry>
2056	</row>	2056	</row>
2057	<row><entry spanname="descr">Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 encoder.</entry>	2057	<row><entry spanname="descr">Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4 encoder.</entry>
2058	</row>	2058	</row>
2059		2059
2060	<row><entry></entry></row>	2060	<row><entry></entry></row>
2061	<row>	2061	<row>
2062	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant> </entry>	2062	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP</constant> </entry>
2063	<entry>integer</entry>	2063	<entry>integer</entry>
2064	</row>	2064	</row>
2065	<row><entry spanname="descr">Quantization parameter for an I frame for H263. Valid range: from 1 to 31.</entry>	2065	<row><entry spanname="descr">Quantization parameter for an I frame for H263. Valid range: from 1 to 31.</entry>
2066	</row>	2066	</row>
2067		2067
2068	<row><entry></entry></row>	2068	<row><entry></entry></row>
2069	<row>	2069	<row>
2070	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant> </entry>	2070	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MIN_QP</constant> </entry>
2071	<entry>integer</entry>	2071	<entry>integer</entry>
2072	</row>	2072	</row>
2073	<row><entry spanname="descr">Minimum quantization parameter for H263. Valid range: from 1 to 31.</entry>	2073	<row><entry spanname="descr">Minimum quantization parameter for H263. Valid range: from 1 to 31.</entry>
2074	</row>	2074	</row>
2075		2075
2076	<row><entry></entry></row>	2076	<row><entry></entry></row>
2077	<row>	2077	<row>
2078	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MAX_QP</constant> </entry>	2078	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_MAX_QP</constant> </entry>
2079	<entry>integer</entry>	2079	<entry>integer</entry>
2080	</row>	2080	</row>
2081	<row><entry spanname="descr">Maximum quantization parameter for H263. Valid range: from 1 to 31.</entry>	2081	<row><entry spanname="descr">Maximum quantization parameter for H263. Valid range: from 1 to 31.</entry>
2082	</row>	2082	</row>
2083		2083
2084	<row><entry></entry></row>	2084	<row><entry></entry></row>
2085	<row>	2085	<row>
2086	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP</constant> </entry>	2086	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP</constant> </entry>
2087	<entry>integer</entry>	2087	<entry>integer</entry>
2088	</row>	2088	</row>
2089	<row><entry spanname="descr">Quantization parameter for an P frame for H263. Valid range: from 1 to 31.</entry>	2089	<row><entry spanname="descr">Quantization parameter for an P frame for H263. Valid range: from 1 to 31.</entry>
2090	</row>	2090	</row>
2091		2091
2092	<row><entry></entry></row>	2092	<row><entry></entry></row>
2093	<row>	2093	<row>
2094	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP</constant> </entry>	2094	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP</constant> </entry>
2095	<entry>integer</entry>	2095	<entry>integer</entry>
2096	</row>	2096	</row>
2097	<row><entry spanname="descr">Quantization parameter for an B frame for H263. Valid range: from 1 to 31.</entry>	2097	<row><entry spanname="descr">Quantization parameter for an B frame for H263. Valid range: from 1 to 31.</entry>
2098	</row>	2098	</row>
2099		2099
2100	<row><entry></entry></row>	2100	<row><entry></entry></row>
2101	<row>	2101	<row>
2102	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP</constant> </entry>	2102	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP</constant> </entry>
2103	<entry>integer</entry>	2103	<entry>integer</entry>
2104	</row>	2104	</row>
2105	<row><entry spanname="descr">Quantization parameter for an I frame for H264. Valid range: from 0 to 51.</entry>	2105	<row><entry spanname="descr">Quantization parameter for an I frame for H264. Valid range: from 0 to 51.</entry>
2106	</row>	2106	</row>
2107		2107
2108	<row><entry></entry></row>	2108	<row><entry></entry></row>
2109	<row>	2109	<row>
2110	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MIN_QP</constant> </entry>	2110	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MIN_QP</constant> </entry>
2111	<entry>integer</entry>	2111	<entry>integer</entry>
2112	</row>	2112	</row>
2113	<row><entry spanname="descr">Minimum quantization parameter for H264. Valid range: from 0 to 51.</entry>	2113	<row><entry spanname="descr">Minimum quantization parameter for H264. Valid range: from 0 to 51.</entry>
2114	</row>	2114	</row>
2115		2115
2116	<row><entry></entry></row>	2116	<row><entry></entry></row>
2117	<row>	2117	<row>
2118	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MAX_QP</constant> </entry>	2118	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_MAX_QP</constant> </entry>
2119	<entry>integer</entry>	2119	<entry>integer</entry>
2120	</row>	2120	</row>
2121	<row><entry spanname="descr">Maximum quantization parameter for H264. Valid range: from 0 to 51.</entry>	2121	<row><entry spanname="descr">Maximum quantization parameter for H264. Valid range: from 0 to 51.</entry>
2122	</row>	2122	</row>
2123		2123
2124	<row><entry></entry></row>	2124	<row><entry></entry></row>
2125	<row>	2125	<row>
2126	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP</constant> </entry>	2126	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP</constant> </entry>
2127	<entry>integer</entry>	2127	<entry>integer</entry>
2128	</row>	2128	</row>
2129	<row><entry spanname="descr">Quantization parameter for an P frame for H264. Valid range: from 0 to 51.</entry>	2129	<row><entry spanname="descr">Quantization parameter for an P frame for H264. Valid range: from 0 to 51.</entry>
2130	</row>	2130	</row>
2131		2131
2132	<row><entry></entry></row>	2132	<row><entry></entry></row>
2133	<row>	2133	<row>
2134	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP</constant> </entry>	2134	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP</constant> </entry>
2135	<entry>integer</entry>	2135	<entry>integer</entry>
2136	</row>	2136	</row>
2137	<row><entry spanname="descr">Quantization parameter for an B frame for H264. Valid range: from 0 to 51.</entry>	2137	<row><entry spanname="descr">Quantization parameter for an B frame for H264. Valid range: from 0 to 51.</entry>
2138	</row>	2138	</row>
2139		2139
2140	<row><entry></entry></row>	2140	<row><entry></entry></row>
2141	<row>	2141	<row>
2142	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP</constant> </entry>	2142	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP</constant> </entry>
2143	<entry>integer</entry>	2143	<entry>integer</entry>
2144	</row>	2144	</row>
2145	<row><entry spanname="descr">Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31.</entry>	2145	<row><entry spanname="descr">Quantization parameter for an I frame for MPEG4. Valid range: from 1 to 31.</entry>
2146	</row>	2146	</row>
2147		2147
2148	<row><entry></entry></row>	2148	<row><entry></entry></row>
2149	<row>	2149	<row>
2150	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP</constant> </entry>	2150	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP</constant> </entry>
2151	<entry>integer</entry>	2151	<entry>integer</entry>
2152	</row>	2152	</row>
2153	<row><entry spanname="descr">Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>	2153	<row><entry spanname="descr">Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>
2154	</row>	2154	</row>
2155		2155
2156	<row><entry></entry></row>	2156	<row><entry></entry></row>
2157	<row>	2157	<row>
2158	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP</constant> </entry>	2158	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP</constant> </entry>
2159	<entry>integer</entry>	2159	<entry>integer</entry>
2160	</row>	2160	</row>
2161	<row><entry spanname="descr">Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>	2161	<row><entry spanname="descr">Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.</entry>
2162	</row>	2162	</row>
2163		2163
2164	<row><entry></entry></row>	2164	<row><entry></entry></row>
2165	<row>	2165	<row>
2166	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP</constant> </entry>	2166	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP</constant> </entry>
2167	<entry>integer</entry>	2167	<entry>integer</entry>
2168	</row>	2168	</row>
2169	<row><entry spanname="descr">Quantization parameter for an P frame for MPEG4. Valid range: from 1 to 31.</entry>	2169	<row><entry spanname="descr">Quantization parameter for an P frame for MPEG4. Valid range: from 1 to 31.</entry>
2170	</row>	2170	</row>
2171		2171
2172	<row><entry></entry></row>	2172	<row><entry></entry></row>
2173	<row>	2173	<row>
2174	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP</constant> </entry>	2174	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP</constant> </entry>
2175	<entry>integer</entry>	2175	<entry>integer</entry>
2176	</row>	2176	</row>
2177	<row><entry spanname="descr">Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31.</entry>	2177	<row><entry spanname="descr">Quantization parameter for an B frame for MPEG4. Valid range: from 1 to 31.</entry>
2178	</row>	2178	</row>
2179		2179
2180	<row><entry></entry></row>	2180	<row><entry></entry></row>
2181	<row>	2181	<row>
2182	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_SIZE</constant> </entry>	2182	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_SIZE</constant> </entry>
2183	<entry>integer</entry>	2183	<entry>integer</entry>
2184	</row>	2184	</row>
2185	<row><entry spanname="descr">The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip.	2185	<row><entry spanname="descr">The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip.
2186	The VBV is defined in the standard as a mean to verify that the produced stream will be succesfully decoded.	2186	The VBV is defined in the standard as a mean to verify that the produced stream will be successfully decoded.
2187	The standard describes it as "Part of a hypothetical decoder that is conceptually connected to the	2187	The standard describes it as "Part of a hypothetical decoder that is conceptually connected to the
2188	output of the encoder. Its purpose is to provide a constraint on the variability of the data rate that an	2188	output of the encoder. Its purpose is to provide a constraint on the variability of the data rate that an
2189	encoder or editing process may produce.".	2189	encoder or editing process may produce.".
2190	Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry>	2190	Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry>
2191	</row>	2191	</row>
2192		2192
2193	<row><entry></entry></row>	2193	<row><entry></entry></row>
2194	<row>	2194	<row>
2195	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant> </entry>	2195	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant> </entry>
2196	<entry>integer</entry>	2196	<entry>integer</entry>
2197	</row>	2197	</row>
2198	<row><entry spanname="descr">The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip.	2198	<row><entry spanname="descr">The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip.
2199	The CPB is defined in the H264 standard as a mean to verify that the produced stream will be succesfully decoded.	2199	The CPB is defined in the H264 standard as a mean to verify that the produced stream will be successfully decoded.
2200	Applicable to the H264 encoder.</entry>	2200	Applicable to the H264 encoder.</entry>
2201	</row>	2201	</row>
2202		2202
2203	<row><entry></entry></row>	2203	<row><entry></entry></row>
2204	<row>	2204	<row>
2205	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_PERIOD</constant> </entry>	2205	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_I_PERIOD</constant> </entry>
2206	<entry>integer</entry>	2206	<entry>integer</entry>
2207	</row>	2207	</row>
2208	<row><entry spanname="descr">Period between I-frames in the open GOP for H264. In case of an open GOP	2208	<row><entry spanname="descr">Period between I-frames in the open GOP for H264. In case of an open GOP
2209	this is the period between two I-frames. The period between IDR (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE control.	2209	this is the period between two I-frames. The period between IDR (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE control.
2210	An IDR frame, which stands for Instantaneous Decoding Refresh is an I-frame after which no prior frames are	2210	An IDR frame, which stands for Instantaneous Decoding Refresh is an I-frame after which no prior frames are
2211	referenced. This means that a stream can be restarted from an IDR frame without the need to store or decode any	2211	referenced. This means that a stream can be restarted from an IDR frame without the need to store or decode any
2212	previous frames. Applicable to the H264 encoder.</entry>	2212	previous frames. Applicable to the H264 encoder.</entry>
2213	</row>	2213	</row>
2214		2214
2215	<row><entry></entry></row>	2215	<row><entry></entry></row>
2216	<row id="v4l2-mpeg-video-header-mode">	2216	<row id="v4l2-mpeg-video-header-mode">
2217	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_HEADER_MODE</constant> </entry>	2217	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_HEADER_MODE</constant> </entry>
2218	<entry>enum v4l2_mpeg_video_header_mode</entry>	2218	<entry>enum v4l2_mpeg_video_header_mode</entry>
2219	</row>	2219	</row>
2220	<row><entry spanname="descr">Determines whether the header is returned as the first buffer or is	2220	<row><entry spanname="descr">Determines whether the header is returned as the first buffer or is
2221	it returned together with the first frame. Applicable to encoders.	2221	it returned together with the first frame. Applicable to encoders.
2222	Possible values are:</entry>	2222	Possible values are:</entry>
2223	</row>	2223	</row>
2224	<row>	2224	<row>
2225	<entrytbl spanname="descr" cols="2">	2225	<entrytbl spanname="descr" cols="2">
2226	<tbody valign="top">	2226	<tbody valign="top">
2227	<row>	2227	<row>
2228	<entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE</constant> </entry>	2228	<entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE</constant> </entry>
2229	<entry>The stream header is returned separately in the first buffer.</entry>	2229	<entry>The stream header is returned separately in the first buffer.</entry>
2230	</row>	2230	</row>
2231	<row>	2231	<row>
2232	<entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME</constant> </entry>	2232	<entry><constant>V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME</constant> </entry>
2233	<entry>The stream header is returned together with the first encoded frame.</entry>	2233	<entry>The stream header is returned together with the first encoded frame.</entry>
2234	</row>	2234	</row>
2235	</tbody>	2235	</tbody>
2236	</entrytbl>	2236	</entrytbl>
2237	</row>	2237	</row>
2238	<row><entry></entry></row>	2238	<row><entry></entry></row>
2239	<row>	2239	<row>
2240	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER</constant> </entry>	2240	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER</constant> </entry>
2241	<entry>boolean</entry>	2241	<entry>boolean</entry>
2242	</row><row><entry spanname="descr">Enabled the deblocking post processing filter for MPEG4 decoder.	2242	</row><row><entry spanname="descr">Enabled the deblocking post processing filter for MPEG4 decoder.
2243	Applicable to the MPEG4 decoder.</entry>	2243	Applicable to the MPEG4 decoder.</entry>
2244	</row>	2244	</row>
2245	<row><entry></entry></row>	2245	<row><entry></entry></row>
2246	<row>	2246	<row>
2247	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES</constant> </entry>	2247	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES</constant> </entry>
2248	<entry>integer</entry>	2248	<entry>integer</entry>
2249	</row><row><entry spanname="descr">vop_time_increment_resolution value for MPEG4. Applicable to the MPEG4 encoder.</entry>	2249	</row><row><entry spanname="descr">vop_time_increment_resolution value for MPEG4. Applicable to the MPEG4 encoder.</entry>
2250	</row>	2250	</row>
2251	<row><entry></entry></row>	2251	<row><entry></entry></row>
2252	<row>	2252	<row>
2253	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC</constant> </entry>	2253	<entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC</constant> </entry>
2254	<entry>integer</entry>	2254	<entry>integer</entry>
2255	</row><row><entry spanname="descr">vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder.</entry>	2255	</row><row><entry spanname="descr">vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder.</entry>
2256	</row>	2256	</row>
2257		2257
2258	</tbody>	2258	</tbody>
2259	</tgroup>	2259	</tgroup>
2260	</table>	2260	</table>
2261	</section>	2261	</section>
2262		2262
2263	<section>	2263	<section>
2264	<title>MFC 5.1 MPEG Controls</title>	2264	<title>MFC 5.1 MPEG Controls</title>
2265		2265
2266	<para>The following MPEG class controls deal with MPEG	2266	<para>The following MPEG class controls deal with MPEG
2267	decoding and encoding settings that are specific to the Multi Format Codec 5.1 device present	2267	decoding and encoding settings that are specific to the Multi Format Codec 5.1 device present
2268	in the S5P family of SoCs by Samsung.	2268	in the S5P family of SoCs by Samsung.
2269	</para>	2269	</para>
2270		2270
2271	<table pgwide="1" frame="none" id="mfc51-control-id">	2271	<table pgwide="1" frame="none" id="mfc51-control-id">
2272	<title>MFC 5.1 Control IDs</title>	2272	<title>MFC 5.1 Control IDs</title>
2273	<tgroup cols="4">	2273	<tgroup cols="4">
2274	<colspec colname="c1" colwidth="1*" />	2274	<colspec colname="c1" colwidth="1*" />
2275	<colspec colname="c2" colwidth="6*" />	2275	<colspec colname="c2" colwidth="6*" />
2276	<colspec colname="c3" colwidth="2*" />	2276	<colspec colname="c3" colwidth="2*" />
2277	<colspec colname="c4" colwidth="6*" />	2277	<colspec colname="c4" colwidth="6*" />
2278	<spanspec namest="c1" nameend="c2" spanname="id" />	2278	<spanspec namest="c1" nameend="c2" spanname="id" />
2279	<spanspec namest="c2" nameend="c4" spanname="descr" />	2279	<spanspec namest="c2" nameend="c4" spanname="descr" />
2280	<thead>	2280	<thead>
2281	<row>	2281	<row>
2282	<entry spanname="id" align="left">ID</entry>	2282	<entry spanname="id" align="left">ID</entry>
2283	<entry align="left">Type</entry>	2283	<entry align="left">Type</entry>
2284	</row><row><entry spanname="descr" align="left">Description</entry>	2284	</row><row><entry spanname="descr" align="left">Description</entry>
2285	</row>	2285	</row>
2286	</thead>	2286	</thead>
2287	<tbody valign="top">	2287	<tbody valign="top">
2288	<row><entry></entry></row>	2288	<row><entry></entry></row>
2289	<row>	2289	<row>
2290	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE</constant> </entry>	2290	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE</constant> </entry>
2291	<entry>integer</entry>	2291	<entry>integer</entry>
2292	</row><row><entry spanname="descr">If the display delay is enabled then the decoder has to return a	2292	</row><row><entry spanname="descr">If the display delay is enabled then the decoder has to return a
2293	CAPTURE buffer after processing a certain number of OUTPUT buffers. If this number is low, then it may result in	2293	CAPTURE buffer after processing a certain number of OUTPUT buffers. If this number is low, then it may result in
2294	buffers not being dequeued in display order. In addition hardware may still use those buffers as reference, thus	2294	buffers not being dequeued in display order. In addition hardware may still use those buffers as reference, thus
2295	application should not write to those buffers. This feature can be used for example for generating thumbnails of videos.	2295	application should not write to those buffers. This feature can be used for example for generating thumbnails of videos.
2296	Applicable to the H264 decoder.	2296	Applicable to the H264 decoder.
2297	</entry>	2297	</entry>
2298	</row>	2298	</row>
2299	<row><entry></entry></row>	2299	<row><entry></entry></row>
2300	<row>	2300	<row>
2301	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant> </entry>	2301	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY</constant> </entry>
2302	<entry>integer</entry>	2302	<entry>integer</entry>
2303	</row><row><entry spanname="descr">Display delay value for H264 decoder.	2303	</row><row><entry spanname="descr">Display delay value for H264 decoder.
2304	The decoder is forced to return a decoded frame after the set 'display delay' number of frames. If this number is	2304	The decoder is forced to return a decoded frame after the set 'display delay' number of frames. If this number is
2305	low it may result in frames returned out of dispaly order, in addition the hardware may still be using the returned buffer	2305	low it may result in frames returned out of dispaly order, in addition the hardware may still be using the returned buffer
2306	as a reference picture for subsequent frames.	2306	as a reference picture for subsequent frames.
2307	</entry>	2307	</entry>
2308	</row>	2308	</row>
2309	<row><entry></entry></row>	2309	<row><entry></entry></row>
2310	<row>	2310	<row>
2311	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P</constant> </entry>	2311	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P</constant> </entry>
2312	<entry>integer</entry>	2312	<entry>integer</entry>
2313	</row><row><entry spanname="descr">The number of reference pictures used for encoding a P picture.	2313	</row><row><entry spanname="descr">The number of reference pictures used for encoding a P picture.
2314	Applicable to the H264 encoder.</entry>	2314	Applicable to the H264 encoder.</entry>
2315	</row>	2315	</row>
2316	<row><entry></entry></row>	2316	<row><entry></entry></row>
2317	<row>	2317	<row>
2318	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING</constant> </entry>	2318	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING</constant> </entry>
2319	<entry>boolean</entry>	2319	<entry>boolean</entry>
2320	</row><row><entry spanname="descr">Padding enable in the encoder - use a color instead of repeating border pixels.	2320	</row><row><entry spanname="descr">Padding enable in the encoder - use a color instead of repeating border pixels.
2321	Applicable to encoders.</entry>	2321	Applicable to encoders.</entry>
2322	</row>	2322	</row>
2323	<row><entry></entry></row>	2323	<row><entry></entry></row>
2324	<row>	2324	<row>
2325	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV</constant> </entry>	2325	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV</constant> </entry>
2326	<entry>integer</entry>	2326	<entry>integer</entry>
2327	</row><row><entry spanname="descr">Padding color in the encoder. Applicable to encoders. The supplied 32-bit integer is interpreted as follows (bit	2327	</row><row><entry spanname="descr">Padding color in the encoder. Applicable to encoders. The supplied 32-bit integer is interpreted as follows (bit
2328	0 = least significant bit):</entry>	2328	0 = least significant bit):</entry>
2329	</row>	2329	</row>
2330	<row>	2330	<row>
2331	<entrytbl spanname="descr" cols="2">	2331	<entrytbl spanname="descr" cols="2">
2332	<tbody valign="top">	2332	<tbody valign="top">
2333	<row>	2333	<row>
2334	<entry>Bit 0:7</entry>	2334	<entry>Bit 0:7</entry>
2335	<entry>V chrominance information</entry>	2335	<entry>V chrominance information</entry>
2336	</row>	2336	</row>
2337	<row>	2337	<row>
2338	<entry>Bit 8:15</entry>	2338	<entry>Bit 8:15</entry>
2339	<entry>U chrominance information</entry>	2339	<entry>U chrominance information</entry>
2340	</row>	2340	</row>
2341	<row>	2341	<row>
2342	<entry>Bit 16:23</entry>	2342	<entry>Bit 16:23</entry>
2343	<entry>Y luminance information</entry>	2343	<entry>Y luminance information</entry>
2344	</row>	2344	</row>
2345	<row>	2345	<row>
2346	<entry>Bit 24:31</entry>	2346	<entry>Bit 24:31</entry>
2347	<entry>Must be zero.</entry>	2347	<entry>Must be zero.</entry>
2348	</row>	2348	</row>
2349	</tbody>	2349	</tbody>
2350	</entrytbl>	2350	</entrytbl>
2351	</row>	2351	</row>
2352	<row><entry></entry></row>	2352	<row><entry></entry></row>
2353	<row>	2353	<row>
2354	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF</constant> </entry>	2354	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF</constant> </entry>
2355	<entry>integer</entry>	2355	<entry>integer</entry>
2356	</row><row><entry spanname="descr">Reaction coefficient for MFC rate control. Applicable to encoders.	2356	</row><row><entry spanname="descr">Reaction coefficient for MFC rate control. Applicable to encoders.
2357	<para>Note 1: Valid only when the frame level RC is enabled.</para>	2357	<para>Note 1: Valid only when the frame level RC is enabled.</para>
2358	<para>Note 2: For tight CBR, this field must be small (ex. 2 ~ 10).	2358	<para>Note 2: For tight CBR, this field must be small (ex. 2 ~ 10).
2359	For VBR, this field must be large (ex. 100 ~ 1000).</para>	2359	For VBR, this field must be large (ex. 100 ~ 1000).</para>
2360	<para>Note 3: It is not recommended to use the greater number than FRAME_RATE * (10^9 / BIT_RATE).</para>	2360	<para>Note 3: It is not recommended to use the greater number than FRAME_RATE * (10^9 / BIT_RATE).</para>
2361	</entry>	2361	</entry>
2362	</row>	2362	</row>
2363	<row><entry></entry></row>	2363	<row><entry></entry></row>
2364	<row>	2364	<row>
2365	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK</constant> </entry>	2365	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK</constant> </entry>
2366	<entry>boolean</entry>	2366	<entry>boolean</entry>
2367	</row><row><entry spanname="descr">Adaptive rate control for dark region.	2367	</row><row><entry spanname="descr">Adaptive rate control for dark region.
2368	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).	2368	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
2369	Applicable to the H264 encoder.</entry>	2369	Applicable to the H264 encoder.</entry>
2370	</row>	2370	</row>
2371	<row><entry></entry></row>	2371	<row><entry></entry></row>
2372	<row>	2372	<row>
2373	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH</constant> </entry>	2373	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH</constant> </entry>
2374	<entry>boolean</entry>	2374	<entry>boolean</entry>
2375	</row><row><entry spanname="descr">Adaptive rate control for smooth region.	2375	</row><row><entry spanname="descr">Adaptive rate control for smooth region.
2376	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).	2376	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
2377	Applicable to the H264 encoder.</entry>	2377	Applicable to the H264 encoder.</entry>
2378	</row>	2378	</row>
2379	<row><entry></entry></row>	2379	<row><entry></entry></row>
2380	<row>	2380	<row>
2381	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC</constant> </entry>	2381	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC</constant> </entry>
2382	<entry>boolean</entry>	2382	<entry>boolean</entry>
2383	</row><row><entry spanname="descr">Adaptive rate control for static region.	2383	</row><row><entry spanname="descr">Adaptive rate control for static region.
2384	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).	2384	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
2385	Applicable to the H264 encoder.</entry>	2385	Applicable to the H264 encoder.</entry>
2386	</row>	2386	</row>
2387	<row><entry></entry></row>	2387	<row><entry></entry></row>
2388	<row>	2388	<row>
2389	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY</constant> </entry>	2389	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY</constant> </entry>
2390	<entry>boolean</entry>	2390	<entry>boolean</entry>
2391	</row><row><entry spanname="descr">Adaptive rate control for activity region.	2391	</row><row><entry spanname="descr">Adaptive rate control for activity region.
2392	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).	2392	Valid only when H.264 and macroblock level RC is enabled (<constant>V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE</constant>).
2393	Applicable to the H264 encoder.</entry>	2393	Applicable to the H264 encoder.</entry>
2394	</row>	2394	</row>
2395	<row><entry></entry></row>	2395	<row><entry></entry></row>
2396	<row id="v4l2-mpeg-mfc51-video-frame-skip-mode">	2396	<row id="v4l2-mpeg-mfc51-video-frame-skip-mode">
2397	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE</constant> </entry>	2397	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE</constant> </entry>
2398	<entry>enum v4l2_mpeg_mfc51_video_frame_skip_mode</entry>	2398	<entry>enum v4l2_mpeg_mfc51_video_frame_skip_mode</entry>
2399	</row>	2399	</row>
2400	<row><entry spanname="descr">	2400	<row><entry spanname="descr">
2401	Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then	2401	Indicates in what conditions the encoder should skip frames. If encoding a frame would cause the encoded stream to be larger then
2402	a chosen data limit then the frame will be skipped.	2402	a chosen data limit then the frame will be skipped.
2403	Possible values are:</entry>	2403	Possible values are:</entry>
2404	</row>	2404	</row>
2405	<row>	2405	<row>
2406	<entrytbl spanname="descr" cols="2">	2406	<entrytbl spanname="descr" cols="2">
2407	<tbody valign="top">	2407	<tbody valign="top">
2408	<row>	2408	<row>
2409	<entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED</constant> </entry>	2409	<entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED</constant> </entry>
2410	<entry>Frame skip mode is disabled.</entry>	2410	<entry>Frame skip mode is disabled.</entry>
2411	</row>	2411	</row>
2412	<row>	2412	<row>
2413	<entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT</constant> </entry>	2413	<entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT</constant> </entry>
2414	<entry>Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard.</entry>	2414	<entry>Frame skip mode enabled and buffer limit is set by the chosen level and is defined by the standard.</entry>
2415	</row>	2415	</row>
2416	<row>	2416	<row>
2417	<entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT</constant> </entry>	2417	<entry><constant>V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT</constant> </entry>
2418	<entry>Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control.</entry>	2418	<entry>Frame skip mode enabled and buffer limit is set by the VBV (MPEG1/2/4) or CPB (H264) buffer size control.</entry>
2419	</row>	2419	</row>
2420	</tbody>	2420	</tbody>
2421	</entrytbl>	2421	</entrytbl>
2422	</row>	2422	</row>
2423	<row><entry></entry></row>	2423	<row><entry></entry></row>
2424	<row>	2424	<row>
2425	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT</constant> </entry>	2425	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT</constant> </entry>
2426	<entry>integer</entry>	2426	<entry>integer</entry>
2427	</row><row><entry spanname="descr">Enable rate-control with fixed target bit.	2427	</row><row><entry spanname="descr">Enable rate-control with fixed target bit.
2428	If this setting is enabled, then the rate control logic of the encoder will calculate the average bitrate	2428	If this setting is enabled, then the rate control logic of the encoder will calculate the average bitrate
2429	for a GOP and keep it below or equal the set bitrate target. Otherwise the rate control logic calculates the	2429	for a GOP and keep it below or equal the set bitrate target. Otherwise the rate control logic calculates the
2430	overall average bitrate for the stream and keeps it below or equal to the set bitrate. In the first case	2430	overall average bitrate for the stream and keeps it below or equal to the set bitrate. In the first case
2431	the average bitrate for the whole stream will be smaller then the set bitrate. This is caused because the	2431	the average bitrate for the whole stream will be smaller then the set bitrate. This is caused because the
2432	average is calculated for smaller number of frames, on the other hand enabling this setting will ensure that	2432	average is calculated for smaller number of frames, on the other hand enabling this setting will ensure that
2433	the stream will meet tight bandwidth contraints. Applicable to encoders.	2433	the stream will meet tight bandwidth contraints. Applicable to encoders.
2434	</entry>	2434	</entry>
2435	</row>	2435	</row>
2436	<row><entry></entry></row>	2436	<row><entry></entry></row>
2437	<row id="v4l2-mpeg-mfc51-video-force-frame-type">	2437	<row id="v4l2-mpeg-mfc51-video-force-frame-type">
2438	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE</constant> </entry>	2438	<entry spanname="id"><constant>V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE</constant> </entry>
2439	<entry>enum v4l2_mpeg_mfc51_video_force_frame_type</entry>	2439	<entry>enum v4l2_mpeg_mfc51_video_force_frame_type</entry>
2440	</row>	2440	</row>
2441	<row><entry spanname="descr">Force a frame type for the next queued buffer. Applicable to encoders.	2441	<row><entry spanname="descr">Force a frame type for the next queued buffer. Applicable to encoders.
2442	Possible values are:</entry>	2442	Possible values are:</entry>
2443	</row>	2443	</row>
2444	<row>	2444	<row>
2445	<entrytbl spanname="descr" cols="2">	2445	<entrytbl spanname="descr" cols="2">
2446	<tbody valign="top">	2446	<tbody valign="top">
2447	<row>	2447	<row>
2448	<entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED</constant> </entry>	2448	<entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED</constant> </entry>
2449	<entry>Forcing a specific frame type disabled.</entry>	2449	<entry>Forcing a specific frame type disabled.</entry>
2450	</row>	2450	</row>
2451	<row>	2451	<row>
2452	<entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME</constant> </entry>	2452	<entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME</constant> </entry>
2453	<entry>Force an I-frame.</entry>	2453	<entry>Force an I-frame.</entry>
2454	</row>	2454	</row>
2455	<row>	2455	<row>
2456	<entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED</constant> </entry>	2456	<entry><constant>V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED</constant> </entry>
2457	<entry>Force a non-coded frame.</entry>	2457	<entry>Force a non-coded frame.</entry>
2458	</row>	2458	</row>
2459	</tbody>	2459	</tbody>
2460	</entrytbl>	2460	</entrytbl>
2461	</row>	2461	</row>
2462	</tbody>	2462	</tbody>
2463	</tgroup>	2463	</tgroup>
2464	</table>	2464	</table>
2465	</section>	2465	</section>
2466		2466
2467	<section>	2467	<section>
2468	<title>CX2341x MPEG Controls</title>	2468	<title>CX2341x MPEG Controls</title>
2469		2469
2470	<para>The following MPEG class controls deal with MPEG	2470	<para>The following MPEG class controls deal with MPEG
2471	encoding settings that are specific to the Conexant CX23415 and	2471	encoding settings that are specific to the Conexant CX23415 and
2472	CX23416 MPEG encoding chips.</para>	2472	CX23416 MPEG encoding chips.</para>
2473		2473
2474	<table pgwide="1" frame="none" id="cx2341x-control-id">	2474	<table pgwide="1" frame="none" id="cx2341x-control-id">
2475	<title>CX2341x Control IDs</title>	2475	<title>CX2341x Control IDs</title>
2476	<tgroup cols="4">	2476	<tgroup cols="4">
2477	<colspec colname="c1" colwidth="1*" />	2477	<colspec colname="c1" colwidth="1*" />
2478	<colspec colname="c2" colwidth="6*" />	2478	<colspec colname="c2" colwidth="6*" />
2479	<colspec colname="c3" colwidth="2*" />	2479	<colspec colname="c3" colwidth="2*" />
2480	<colspec colname="c4" colwidth="6*" />	2480	<colspec colname="c4" colwidth="6*" />
2481	<spanspec namest="c1" nameend="c2" spanname="id" />	2481	<spanspec namest="c1" nameend="c2" spanname="id" />
2482	<spanspec namest="c2" nameend="c4" spanname="descr" />	2482	<spanspec namest="c2" nameend="c4" spanname="descr" />
2483	<thead>	2483	<thead>
2484	<row>	2484	<row>
2485	<entry spanname="id" align="left">ID</entry>	2485	<entry spanname="id" align="left">ID</entry>
2486	<entry align="left">Type</entry>	2486	<entry align="left">Type</entry>
2487	</row><row><entry spanname="descr" align="left">Description</entry>	2487	</row><row><entry spanname="descr" align="left">Description</entry>
2488	</row>	2488	</row>
2489	</thead>	2489	</thead>
2490	<tbody valign="top">	2490	<tbody valign="top">
2491	<row><entry></entry></row>	2491	<row><entry></entry></row>
2492	<row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode">	2492	<row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode">
2493	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant> </entry>	2493	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant> </entry>
2494	<entry>enum v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>	2494	<entry>enum v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>
2495	</row><row><entry spanname="descr">Sets the Spatial	2495	</row><row><entry spanname="descr">Sets the Spatial
2496	Filter mode (default <constant>MANUAL</constant>). Possible values	2496	Filter mode (default <constant>MANUAL</constant>). Possible values
2497	are:</entry>	2497	are:</entry>
2498	</row>	2498	</row>
2499	<row>	2499	<row>
2500	<entrytbl spanname="descr" cols="2">	2500	<entrytbl spanname="descr" cols="2">
2501	<tbody valign="top">	2501	<tbody valign="top">
2502	<row>	2502	<row>
2503	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant> </entry>	2503	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant> </entry>
2504	<entry>Choose the filter manually</entry>	2504	<entry>Choose the filter manually</entry>
2505	</row>	2505	</row>
2506	<row>	2506	<row>
2507	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant> </entry>	2507	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant> </entry>
2508	<entry>Choose the filter automatically</entry>	2508	<entry>Choose the filter automatically</entry>
2509	</row>	2509	</row>
2510	</tbody>	2510	</tbody>
2511	</entrytbl>	2511	</entrytbl>
2512	</row>	2512	</row>
2513	<row><entry></entry></row>	2513	<row><entry></entry></row>
2514	<row>	2514	<row>
2515	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant> </entry>	2515	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant> </entry>
2516	<entry>integer (0-15)</entry>	2516	<entry>integer (0-15)</entry>
2517	</row><row><entry spanname="descr">The setting for the	2517	</row><row><entry spanname="descr">The setting for the
2518	Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry>	2518	Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry>
2519	</row>	2519	</row>
2520	<row><entry></entry></row>	2520	<row><entry></entry></row>
2521	<row id="luma-spatial-filter-type">	2521	<row id="luma-spatial-filter-type">
2522	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant> </entry>	2522	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant> </entry>
2523	<entry>enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>	2523	<entry>enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>
2524	</row><row><entry spanname="descr">Select the algorithm	2524	</row><row><entry spanname="descr">Select the algorithm
2525	to use for the Luma Spatial Filter (default	2525	to use for the Luma Spatial Filter (default
2526	<constant>1D_HOR</constant>). Possible values:</entry>	2526	<constant>1D_HOR</constant>). Possible values:</entry>
2527	</row>	2527	</row>
2528	<row>	2528	<row>
2529	<entrytbl spanname="descr" cols="2">	2529	<entrytbl spanname="descr" cols="2">
2530	<tbody valign="top">	2530	<tbody valign="top">
2531	<row>	2531	<row>
2532	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry>	2532	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry>
2533	<entry>No filter</entry>	2533	<entry>No filter</entry>
2534	</row>	2534	</row>
2535	<row>	2535	<row>
2536	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry>	2536	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry>
2537	<entry>One-dimensional horizontal</entry>	2537	<entry>One-dimensional horizontal</entry>
2538	</row>	2538	</row>
2539	<row>	2539	<row>
2540	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant> </entry>	2540	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant> </entry>
2541	<entry>One-dimensional vertical</entry>	2541	<entry>One-dimensional vertical</entry>
2542	</row>	2542	</row>
2543	<row>	2543	<row>
2544	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant> </entry>	2544	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant> </entry>
2545	<entry>Two-dimensional separable</entry>	2545	<entry>Two-dimensional separable</entry>
2546	</row>	2546	</row>
2547	<row>	2547	<row>
2548	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant> </entry>	2548	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant> </entry>
2549	<entry>Two-dimensional symmetrical	2549	<entry>Two-dimensional symmetrical
2550	non-separable</entry>	2550	non-separable</entry>
2551	</row>	2551	</row>
2552	</tbody>	2552	</tbody>
2553	</entrytbl>	2553	</entrytbl>
2554	</row>	2554	</row>
2555	<row><entry></entry></row>	2555	<row><entry></entry></row>
2556	<row id="chroma-spatial-filter-type">	2556	<row id="chroma-spatial-filter-type">
2557	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant> </entry>	2557	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant> </entry>
2558	<entry>enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>	2558	<entry>enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>
2559	</row><row><entry spanname="descr">Select the algorithm	2559	</row><row><entry spanname="descr">Select the algorithm
2560	for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).	2560	for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).
2561	Possible values are:</entry>	2561	Possible values are:</entry>
2562	</row>	2562	</row>
2563	<row>	2563	<row>
2564	<entrytbl spanname="descr" cols="2">	2564	<entrytbl spanname="descr" cols="2">
2565	<tbody valign="top">	2565	<tbody valign="top">
2566	<row>	2566	<row>
2567	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry>	2567	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant> </entry>
2568	<entry>No filter</entry>	2568	<entry>No filter</entry>
2569	</row>	2569	</row>
2570	<row>	2570	<row>
2571	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry>	2571	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant> </entry>
2572	<entry>One-dimensional horizontal</entry>	2572	<entry>One-dimensional horizontal</entry>
2573	</row>	2573	</row>
2574	</tbody>	2574	</tbody>
2575	</entrytbl>	2575	</entrytbl>
2576	</row>	2576	</row>
2577	<row><entry></entry></row>	2577	<row><entry></entry></row>
2578	<row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode">	2578	<row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode">
2579	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant> </entry>	2579	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant> </entry>
2580	<entry>enum v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>	2580	<entry>enum v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>
2581	</row><row><entry spanname="descr">Sets the Temporal	2581	</row><row><entry spanname="descr">Sets the Temporal
2582	Filter mode (default <constant>MANUAL</constant>). Possible values	2582	Filter mode (default <constant>MANUAL</constant>). Possible values
2583	are:</entry>	2583	are:</entry>
2584	</row>	2584	</row>
2585	<row>	2585	<row>
2586	<entrytbl spanname="descr" cols="2">	2586	<entrytbl spanname="descr" cols="2">
2587	<tbody valign="top">	2587	<tbody valign="top">
2588	<row>	2588	<row>
2589	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant> </entry>	2589	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant> </entry>
2590	<entry>Choose the filter manually</entry>	2590	<entry>Choose the filter manually</entry>
2591	</row>	2591	</row>
2592	<row>	2592	<row>
2593	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant> </entry>	2593	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant> </entry>
2594	<entry>Choose the filter automatically</entry>	2594	<entry>Choose the filter automatically</entry>
2595	</row>	2595	</row>
2596	</tbody>	2596	</tbody>
2597	</entrytbl>	2597	</entrytbl>
2598	</row>	2598	</row>
2599	<row><entry></entry></row>	2599	<row><entry></entry></row>
2600	<row>	2600	<row>
2601	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant> </entry>	2601	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant> </entry>
2602	<entry>integer (0-31)</entry>	2602	<entry>integer (0-31)</entry>
2603	</row><row><entry spanname="descr">The setting for the	2603	</row><row><entry spanname="descr">The setting for the
2604	Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale	2604	Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale
2605	capturing and 0 for scaled capturing.)</entry>	2605	capturing and 0 for scaled capturing.)</entry>
2606	</row>	2606	</row>
2607	<row><entry></entry></row>	2607	<row><entry></entry></row>
2608	<row id="v4l2-mpeg-cx2341x-video-median-filter-type">	2608	<row id="v4l2-mpeg-cx2341x-video-median-filter-type">
2609	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant> </entry>	2609	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant> </entry>
2610	<entry>enum v4l2_mpeg_cx2341x_video_median_filter_type</entry>	2610	<entry>enum v4l2_mpeg_cx2341x_video_median_filter_type</entry>
2611	</row><row><entry spanname="descr">Median Filter Type	2611	</row><row><entry spanname="descr">Median Filter Type
2612	(default <constant>OFF</constant>). Possible values are:</entry>	2612	(default <constant>OFF</constant>). Possible values are:</entry>
2613	</row>	2613	</row>
2614	<row>	2614	<row>
2615	<entrytbl spanname="descr" cols="2">	2615	<entrytbl spanname="descr" cols="2">
2616	<tbody valign="top">	2616	<tbody valign="top">
2617	<row>	2617	<row>
2618	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant> </entry>	2618	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant> </entry>
2619	<entry>No filter</entry>	2619	<entry>No filter</entry>
2620	</row>	2620	</row>
2621	<row>	2621	<row>
2622	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant> </entry>	2622	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant> </entry>
2623	<entry>Horizontal filter</entry>	2623	<entry>Horizontal filter</entry>
2624	</row>	2624	</row>
2625	<row>	2625	<row>
2626	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant> </entry>	2626	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant> </entry>
2627	<entry>Vertical filter</entry>	2627	<entry>Vertical filter</entry>
2628	</row>	2628	</row>
2629	<row>	2629	<row>
2630	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant> </entry>	2630	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant> </entry>
2631	<entry>Horizontal and vertical filter</entry>	2631	<entry>Horizontal and vertical filter</entry>
2632	</row>	2632	</row>
2633	<row>	2633	<row>
2634	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant> </entry>	2634	<entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant> </entry>
2635	<entry>Diagonal filter</entry>	2635	<entry>Diagonal filter</entry>
2636	</row>	2636	</row>
2637	</tbody>	2637	</tbody>
2638	</entrytbl>	2638	</entrytbl>
2639	</row>	2639	</row>
2640	<row><entry></entry></row>	2640	<row><entry></entry></row>
2641	<row>	2641	<row>
2642	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant> </entry>	2642	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant> </entry>
2643	<entry>integer (0-255)</entry>	2643	<entry>integer (0-255)</entry>
2644	</row><row><entry spanname="descr">Threshold above which	2644	</row><row><entry spanname="descr">Threshold above which
2645	the luminance median filter is enabled (default 0)</entry>	2645	the luminance median filter is enabled (default 0)</entry>
2646	</row>	2646	</row>
2647	<row><entry></entry></row>	2647	<row><entry></entry></row>
2648	<row>	2648	<row>
2649	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant> </entry>	2649	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant> </entry>
2650	<entry>integer (0-255)</entry>	2650	<entry>integer (0-255)</entry>
2651	</row><row><entry spanname="descr">Threshold below which	2651	</row><row><entry spanname="descr">Threshold below which
2652	the luminance median filter is enabled (default 255)</entry>	2652	the luminance median filter is enabled (default 255)</entry>
2653	</row>	2653	</row>
2654	<row><entry></entry></row>	2654	<row><entry></entry></row>
2655	<row>	2655	<row>
2656	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant> </entry>	2656	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant> </entry>
2657	<entry>integer (0-255)</entry>	2657	<entry>integer (0-255)</entry>
2658	</row><row><entry spanname="descr">Threshold above which	2658	</row><row><entry spanname="descr">Threshold above which
2659	the chroma median filter is enabled (default 0)</entry>	2659	the chroma median filter is enabled (default 0)</entry>
2660	</row>	2660	</row>
2661	<row><entry></entry></row>	2661	<row><entry></entry></row>
2662	<row>	2662	<row>
2663	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant> </entry>	2663	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant> </entry>
2664	<entry>integer (0-255)</entry>	2664	<entry>integer (0-255)</entry>
2665	</row><row><entry spanname="descr">Threshold below which	2665	</row><row><entry spanname="descr">Threshold below which
2666	the chroma median filter is enabled (default 255)</entry>	2666	the chroma median filter is enabled (default 255)</entry>
2667	</row>	2667	</row>
2668	<row><entry></entry></row>	2668	<row><entry></entry></row>
2669	<row>	2669	<row>
2670	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant> </entry>	2670	<entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant> </entry>
2671	<entry>boolean</entry>	2671	<entry>boolean</entry>
2672	</row>	2672	</row>
2673	<row><entry spanname="descr">The CX2341X MPEG encoder	2673	<row><entry spanname="descr">The CX2341X MPEG encoder
2674	can insert one empty MPEG-2 PES packet into the stream between every	2674	can insert one empty MPEG-2 PES packet into the stream between every
2675	four video frames. The packet size is 2048 bytes, including the	2675	four video frames. The packet size is 2048 bytes, including the
2676	packet_start_code_prefix and stream_id fields. The stream_id is 0xBF	2676	packet_start_code_prefix and stream_id fields. The stream_id is 0xBF
2677	(private stream 2). The payload consists of 0x00 bytes, to be filled	2677	(private stream 2). The payload consists of 0x00 bytes, to be filled
2678	in by the application. 0 = do not insert, 1 = insert packets.</entry>	2678	in by the application. 0 = do not insert, 1 = insert packets.</entry>
2679	</row>	2679	</row>
2680	</tbody>	2680	</tbody>
2681	</tgroup>	2681	</tgroup>
2682	</table>	2682	</table>
2683	</section>	2683	</section>
2684	</section>	2684	</section>
2685		2685
2686	<section id="camera-controls">	2686	<section id="camera-controls">
2687	<title>Camera Control Reference</title>	2687	<title>Camera Control Reference</title>
2688		2688
2689	<para>The Camera class includes controls for mechanical (or	2689	<para>The Camera class includes controls for mechanical (or
2690	equivalent digital) features of a device such as controllable lenses	2690	equivalent digital) features of a device such as controllable lenses
2691	or sensors.</para>	2691	or sensors.</para>
2692		2692
2693	<table pgwide="1" frame="none" id="camera-control-id">	2693	<table pgwide="1" frame="none" id="camera-control-id">
2694	<title>Camera Control IDs</title>	2694	<title>Camera Control IDs</title>
2695	<tgroup cols="4">	2695	<tgroup cols="4">
2696	<colspec colname="c1" colwidth="1*" />	2696	<colspec colname="c1" colwidth="1*" />
2697	<colspec colname="c2" colwidth="6*" />	2697	<colspec colname="c2" colwidth="6*" />
2698	<colspec colname="c3" colwidth="2*" />	2698	<colspec colname="c3" colwidth="2*" />
2699	<colspec colname="c4" colwidth="6*" />	2699	<colspec colname="c4" colwidth="6*" />
2700	<spanspec namest="c1" nameend="c2" spanname="id" />	2700	<spanspec namest="c1" nameend="c2" spanname="id" />
2701	<spanspec namest="c2" nameend="c4" spanname="descr" />	2701	<spanspec namest="c2" nameend="c4" spanname="descr" />
2702	<thead>	2702	<thead>
2703	<row>	2703	<row>
2704	<entry spanname="id" align="left">ID</entry>	2704	<entry spanname="id" align="left">ID</entry>
2705	<entry align="left">Type</entry>	2705	<entry align="left">Type</entry>
2706	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>	2706	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
2707	</row>	2707	</row>
2708	</thead>	2708	</thead>
2709	<tbody valign="top">	2709	<tbody valign="top">
2710	<row><entry></entry></row>	2710	<row><entry></entry></row>
2711	<row>	2711	<row>
2712	<entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant> </entry>	2712	<entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant> </entry>
2713	<entry>class</entry>	2713	<entry>class</entry>
2714	</row><row><entry spanname="descr">The Camera class	2714	</row><row><entry spanname="descr">The Camera class
2715	descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a	2715	descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
2716	description of this control class.</entry>	2716	description of this control class.</entry>
2717	</row>	2717	</row>
2718	<row><entry></entry></row>	2718	<row><entry></entry></row>
2719		2719
2720	<row id="v4l2-exposure-auto-type">	2720	<row id="v4l2-exposure-auto-type">
2721	<entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant> </entry>	2721	<entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant> </entry>
2722	<entry>enum v4l2_exposure_auto_type</entry>	2722	<entry>enum v4l2_exposure_auto_type</entry>
2723	</row><row><entry spanname="descr">Enables automatic	2723	</row><row><entry spanname="descr">Enables automatic
2724	adjustments of the exposure time and/or iris aperture. The effect of	2724	adjustments of the exposure time and/or iris aperture. The effect of
2725	manual changes of the exposure time or iris aperture while these	2725	manual changes of the exposure time or iris aperture while these
2726	features are enabled is undefined, drivers should ignore such	2726	features are enabled is undefined, drivers should ignore such
2727	requests. Possible values are:</entry>	2727	requests. Possible values are:</entry>
2728	</row>	2728	</row>
2729	<row>	2729	<row>
2730	<entrytbl spanname="descr" cols="2">	2730	<entrytbl spanname="descr" cols="2">
2731	<tbody valign="top">	2731	<tbody valign="top">
2732	<row>	2732	<row>
2733	<entry><constant>V4L2_EXPOSURE_AUTO</constant> </entry>	2733	<entry><constant>V4L2_EXPOSURE_AUTO</constant> </entry>
2734	<entry>Automatic exposure time, automatic iris	2734	<entry>Automatic exposure time, automatic iris
2735	aperture.</entry>	2735	aperture.</entry>
2736	</row>	2736	</row>
2737	<row>	2737	<row>
2738	<entry><constant>V4L2_EXPOSURE_MANUAL</constant> </entry>	2738	<entry><constant>V4L2_EXPOSURE_MANUAL</constant> </entry>
2739	<entry>Manual exposure time, manual iris.</entry>	2739	<entry>Manual exposure time, manual iris.</entry>
2740	</row>	2740	</row>
2741	<row>	2741	<row>
2742	<entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant> </entry>	2742	<entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant> </entry>
2743	<entry>Manual exposure time, auto iris.</entry>	2743	<entry>Manual exposure time, auto iris.</entry>
2744	</row>	2744	</row>
2745	<row>	2745	<row>
2746	<entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant> </entry>	2746	<entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant> </entry>
2747	<entry>Auto exposure time, manual iris.</entry>	2747	<entry>Auto exposure time, manual iris.</entry>
2748	</row>	2748	</row>
2749	</tbody>	2749	</tbody>
2750	</entrytbl>	2750	</entrytbl>
2751	</row>	2751	</row>
2752	<row><entry></entry></row>	2752	<row><entry></entry></row>
2753		2753
2754	<row>	2754	<row>
2755	<entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant> </entry>	2755	<entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant> </entry>
2756	<entry>integer</entry>	2756	<entry>integer</entry>
2757	</row><row><entry spanname="descr">Determines the exposure	2757	</row><row><entry spanname="descr">Determines the exposure
2758	time of the camera sensor. The exposure time is limited by the frame	2758	time of the camera sensor. The exposure time is limited by the frame
2759	interval. Drivers should interpret the values as 100 µs units,	2759	interval. Drivers should interpret the values as 100 µs units,
2760	where the value 1 stands for 1/10000th of a second, 10000 for 1 second	2760	where the value 1 stands for 1/10000th of a second, 10000 for 1 second
2761	and 100000 for 10 seconds.</entry>	2761	and 100000 for 10 seconds.</entry>
2762	</row>	2762	</row>
2763	<row><entry></entry></row>	2763	<row><entry></entry></row>
2764		2764
2765	<row>	2765	<row>
2766	<entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant> </entry>	2766	<entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant> </entry>
2767	<entry>boolean</entry>	2767	<entry>boolean</entry>
2768	</row><row><entry spanname="descr">When	2768	</row><row><entry spanname="descr">When
2769	<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to	2769	<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to
2770	<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>,	2770	<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>,
2771	this control determines if the device may dynamically vary the frame	2771	this control determines if the device may dynamically vary the frame
2772	rate. By default this feature is disabled (0) and the frame rate must	2772	rate. By default this feature is disabled (0) and the frame rate must
2773	remain constant.</entry>	2773	remain constant.</entry>
2774	</row>	2774	</row>
2775	<row><entry></entry></row>	2775	<row><entry></entry></row>
2776		2776
2777	<row>	2777	<row>
2778	<entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant> </entry>	2778	<entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant> </entry>
2779	<entry>integer</entry>	2779	<entry>integer</entry>
2780	</row><row><entry spanname="descr">This control turns the	2780	</row><row><entry spanname="descr">This control turns the
2781	camera horizontally by the specified amount. The unit is undefined. A	2781	camera horizontally by the specified amount. The unit is undefined. A
2782	positive value moves the camera to the right (clockwise when viewed	2782	positive value moves the camera to the right (clockwise when viewed
2783	from above), a negative value to the left. A value of zero does not	2783	from above), a negative value to the left. A value of zero does not
2784	cause motion. This is a write-only control.</entry>	2784	cause motion. This is a write-only control.</entry>
2785	</row>	2785	</row>
2786	<row><entry></entry></row>	2786	<row><entry></entry></row>
2787		2787
2788	<row>	2788	<row>
2789	<entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant> </entry>	2789	<entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant> </entry>
2790	<entry>integer</entry>	2790	<entry>integer</entry>
2791	</row><row><entry spanname="descr">This control turns the	2791	</row><row><entry spanname="descr">This control turns the
2792	camera vertically by the specified amount. The unit is undefined. A	2792	camera vertically by the specified amount. The unit is undefined. A
2793	positive value moves the camera up, a negative value down. A value of	2793	positive value moves the camera up, a negative value down. A value of
2794	zero does not cause motion. This is a write-only control.</entry>	2794	zero does not cause motion. This is a write-only control.</entry>
2795	</row>	2795	</row>
2796	<row><entry></entry></row>	2796	<row><entry></entry></row>
2797		2797
2798	<row>	2798	<row>
2799	<entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant> </entry>	2799	<entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant> </entry>
2800	<entry>button</entry>	2800	<entry>button</entry>
2801	</row><row><entry spanname="descr">When this control is set,	2801	</row><row><entry spanname="descr">When this control is set,
2802	the camera moves horizontally to the default position.</entry>	2802	the camera moves horizontally to the default position.</entry>
2803	</row>	2803	</row>
2804	<row><entry></entry></row>	2804	<row><entry></entry></row>
2805		2805
2806	<row>	2806	<row>
2807	<entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant> </entry>	2807	<entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant> </entry>
2808	<entry>button</entry>	2808	<entry>button</entry>
2809	</row><row><entry spanname="descr">When this control is set,	2809	</row><row><entry spanname="descr">When this control is set,
2810	the camera moves vertically to the default position.</entry>	2810	the camera moves vertically to the default position.</entry>
2811	</row>	2811	</row>
2812	<row><entry></entry></row>	2812	<row><entry></entry></row>
2813		2813
2814	<row>	2814	<row>
2815	<entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant> </entry>	2815	<entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant> </entry>
2816	<entry>integer</entry>	2816	<entry>integer</entry>
2817	</row><row><entry spanname="descr">This control	2817	</row><row><entry spanname="descr">This control
2818	turns the camera horizontally to the specified position. Positive	2818	turns the camera horizontally to the specified position. Positive
2819	values move the camera to the right (clockwise when viewed from above),	2819	values move the camera to the right (clockwise when viewed from above),
2820	negative values to the left. Drivers should interpret the values as arc	2820	negative values to the left. Drivers should interpret the values as arc
2821	seconds, with valid values between -180 * 3600 and +180 * 3600	2821	seconds, with valid values between -180 * 3600 and +180 * 3600
2822	inclusive.</entry>	2822	inclusive.</entry>
2823	</row>	2823	</row>
2824	<row><entry></entry></row>	2824	<row><entry></entry></row>
2825		2825
2826	<row>	2826	<row>
2827	<entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant> </entry>	2827	<entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant> </entry>
2828	<entry>integer</entry>	2828	<entry>integer</entry>
2829	</row><row><entry spanname="descr">This control	2829	</row><row><entry spanname="descr">This control
2830	turns the camera vertically to the specified position. Positive values	2830	turns the camera vertically to the specified position. Positive values
2831	move the camera up, negative values down. Drivers should interpret the	2831	move the camera up, negative values down. Drivers should interpret the
2832	values as arc seconds, with valid values between -180 * 3600 and +180	2832	values as arc seconds, with valid values between -180 * 3600 and +180
2833	* 3600 inclusive.</entry>	2833	* 3600 inclusive.</entry>
2834	</row>	2834	</row>
2835	<row><entry></entry></row>	2835	<row><entry></entry></row>
2836		2836
2837	<row>	2837	<row>
2838	<entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant> </entry>	2838	<entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant> </entry>
2839	<entry>integer</entry>	2839	<entry>integer</entry>
2840	</row><row><entry spanname="descr">This control sets the	2840	</row><row><entry spanname="descr">This control sets the
2841	focal point of the camera to the specified position. The unit is	2841	focal point of the camera to the specified position. The unit is
2842	undefined. Positive values set the focus closer to the camera,	2842	undefined. Positive values set the focus closer to the camera,
2843	negative values towards infinity.</entry>	2843	negative values towards infinity.</entry>
2844	</row>	2844	</row>
2845	<row><entry></entry></row>	2845	<row><entry></entry></row>
2846		2846
2847	<row>	2847	<row>
2848	<entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant> </entry>	2848	<entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant> </entry>
2849	<entry>integer</entry>	2849	<entry>integer</entry>
2850	</row><row><entry spanname="descr">This control moves the	2850	</row><row><entry spanname="descr">This control moves the
2851	focal point of the camera by the specified amount. The unit is	2851	focal point of the camera by the specified amount. The unit is
2852	undefined. Positive values move the focus closer to the camera,	2852	undefined. Positive values move the focus closer to the camera,
2853	negative values towards infinity. This is a write-only control.</entry>	2853	negative values towards infinity. This is a write-only control.</entry>
2854	</row>	2854	</row>
2855	<row><entry></entry></row>	2855	<row><entry></entry></row>
2856		2856
2857	<row>	2857	<row>
2858	<entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant> </entry>	2858	<entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant> </entry>
2859	<entry>boolean</entry>	2859	<entry>boolean</entry>
2860	</row><row><entry spanname="descr">Enables automatic focus	2860	</row><row><entry spanname="descr">Enables automatic focus
2861	adjustments. The effect of manual focus adjustments while this feature	2861	adjustments. The effect of manual focus adjustments while this feature
2862	is enabled is undefined, drivers should ignore such requests.</entry>	2862	is enabled is undefined, drivers should ignore such requests.</entry>
2863	</row>	2863	</row>
2864	<row><entry></entry></row>	2864	<row><entry></entry></row>
2865		2865
2866	<row>	2866	<row>
2867	<entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant> </entry>	2867	<entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant> </entry>
2868	<entry>integer</entry>	2868	<entry>integer</entry>
2869	</row><row><entry spanname="descr">Specify the objective lens	2869	</row><row><entry spanname="descr">Specify the objective lens
2870	focal length as an absolute value. The zoom unit is driver-specific and its	2870	focal length as an absolute value. The zoom unit is driver-specific and its
2871	value should be a positive integer.</entry>	2871	value should be a positive integer.</entry>
2872	</row>	2872	</row>
2873	<row><entry></entry></row>	2873	<row><entry></entry></row>
2874		2874
2875	<row>	2875	<row>
2876	<entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant> </entry>	2876	<entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant> </entry>
2877	<entry>integer</entry>	2877	<entry>integer</entry>
2878	</row><row><entry spanname="descr">Specify the objective lens	2878	</row><row><entry spanname="descr">Specify the objective lens
2879	focal length relatively to the current value. Positive values move the zoom	2879	focal length relatively to the current value. Positive values move the zoom
2880	lens group towards the telephoto direction, negative values towards the	2880	lens group towards the telephoto direction, negative values towards the
2881	wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry>	2881	wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry>
2882	</row>	2882	</row>
2883	<row><entry></entry></row>	2883	<row><entry></entry></row>
2884		2884
2885	<row>	2885	<row>
2886	<entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant> </entry>	2886	<entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant> </entry>
2887	<entry>integer</entry>	2887	<entry>integer</entry>
2888	</row><row><entry spanname="descr">Move the objective lens group	2888	</row><row><entry spanname="descr">Move the objective lens group
2889	at the specified speed until it reaches physical device limits or until an	2889	at the specified speed until it reaches physical device limits or until an
2890	explicit request to stop the movement. A positive value moves the zoom lens	2890	explicit request to stop the movement. A positive value moves the zoom lens
2891	group towards the telephoto direction. A value of zero stops the zoom lens	2891	group towards the telephoto direction. A value of zero stops the zoom lens
2892	group movement. A negative value moves the zoom lens group towards the	2892	group movement. A negative value moves the zoom lens group towards the
2893	wide-angle direction. The zoom speed unit is driver-specific.</entry>	2893	wide-angle direction. The zoom speed unit is driver-specific.</entry>
2894	</row>	2894	</row>
2895	<row><entry></entry></row>	2895	<row><entry></entry></row>
2896		2896
2897	<row>	2897	<row>
2898	<entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant> </entry>	2898	<entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant> </entry>
2899	<entry>integer</entry>	2899	<entry>integer</entry>
2900	</row><row><entry spanname="descr">This control sets the	2900	</row><row><entry spanname="descr">This control sets the
2901	camera's aperture to the specified value. The unit is undefined.	2901	camera's aperture to the specified value. The unit is undefined.
2902	Larger values open the iris wider, smaller values close it.</entry>	2902	Larger values open the iris wider, smaller values close it.</entry>
2903	</row>	2903	</row>
2904	<row><entry></entry></row>	2904	<row><entry></entry></row>
2905		2905
2906	<row>	2906	<row>
2907	<entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant> </entry>	2907	<entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant> </entry>
2908	<entry>integer</entry>	2908	<entry>integer</entry>
2909	</row><row><entry spanname="descr">This control modifies the	2909	</row><row><entry spanname="descr">This control modifies the
2910	camera's aperture by the specified amount. The unit is undefined.	2910	camera's aperture by the specified amount. The unit is undefined.
2911	Positive values open the iris one step further, negative values close	2911	Positive values open the iris one step further, negative values close
2912	it one step further. This is a write-only control.</entry>	2912	it one step further. This is a write-only control.</entry>
2913	</row>	2913	</row>
2914	<row><entry></entry></row>	2914	<row><entry></entry></row>
2915		2915
2916	<row>	2916	<row>
2917	<entry spanname="id"><constant>V4L2_CID_PRIVACY</constant> </entry>	2917	<entry spanname="id"><constant>V4L2_CID_PRIVACY</constant> </entry>
2918	<entry>boolean</entry>	2918	<entry>boolean</entry>
2919	</row><row><entry spanname="descr">Prevent video from being acquired	2919	</row><row><entry spanname="descr">Prevent video from being acquired
2920	by the camera. When this control is set to <constant>TRUE</constant> (1), no	2920	by the camera. When this control is set to <constant>TRUE</constant> (1), no
2921	image can be captured by the camera. Common means to enforce privacy are	2921	image can be captured by the camera. Common means to enforce privacy are
2922	mechanical obturation of the sensor and firmware image processing, but the	2922	mechanical obturation of the sensor and firmware image processing, but the
2923	device is not restricted to these methods. Devices that implement the privacy	2923	device is not restricted to these methods. Devices that implement the privacy
2924	control must support read access and may support write access.</entry>	2924	control must support read access and may support write access.</entry>
2925	</row>	2925	</row>
2926		2926
2927	<row>	2927	<row>
2928	<entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant> </entry>	2928	<entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant> </entry>
2929	<entry>integer</entry>	2929	<entry>integer</entry>
2930	</row><row><entry spanname="descr">Switch the band-stop filter of a	2930	</row><row><entry spanname="descr">Switch the band-stop filter of a
2931	camera sensor on or off, or specify its strength. Such band-stop filters can	2931	camera sensor on or off, or specify its strength. Such band-stop filters can
2932	be used, for example, to filter out the fluorescent light component.</entry>	2932	be used, for example, to filter out the fluorescent light component.</entry>
2933	</row>	2933	</row>
2934	<row><entry></entry></row>	2934	<row><entry></entry></row>
2935	</tbody>	2935	</tbody>
2936	</tgroup>	2936	</tgroup>
2937	</table>	2937	</table>
2938	</section>	2938	</section>
2939		2939
2940	<section id="fm-tx-controls">	2940	<section id="fm-tx-controls">
2941	<title>FM Transmitter Control Reference</title>	2941	<title>FM Transmitter Control Reference</title>
2942		2942
2943	<para>The FM Transmitter (FM_TX) class includes controls for common features of	2943	<para>The FM Transmitter (FM_TX) class includes controls for common features of
2944	FM transmissions capable devices. Currently this class includes parameters for audio	2944	FM transmissions capable devices. Currently this class includes parameters for audio
2945	compression, pilot tone generation, audio deviation limiter, RDS transmission and	2945	compression, pilot tone generation, audio deviation limiter, RDS transmission and
2946	tuning power features.</para>	2946	tuning power features.</para>
2947		2947
2948	<table pgwide="1" frame="none" id="fm-tx-control-id">	2948	<table pgwide="1" frame="none" id="fm-tx-control-id">
2949	<title>FM_TX Control IDs</title>	2949	<title>FM_TX Control IDs</title>
2950		2950
2951	<tgroup cols="4">	2951	<tgroup cols="4">
2952	<colspec colname="c1" colwidth="1*" />	2952	<colspec colname="c1" colwidth="1*" />
2953	<colspec colname="c2" colwidth="6*" />	2953	<colspec colname="c2" colwidth="6*" />
2954	<colspec colname="c3" colwidth="2*" />	2954	<colspec colname="c3" colwidth="2*" />
2955	<colspec colname="c4" colwidth="6*" />	2955	<colspec colname="c4" colwidth="6*" />
2956	<spanspec namest="c1" nameend="c2" spanname="id" />	2956	<spanspec namest="c1" nameend="c2" spanname="id" />
2957	<spanspec namest="c2" nameend="c4" spanname="descr" />	2957	<spanspec namest="c2" nameend="c4" spanname="descr" />
2958	<thead>	2958	<thead>
2959	<row>	2959	<row>
2960	<entry spanname="id" align="left">ID</entry>	2960	<entry spanname="id" align="left">ID</entry>
2961	<entry align="left">Type</entry>	2961	<entry align="left">Type</entry>
2962	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>	2962	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
2963	</row>	2963	</row>
2964	</thead>	2964	</thead>
2965	<tbody valign="top">	2965	<tbody valign="top">
2966	<row><entry></entry></row>	2966	<row><entry></entry></row>
2967	<row>	2967	<row>
2968	<entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant> </entry>	2968	<entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant> </entry>
2969	<entry>class</entry>	2969	<entry>class</entry>
2970	</row><row><entry spanname="descr">The FM_TX class	2970	</row><row><entry spanname="descr">The FM_TX class
2971	descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a	2971	descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
2972	description of this control class.</entry>	2972	description of this control class.</entry>
2973	</row>	2973	</row>
2974	<row>	2974	<row>
2975	<entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant> </entry>	2975	<entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant> </entry>
2976	<entry>integer</entry>	2976	<entry>integer</entry>
2977	</row>	2977	</row>
2978	<row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.	2978	<row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.
2979	The range and step are driver-specific.</entry>	2979	The range and step are driver-specific.</entry>
2980	</row>	2980	</row>
2981	<row>	2981	<row>
2982	<entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant> </entry>	2982	<entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant> </entry>
2983	<entry>integer</entry>	2983	<entry>integer</entry>
2984	</row>	2984	</row>
2985	<row><entry spanname="descr">Sets the RDS Programme Identification field	2985	<row><entry spanname="descr">Sets the RDS Programme Identification field
2986	for transmission.</entry>	2986	for transmission.</entry>
2987	</row>	2987	</row>
2988	<row>	2988	<row>
2989	<entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant> </entry>	2989	<entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant> </entry>
2990	<entry>integer</entry>	2990	<entry>integer</entry>
2991	</row>	2991	</row>
2992	<row><entry spanname="descr">Sets the RDS Programme Type field for transmission.	2992	<row><entry spanname="descr">Sets the RDS Programme Type field for transmission.
2993	This encodes up to 31 pre-defined programme types.</entry>	2993	This encodes up to 31 pre-defined programme types.</entry>
2994	</row>	2994	</row>
2995	<row>	2995	<row>
2996	<entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant> </entry>	2996	<entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant> </entry>
2997	<entry>string</entry>	2997	<entry>string</entry>
2998	</row>	2998	</row>
2999	<row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.	2999	<row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.
3000	It is intended for static display on a receiver. It is the primary aid to listeners in programme service	3000	It is intended for static display on a receiver. It is the primary aid to listeners in programme service
3001	identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification,	3001	identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification,
3002	there is a full description of the correct character encoding for Programme Service name strings.	3002	there is a full description of the correct character encoding for Programme Service name strings.
3003	Also from RDS specification, PS is usually a single eight character text. However, it is also possible	3003	Also from RDS specification, PS is usually a single eight character text. However, it is also possible
3004	to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured	3004	to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
3005	with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>	3005	with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
3006	</row>	3006	</row>
3007	<row>	3007	<row>
3008	<entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant> </entry>	3008	<entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant> </entry>
3009	<entry>string</entry>	3009	<entry>string</entry>
3010	</row>	3010	</row>
3011	<row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of	3011	<row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of
3012	what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,	3012	what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
3013	programme-related information or any other text. In these cases, RadioText should be used in addition to	3013	programme-related information or any other text. In these cases, RadioText should be used in addition to
3014	<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described	3014	<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
3015	in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being	3015	in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being
3016	used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible	3016	used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
3017	to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured	3017	to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
3018	with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>	3018	with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
3019	</row>	3019	</row>
3020	<row>	3020	<row>
3021	<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry>	3021	<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant> </entry>
3022	<entry>boolean</entry>	3022	<entry>boolean</entry>
3023	</row>	3023	</row>
3024	<row><entry spanname="descr">Enables or disables the audio deviation limiter feature.	3024	<row><entry spanname="descr">Enables or disables the audio deviation limiter feature.
3025	The limiter is useful when trying to maximize the audio volume, minimize receiver-generated	3025	The limiter is useful when trying to maximize the audio volume, minimize receiver-generated
3026	distortion and prevent overmodulation.	3026	distortion and prevent overmodulation.
3027	</entry>	3027	</entry>
3028	</row>	3028	</row>
3029	<row>	3029	<row>
3030	<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant> </entry>	3030	<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant> </entry>
3031	<entry>integer</entry>	3031	<entry>integer</entry>
3032	</row>	3032	</row>
3033	<row><entry spanname="descr">Sets the audio deviation limiter feature release time.	3033	<row><entry spanname="descr">Sets the audio deviation limiter feature release time.
3034	Unit is in useconds. Step and range are driver-specific.</entry>	3034	Unit is in useconds. Step and range are driver-specific.</entry>
3035	</row>	3035	</row>
3036	<row>	3036	<row>
3037	<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant> </entry>	3037	<entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant> </entry>
3038	<entry>integer</entry>	3038	<entry>integer</entry>
3039	</row>	3039	</row>
3040	<row><entry spanname="descr">Configures audio frequency deviation level in Hz.	3040	<row><entry spanname="descr">Configures audio frequency deviation level in Hz.
3041	The range and step are driver-specific.</entry>	3041	The range and step are driver-specific.</entry>
3042	</row>	3042	</row>
3043	<row>	3043	<row>
3044	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant> </entry>	3044	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant> </entry>
3045	<entry>boolean</entry>	3045	<entry>boolean</entry>
3046	</row>	3046	</row>
3047	<row><entry spanname="descr">Enables or disables the audio compression feature.	3047	<row><entry spanname="descr">Enables or disables the audio compression feature.
3048	This feature amplifies signals below the threshold by a fixed gain and compresses audio	3048	This feature amplifies signals below the threshold by a fixed gain and compresses audio
3049	signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry>	3049	signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry>
3050	</row>	3050	</row>
3051	<row>	3051	<row>
3052	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant> </entry>	3052	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant> </entry>
3053	<entry>integer</entry>	3053	<entry>integer</entry>
3054	</row>	3054	</row>
3055	<row><entry spanname="descr">Sets the gain for audio compression feature. It is	3055	<row><entry spanname="descr">Sets the gain for audio compression feature. It is
3056	a dB value. The range and step are driver-specific.</entry>	3056	a dB value. The range and step are driver-specific.</entry>
3057	</row>	3057	</row>
3058	<row>	3058	<row>
3059	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant> </entry>	3059	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant> </entry>
3060	<entry>integer</entry>	3060	<entry>integer</entry>
3061	</row>	3061	</row>
3062	<row><entry spanname="descr">Sets the threshold level for audio compression freature.	3062	<row><entry spanname="descr">Sets the threshold level for audio compression freature.
3063	It is a dB value. The range and step are driver-specific.</entry>	3063	It is a dB value. The range and step are driver-specific.</entry>
3064	</row>	3064	</row>
3065	<row>	3065	<row>
3066	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant> </entry>	3066	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant> </entry>
3067	<entry>integer</entry>	3067	<entry>integer</entry>
3068	</row>	3068	</row>
3069	<row><entry spanname="descr">Sets the attack time for audio compression feature.	3069	<row><entry spanname="descr">Sets the attack time for audio compression feature.
3070	It is a useconds value. The range and step are driver-specific.</entry>	3070	It is a useconds value. The range and step are driver-specific.</entry>
3071	</row>	3071	</row>
3072	<row>	3072	<row>
3073	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant> </entry>	3073	<entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant> </entry>
3074	<entry>integer</entry>	3074	<entry>integer</entry>
3075	</row>	3075	</row>
3076	<row><entry spanname="descr">Sets the release time for audio compression feature.	3076	<row><entry spanname="descr">Sets the release time for audio compression feature.
3077	It is a useconds value. The range and step are driver-specific.</entry>	3077	It is a useconds value. The range and step are driver-specific.</entry>
3078	</row>	3078	</row>
3079	<row>	3079	<row>
3080	<entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant> </entry>	3080	<entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant> </entry>
3081	<entry>boolean</entry>	3081	<entry>boolean</entry>
3082	</row>	3082	</row>
3083	<row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry>	3083	<row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry>
3084	</row>	3084	</row>
3085	<row>	3085	<row>
3086	<entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant> </entry>	3086	<entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant> </entry>
3087	<entry>integer</entry>	3087	<entry>integer</entry>
3088	</row>	3088	</row>
3089	<row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is	3089	<row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is
3090	in Hz. The range and step are driver-specific.</entry>	3090	in Hz. The range and step are driver-specific.</entry>
3091	</row>	3091	</row>
3092	<row>	3092	<row>
3093	<entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant> </entry>	3093	<entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant> </entry>
3094	<entry>integer</entry>	3094	<entry>integer</entry>
3095	</row>	3095	</row>
3096	<row><entry spanname="descr">Configures pilot tone frequency value. Unit is	3096	<row><entry spanname="descr">Configures pilot tone frequency value. Unit is
3097	in Hz. The range and step are driver-specific.</entry>	3097	in Hz. The range and step are driver-specific.</entry>
3098	</row>	3098	</row>
3099	<row>	3099	<row>
3100	<entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry>	3100	<entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry>
3101	<entry>integer</entry>	3101	<entry>integer</entry>
3102	</row>	3102	</row>
3103	<row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.	3103	<row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.
3104	A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.	3104	A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
3105	Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis	3105	Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_preemphasis
3106	defines possible values for pre-emphasis. Here they are:</entry>	3106	defines possible values for pre-emphasis. Here they are:</entry>
3107	</row><row>	3107	</row><row>
3108	<entrytbl spanname="descr" cols="2">	3108	<entrytbl spanname="descr" cols="2">
3109	<tbody valign="top">	3109	<tbody valign="top">
3110	<row>	3110	<row>
3111	<entry><constant>V4L2_PREEMPHASIS_DISABLED</constant> </entry>	3111	<entry><constant>V4L2_PREEMPHASIS_DISABLED</constant> </entry>
3112	<entry>No pre-emphasis is applied.</entry>	3112	<entry>No pre-emphasis is applied.</entry>
3113	</row>	3113	</row>
3114	<row>	3114	<row>
3115	<entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry>	3115	<entry><constant>V4L2_PREEMPHASIS_50_uS</constant> </entry>
3116	<entry>A pre-emphasis of 50 uS is used.</entry>	3116	<entry>A pre-emphasis of 50 uS is used.</entry>
3117	</row>	3117	</row>
3118	<row>	3118	<row>
3119	<entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </entry>	3119	<entry><constant>V4L2_PREEMPHASIS_75_uS</constant> </entry>
3120	<entry>A pre-emphasis of 75 uS is used.</entry>	3120	<entry>A pre-emphasis of 75 uS is used.</entry>
3121	</row>	3121	</row>
3122	</tbody>	3122	</tbody>
3123	</entrytbl>	3123	</entrytbl>
3124		3124
3125	</row>	3125	</row>
3126	<row>	3126	<row>
3127	<entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant> </entry>	3127	<entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant> </entry>
3128	<entry>integer</entry>	3128	<entry>integer</entry>
3129	</row>	3129	</row>
3130	<row><entry spanname="descr">Sets the output power level for signal transmission.	3130	<row><entry spanname="descr">Sets the output power level for signal transmission.
3131	Unit is in dBuV. Range and step are driver-specific.</entry>	3131	Unit is in dBuV. Range and step are driver-specific.</entry>
3132	</row>	3132	</row>
3133	<row>	3133	<row>
3134	<entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant> </entry>	3134	<entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant> </entry>
3135	<entry>integer</entry>	3135	<entry>integer</entry>
3136	</row>	3136	</row>
3137	<row><entry spanname="descr">This selects the value of antenna tuning capacitor	3137	<row><entry spanname="descr">This selects the value of antenna tuning capacitor
3138	manually or automatically if set to zero. Unit, range and step are driver-specific.</entry>	3138	manually or automatically if set to zero. Unit, range and step are driver-specific.</entry>
3139	</row>	3139	</row>
3140	<row><entry></entry></row>	3140	<row><entry></entry></row>
3141	</tbody>	3141	</tbody>
3142	</tgroup>	3142	</tgroup>
3143	</table>	3143	</table>
3144		3144
3145	<para>For more details about RDS specification, refer to	3145	<para>For more details about RDS specification, refer to
3146	<xref linkend="en50067" /> document, from CENELEC.</para>	3146	<xref linkend="en50067" /> document, from CENELEC.</para>
3147	</section>	3147	</section>
3148		3148
3149	<section id="flash-controls">	3149	<section id="flash-controls">
3150	<title>Flash Control Reference</title>	3150	<title>Flash Control Reference</title>
3151		3151
3152	<note>	3152	<note>
3153	<title>Experimental</title>	3153	<title>Experimental</title>
3154		3154
3155	<para>This is an <link linkend="experimental">experimental</link>	3155	<para>This is an <link linkend="experimental">experimental</link>
3156	interface and may change in the future.</para>	3156	interface and may change in the future.</para>
3157	</note>	3157	</note>
3158		3158
3159	<para>	3159	<para>
3160	The V4L2 flash controls are intended to provide generic access	3160	The V4L2 flash controls are intended to provide generic access
3161	to flash controller devices. Flash controller devices are	3161	to flash controller devices. Flash controller devices are
3162	typically used in digital cameras.	3162	typically used in digital cameras.
3163	</para>	3163	</para>
3164		3164
3165	<para>	3165	<para>
3166	The interface can support both LED and xenon flash devices. As	3166	The interface can support both LED and xenon flash devices. As
3167	of writing this, there is no xenon flash driver using this	3167	of writing this, there is no xenon flash driver using this
3168	interface.	3168	interface.
3169	</para>	3169	</para>
3170		3170
3171	<section id="flash-controls-use-cases">	3171	<section id="flash-controls-use-cases">
3172	<title>Supported use cases</title>	3172	<title>Supported use cases</title>
3173		3173
3174	<section>	3174	<section>
3175	<title>Unsynchronised LED flash (software strobe)</title>	3175	<title>Unsynchronised LED flash (software strobe)</title>
3176		3176
3177	<para>	3177	<para>
3178	Unsynchronised LED flash is controlled directly by the	3178	Unsynchronised LED flash is controlled directly by the
3179	host as the sensor. The flash must be enabled by the host	3179	host as the sensor. The flash must be enabled by the host
3180	before the exposure of the image starts and disabled once	3180	before the exposure of the image starts and disabled once
3181	it ends. The host is fully responsible for the timing of	3181	it ends. The host is fully responsible for the timing of
3182	the flash.	3182	the flash.
3183	</para>	3183	</para>
3184		3184
3185	<para>Example of such device: Nokia N900.</para>	3185	<para>Example of such device: Nokia N900.</para>
3186	</section>	3186	</section>
3187		3187
3188	<section>	3188	<section>
3189	<title>Synchronised LED flash (hardware strobe)</title>	3189	<title>Synchronised LED flash (hardware strobe)</title>
3190		3190
3191	<para>	3191	<para>
3192	The synchronised LED flash is pre-programmed by the host	3192	The synchronised LED flash is pre-programmed by the host
3193	(power and timeout) but controlled by the sensor through a	3193	(power and timeout) but controlled by the sensor through a
3194	strobe signal from the sensor to the flash.	3194	strobe signal from the sensor to the flash.
3195	</para>	3195	</para>
3196		3196
3197	<para>	3197	<para>
3198	The sensor controls the flash duration and timing. This	3198	The sensor controls the flash duration and timing. This
3199	information typically must be made available to the	3199	information typically must be made available to the
3200	sensor.	3200	sensor.
3201	</para>	3201	</para>
3202		3202
3203	</section>	3203	</section>
3204		3204
3205	<section>	3205	<section>
3206	<title>LED flash as torch</title>	3206	<title>LED flash as torch</title>
3207		3207
3208	<para>	3208	<para>
3209	LED flash may be used as torch in conjunction with another	3209	LED flash may be used as torch in conjunction with another
3210	use case involving camera or individually.	3210	use case involving camera or individually.
3211	</para>	3211	</para>
3212		3212
3213	</section>	3213	</section>
3214		3214
3215	</section>	3215	</section>
3216		3216
3217	<table pgwide="1" frame="none" id="flash-control-id">	3217	<table pgwide="1" frame="none" id="flash-control-id">
3218	<title>Flash Control IDs</title>	3218	<title>Flash Control IDs</title>
3219		3219
3220	<tgroup cols="4">	3220	<tgroup cols="4">
3221	<colspec colname="c1" colwidth="1*" />	3221	<colspec colname="c1" colwidth="1*" />
3222	<colspec colname="c2" colwidth="6*" />	3222	<colspec colname="c2" colwidth="6*" />
3223	<colspec colname="c3" colwidth="2*" />	3223	<colspec colname="c3" colwidth="2*" />
3224	<colspec colname="c4" colwidth="6*" />	3224	<colspec colname="c4" colwidth="6*" />
3225	<spanspec namest="c1" nameend="c2" spanname="id" />	3225	<spanspec namest="c1" nameend="c2" spanname="id" />
3226	<spanspec namest="c2" nameend="c4" spanname="descr" />	3226	<spanspec namest="c2" nameend="c4" spanname="descr" />
3227	<thead>	3227	<thead>
3228	<row>	3228	<row>
3229	<entry spanname="id" align="left">ID</entry>	3229	<entry spanname="id" align="left">ID</entry>
3230	<entry align="left">Type</entry>	3230	<entry align="left">Type</entry>
3231	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>	3231	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
3232	</row>	3232	</row>
3233	</thead>	3233	</thead>
3234	<tbody valign="top">	3234	<tbody valign="top">
3235	<row><entry></entry></row>	3235	<row><entry></entry></row>
3236	<row>	3236	<row>
3237	<entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry>	3237	<entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry>
3238	<entry>class</entry>	3238	<entry>class</entry>
3239	</row>	3239	</row>
3240	<row>	3240	<row>
3241	<entry spanname="descr">The FLASH class descriptor.</entry>	3241	<entry spanname="descr">The FLASH class descriptor.</entry>
3242	</row>	3242	</row>
3243	<row>	3243	<row>
3244	<entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry>	3244	<entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry>
3245	<entry>menu</entry>	3245	<entry>menu</entry>
3246	</row>	3246	</row>
3247	<row id="v4l2-flash-led-mode">	3247	<row id="v4l2-flash-led-mode">
3248	<entry spanname="descr">Defines the mode of the flash LED,	3248	<entry spanname="descr">Defines the mode of the flash LED,
3249	the high-power white LED attached to the flash controller.	3249	the high-power white LED attached to the flash controller.
3250	Setting this control may not be possible in presence of	3250	Setting this control may not be possible in presence of
3251	some faults. See V4L2_CID_FLASH_FAULT.</entry>	3251	some faults. See V4L2_CID_FLASH_FAULT.</entry>
3252	</row>	3252	</row>
3253	<row>	3253	<row>
3254	<entrytbl spanname="descr" cols="2">	3254	<entrytbl spanname="descr" cols="2">
3255	<tbody valign="top">	3255	<tbody valign="top">
3256	<row>	3256	<row>
3257	<entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry>	3257	<entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry>
3258	<entry>Off.</entry>	3258	<entry>Off.</entry>
3259	</row>	3259	</row>
3260	<row>	3260	<row>
3261	<entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry>	3261	<entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry>
3262	<entry>Flash mode.</entry>	3262	<entry>Flash mode.</entry>
3263	</row>	3263	</row>
3264	<row>	3264	<row>
3265	<entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry>	3265	<entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry>
3266	<entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry>	3266	<entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry>
3267	</row>	3267	</row>
3268	</tbody>	3268	</tbody>
3269	</entrytbl>	3269	</entrytbl>
3270	</row>	3270	</row>
3271	<row>	3271	<row>
3272	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry>	3272	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry>
3273	<entry>menu</entry>	3273	<entry>menu</entry>
3274	</row>	3274	</row>
3275	<row id="v4l2-flash-strobe-source"><entry	3275	<row id="v4l2-flash-strobe-source"><entry
3276	spanname="descr">Defines the source of the flash LED	3276	spanname="descr">Defines the source of the flash LED
3277	strobe.</entry>	3277	strobe.</entry>
3278	</row>	3278	</row>
3279	<row>	3279	<row>
3280	<entrytbl spanname="descr" cols="2">	3280	<entrytbl spanname="descr" cols="2">
3281	<tbody valign="top">	3281	<tbody valign="top">
3282	<row>	3282	<row>
3283	<entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry>	3283	<entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry>
3284	<entry>The flash strobe is triggered by using	3284	<entry>The flash strobe is triggered by using
3285	the V4L2_CID_FLASH_STROBE control.</entry>	3285	the V4L2_CID_FLASH_STROBE control.</entry>
3286	</row>	3286	</row>
3287	<row>	3287	<row>
3288	<entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry>	3288	<entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry>
3289	<entry>The flash strobe is triggered by an	3289	<entry>The flash strobe is triggered by an
3290	external source. Typically this is a sensor,	3290	external source. Typically this is a sensor,
3291	which makes it possible to synchronises the	3291	which makes it possible to synchronises the
3292	flash strobe start to exposure start.</entry>	3292	flash strobe start to exposure start.</entry>
3293	</row>	3293	</row>
3294	</tbody>	3294	</tbody>
3295	</entrytbl>	3295	</entrytbl>
3296	</row>	3296	</row>
3297	<row>	3297	<row>
3298	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry>	3298	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry>
3299	<entry>button</entry>	3299	<entry>button</entry>
3300	</row>	3300	</row>
3301	<row>	3301	<row>
3302	<entry spanname="descr">Strobe flash. Valid when	3302	<entry spanname="descr">Strobe flash. Valid when
3303	V4L2_CID_FLASH_LED_MODE is set to	3303	V4L2_CID_FLASH_LED_MODE is set to
3304	V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE	3304	V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
3305	is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this	3305	is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
3306	control may not be possible in presence of some faults.	3306	control may not be possible in presence of some faults.
3307	See V4L2_CID_FLASH_FAULT.</entry>	3307	See V4L2_CID_FLASH_FAULT.</entry>
3308	</row>	3308	</row>
3309	<row>	3309	<row>
3310	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry>	3310	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry>
3311	<entry>button</entry>	3311	<entry>button</entry>
3312	</row>	3312	</row>
3313	<row><entry spanname="descr">Stop flash strobe immediately.</entry>	3313	<row><entry spanname="descr">Stop flash strobe immediately.</entry>
3314	</row>	3314	</row>
3315	<row>	3315	<row>
3316	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry>	3316	<entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry>
3317	<entry>boolean</entry>	3317	<entry>boolean</entry>
3318	</row>	3318	</row>
3319	<row>	3319	<row>
3320	<entry spanname="descr">Strobe status: whether the flash	3320	<entry spanname="descr">Strobe status: whether the flash
3321	is strobing at the moment or not. This is a read-only	3321	is strobing at the moment or not. This is a read-only
3322	control.</entry>	3322	control.</entry>
3323	</row>	3323	</row>
3324	<row>	3324	<row>
3325	<entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry>	3325	<entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry>
3326	<entry>integer</entry>	3326	<entry>integer</entry>
3327	</row>	3327	</row>
3328	<row>	3328	<row>
3329	<entry spanname="descr">Hardware timeout for flash. The	3329	<entry spanname="descr">Hardware timeout for flash. The
3330	flash strobe is stopped after this period of time has	3330	flash strobe is stopped after this period of time has
3331	passed from the start of the strobe.</entry>	3331	passed from the start of the strobe.</entry>
3332	</row>	3332	</row>
3333	<row>	3333	<row>
3334	<entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry>	3334	<entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry>
3335	<entry>integer</entry>	3335	<entry>integer</entry>
3336	</row>	3336	</row>
3337	<row>	3337	<row>
3338	<entry spanname="descr">Intensity of the flash strobe when	3338	<entry spanname="descr">Intensity of the flash strobe when
3339	the flash LED is in flash mode	3339	the flash LED is in flash mode
3340	(V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps	3340	(V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps
3341	(mA) if possible.</entry>	3341	(mA) if possible.</entry>
3342	</row>	3342	</row>
3343	<row>	3343	<row>
3344	<entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry>	3344	<entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry>
3345	<entry>integer</entry>	3345	<entry>integer</entry>
3346	</row>	3346	</row>
3347	<row>	3347	<row>
3348	<entry spanname="descr">Intensity of the flash LED in	3348	<entry spanname="descr">Intensity of the flash LED in
3349	torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be	3349	torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be
3350	milliamps (mA) if possible. Setting this control may not	3350	milliamps (mA) if possible. Setting this control may not
3351	be possible in presence of some faults. See	3351	be possible in presence of some faults. See
3352	V4L2_CID_FLASH_FAULT.</entry>	3352	V4L2_CID_FLASH_FAULT.</entry>
3353	</row>	3353	</row>
3354	<row>	3354	<row>
3355	<entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry>	3355	<entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry>
3356	<entry>integer</entry>	3356	<entry>integer</entry>
3357	</row>	3357	</row>
3358	<row>	3358	<row>
3359	<entry spanname="descr">Intensity of the indicator LED.	3359	<entry spanname="descr">Intensity of the indicator LED.
3360	The indicator LED may be fully independent of the flash	3360	The indicator LED may be fully independent of the flash
3361	LED. The unit should be microamps (uA) if possible.</entry>	3361	LED. The unit should be microamps (uA) if possible.</entry>
3362	</row>	3362	</row>
3363	<row>	3363	<row>
3364	<entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry>	3364	<entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry>
3365	<entry>bitmask</entry>	3365	<entry>bitmask</entry>
3366	</row>	3366	</row>
3367	<row>	3367	<row>
3368	<entry spanname="descr">Faults related to the flash. The	3368	<entry spanname="descr">Faults related to the flash. The
3369	faults tell about specific problems in the flash chip	3369	faults tell about specific problems in the flash chip
3370	itself or the LEDs attached to it. Faults may prevent	3370	itself or the LEDs attached to it. Faults may prevent
3371	further use of some of the flash controls. In particular,	3371	further use of some of the flash controls. In particular,
3372	V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE	3372	V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
3373	if the fault affects the flash LED. Exactly which faults	3373	if the fault affects the flash LED. Exactly which faults
3374	have such an effect is chip dependent. Reading the faults	3374	have such an effect is chip dependent. Reading the faults
3375	resets the control and returns the chip to a usable state	3375	resets the control and returns the chip to a usable state
3376	if possible.</entry>	3376	if possible.</entry>
3377	</row>	3377	</row>
3378	<row>	3378	<row>
3379	<entrytbl spanname="descr" cols="2">	3379	<entrytbl spanname="descr" cols="2">
3380	<tbody valign="top">	3380	<tbody valign="top">
3381	<row>	3381	<row>
3382	<entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry>	3382	<entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry>
3383	<entry>Flash controller voltage to the flash LED	3383	<entry>Flash controller voltage to the flash LED
3384	has exceeded the limit specific to the flash	3384	has exceeded the limit specific to the flash
3385	controller.</entry>	3385	controller.</entry>
3386	</row>	3386	</row>
3387	<row>	3387	<row>
3388	<entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry>	3388	<entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry>
3389	<entry>The flash strobe was still on when	3389	<entry>The flash strobe was still on when
3390	the timeout set by the user ---	3390	the timeout set by the user ---
3391	V4L2_CID_FLASH_TIMEOUT control --- has expired.	3391	V4L2_CID_FLASH_TIMEOUT control --- has expired.
3392	Not all flash controllers may set this in all	3392	Not all flash controllers may set this in all
3393	such conditions.</entry>	3393	such conditions.</entry>
3394	</row>	3394	</row>
3395	<row>	3395	<row>
3396	<entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry>	3396	<entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry>
3397	<entry>The flash controller has overheated.</entry>	3397	<entry>The flash controller has overheated.</entry>
3398	</row>	3398	</row>
3399	<row>	3399	<row>
3400	<entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry>	3400	<entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry>
3401	<entry>The short circuit protection of the flash	3401	<entry>The short circuit protection of the flash
3402	controller has been triggered.</entry>	3402	controller has been triggered.</entry>
3403	</row>	3403	</row>
3404	<row>	3404	<row>
3405	<entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry>	3405	<entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry>
3406	<entry>Current in the LED power supply has exceeded the limit	3406	<entry>Current in the LED power supply has exceeded the limit
3407	specific to the flash controller.</entry>	3407	specific to the flash controller.</entry>
3408	</row>	3408	</row>
3409	<row>	3409	<row>
3410	<entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry>	3410	<entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry>
3411	<entry>The flash controller has detected a short or open	3411	<entry>The flash controller has detected a short or open
3412	circuit condition on the indicator LED.</entry>	3412	circuit condition on the indicator LED.</entry>
3413	</row>	3413	</row>
3414	</tbody>	3414	</tbody>
3415	</entrytbl>	3415	</entrytbl>
3416	</row>	3416	</row>
3417	<row>	3417	<row>
3418	<entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry>	3418	<entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry>
3419	<entry>boolean</entry>	3419	<entry>boolean</entry>
3420	</row>	3420	</row>
3421	<row><entry spanname="descr">Enable or disable charging of the xenon	3421	<row><entry spanname="descr">Enable or disable charging of the xenon
3422	flash capacitor.</entry>	3422	flash capacitor.</entry>
3423	</row>	3423	</row>
3424	<row>	3424	<row>
3425	<entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry>	3425	<entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry>
3426	<entry>boolean</entry>	3426	<entry>boolean</entry>
3427	</row>	3427	</row>
3428	<row>	3428	<row>
3429	<entry spanname="descr">Is the flash ready to strobe?	3429	<entry spanname="descr">Is the flash ready to strobe?
3430	Xenon flashes require their capacitors charged before	3430	Xenon flashes require their capacitors charged before
3431	strobing. LED flashes often require a cooldown period	3431	strobing. LED flashes often require a cooldown period
3432	after strobe during which another strobe will not be	3432	after strobe during which another strobe will not be
3433	possible. This is a read-only control.</entry>	3433	possible. This is a read-only control.</entry>
3434	</row>	3434	</row>
3435	<row><entry></entry></row>	3435	<row><entry></entry></row>
3436	</tbody>	3436	</tbody>
3437	</tgroup>	3437	</tgroup>
3438	</table>	3438	</table>
3439	</section>	3439	</section>
3440		3440
3441	<section id="jpeg-controls">	3441	<section id="jpeg-controls">
3442	<title>JPEG Control Reference</title>	3442	<title>JPEG Control Reference</title>
3443	<para>The JPEG class includes controls for common features of JPEG	3443	<para>The JPEG class includes controls for common features of JPEG
3444	encoders and decoders. Currently it includes features for codecs	3444	encoders and decoders. Currently it includes features for codecs
3445	implementing progressive baseline DCT compression process with	3445	implementing progressive baseline DCT compression process with
3446	Huffman entrophy coding.</para>	3446	Huffman entrophy coding.</para>
3447	<table pgwide="1" frame="none" id="jpeg-control-id">	3447	<table pgwide="1" frame="none" id="jpeg-control-id">
3448	<title>JPEG Control IDs</title>	3448	<title>JPEG Control IDs</title>
3449		3449
3450	<tgroup cols="4">	3450	<tgroup cols="4">
3451	<colspec colname="c1" colwidth="1*" />	3451	<colspec colname="c1" colwidth="1*" />
3452	<colspec colname="c2" colwidth="6*" />	3452	<colspec colname="c2" colwidth="6*" />
3453	<colspec colname="c3" colwidth="2*" />	3453	<colspec colname="c3" colwidth="2*" />
3454	<colspec colname="c4" colwidth="6*" />	3454	<colspec colname="c4" colwidth="6*" />
3455	<spanspec namest="c1" nameend="c2" spanname="id" />	3455	<spanspec namest="c1" nameend="c2" spanname="id" />
3456	<spanspec namest="c2" nameend="c4" spanname="descr" />	3456	<spanspec namest="c2" nameend="c4" spanname="descr" />
3457	<thead>	3457	<thead>
3458	<row>	3458	<row>
3459	<entry spanname="id" align="left">ID</entry>	3459	<entry spanname="id" align="left">ID</entry>
3460	<entry align="left">Type</entry>	3460	<entry align="left">Type</entry>
3461	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>	3461	</row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
3462	</row>	3462	</row>
3463	</thead>	3463	</thead>
3464	<tbody valign="top">	3464	<tbody valign="top">
3465	<row><entry></entry></row>	3465	<row><entry></entry></row>
3466	<row>	3466	<row>
3467	<entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant> </entry>	3467	<entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant> </entry>
3468	<entry>class</entry>	3468	<entry>class</entry>
3469	</row><row><entry spanname="descr">The JPEG class descriptor. Calling	3469	</row><row><entry spanname="descr">The JPEG class descriptor. Calling
3470	&VIDIOC-QUERYCTRL; for this control will return a description of this	3470	&VIDIOC-QUERYCTRL; for this control will return a description of this
3471	control class.	3471	control class.
3472		3472
3473	</entry>	3473	</entry>
3474	</row>	3474	</row>
3475	<row>	3475	<row>
3476	<entry spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant></entry>	3476	<entry spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant></entry>
3477	<entry>menu</entry>	3477	<entry>menu</entry>
3478	</row>	3478	</row>
3479	<row id="jpeg-chroma-subsampling-control">	3479	<row id="jpeg-chroma-subsampling-control">
3480	<entry spanname="descr">The chroma subsampling factors describe how	3480	<entry spanname="descr">The chroma subsampling factors describe how
3481	each component of an input image is sampled, in respect to maximum	3481	each component of an input image is sampled, in respect to maximum
3482	sample rate in each spatial dimension. See <xref linkend="itu-t81"/>,	3482	sample rate in each spatial dimension. See <xref linkend="itu-t81"/>,
3483	clause A.1.1. for more details. The <constant>	3483	clause A.1.1. for more details. The <constant>
3484	V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how	3484	V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how
3485	Cb and Cr components are downsampled after coverting an input image	3485	Cb and Cr components are downsampled after coverting an input image
3486	from RGB to Y'CbCr color space.	3486	from RGB to Y'CbCr color space.
3487	</entry>	3487	</entry>
3488	</row>	3488	</row>
3489	<row>	3489	<row>
3490	<entrytbl spanname="descr" cols="2">	3490	<entrytbl spanname="descr" cols="2">
3491	<tbody valign="top">	3491	<tbody valign="top">
3492	<row>	3492	<row>
3493	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant>	3493	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant>
3494	</entry><entry>No chroma subsampling, each pixel has	3494	</entry><entry>No chroma subsampling, each pixel has
3495	Y, Cr and Cb values.</entry>	3495	Y, Cr and Cb values.</entry>
3496	</row>	3496	</row>
3497	<row>	3497	<row>
3498	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant>	3498	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant>
3499	</entry><entry>Horizontally subsample Cr, Cb components	3499	</entry><entry>Horizontally subsample Cr, Cb components
3500	by a factor of 2.</entry>	3500	by a factor of 2.</entry>
3501	</row>	3501	</row>
3502	<row>	3502	<row>
3503	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant>	3503	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant>
3504	</entry><entry>Subsample Cr, Cb components horizontally	3504	</entry><entry>Subsample Cr, Cb components horizontally
3505	and vertically by 2.</entry>	3505	and vertically by 2.</entry>
3506	</row>	3506	</row>
3507	<row>	3507	<row>
3508	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant>	3508	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant>
3509	</entry><entry>Horizontally subsample Cr, Cb components	3509	</entry><entry>Horizontally subsample Cr, Cb components
3510	by a factor of 4.</entry>	3510	by a factor of 4.</entry>
3511	</row>	3511	</row>
3512	<row>	3512	<row>
3513	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant>	3513	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant>
3514	</entry><entry>Subsample Cr, Cb components horizontally	3514	</entry><entry>Subsample Cr, Cb components horizontally
3515	by 4 and vertically by 2.</entry>	3515	by 4 and vertically by 2.</entry>
3516	</row>	3516	</row>
3517	<row>	3517	<row>
3518	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant>	3518	<entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant>
3519	</entry><entry>Use only luminance component.</entry>	3519	</entry><entry>Use only luminance component.</entry>
3520	</row>	3520	</row>
3521	</tbody>	3521	</tbody>
3522	</entrytbl>	3522	</entrytbl>
3523	</row>	3523	</row>
3524	<row>	3524	<row>
3525	<entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant>	3525	<entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant>
3526	</entry><entry>integer</entry>	3526	</entry><entry>integer</entry>
3527	</row>	3527	</row>
3528	<row><entry spanname="descr">	3528	<row><entry spanname="descr">
3529	The restart interval determines an interval of inserting RSTm	3529	The restart interval determines an interval of inserting RSTm
3530	markers (m = 0..7). The purpose of these markers is to additionally	3530	markers (m = 0..7). The purpose of these markers is to additionally
3531	reinitialize the encoder process, in order to process blocks of	3531	reinitialize the encoder process, in order to process blocks of
3532	an image independently.	3532	an image independently.
3533	For the lossy compression processes the restart interval unit is	3533	For the lossy compression processes the restart interval unit is
3534	MCU (Minimum Coded Unit) and its value is contained in DRI	3534	MCU (Minimum Coded Unit) and its value is contained in DRI
3535	(Define Restart Interval) marker. If <constant>	3535	(Define Restart Interval) marker. If <constant>
3536	V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0,	3536	V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0,
3537	DRI and RSTm markers will not be inserted.	3537	DRI and RSTm markers will not be inserted.
3538	</entry>	3538	</entry>
3539	</row>	3539	</row>
3540	<row id="jpeg-quality-control">	3540	<row id="jpeg-quality-control">
3541	<entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESION_QUALITY</constant></entry>	3541	<entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESION_QUALITY</constant></entry>
3542	<entry>integer</entry>	3542	<entry>integer</entry>
3543	</row>	3543	</row>
3544	<row>	3544	<row>
3545	<entry spanname="descr">	3545	<entry spanname="descr">
3546	<constant>V4L2_CID_JPEG_COMPRESION_QUALITY</constant> control	3546	<constant>V4L2_CID_JPEG_COMPRESION_QUALITY</constant> control
3547	determines trade-off between image quality and size.	3547	determines trade-off between image quality and size.
3548	It provides simpler method for applications to control image quality,	3548	It provides simpler method for applications to control image quality,
3549	without a need for direct reconfiguration of luminance and chrominance	3549	without a need for direct reconfiguration of luminance and chrominance
3550	quantization tables.	3550	quantization tables.
3551		3551
3552	In cases where a driver uses quantization tables configured directly	3552	In cases where a driver uses quantization tables configured directly
3553	by an application, using interfaces defined elsewhere, <constant>	3553	by an application, using interfaces defined elsewhere, <constant>
3554	V4L2_CID_JPEG_COMPRESION_QUALITY</constant> control should be set	3554	V4L2_CID_JPEG_COMPRESION_QUALITY</constant> control should be set
3555	by driver to 0.	3555	by driver to 0.
3556		3556
3557	<para>The value range of this control is driver-specific. Only	3557	<para>The value range of this control is driver-specific. Only
3558	positive, non-zero values are meaningful. The recommended range	3558	positive, non-zero values are meaningful. The recommended range
3559	is 1 - 100, where larger values correspond to better image quality.	3559	is 1 - 100, where larger values correspond to better image quality.
3560	</para>	3560	</para>
3561	</entry>	3561	</entry>
3562	</row>	3562	</row>
3563	<row id="jpeg-active-marker-control">	3563	<row id="jpeg-active-marker-control">
3564	<entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry>	3564	<entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry>
3565	<entry>bitmask</entry>	3565	<entry>bitmask</entry>
3566	</row>	3566	</row>
3567	<row>	3567	<row>
3568	<entry spanname="descr">Specify which JPEG markers are included	3568	<entry spanname="descr">Specify which JPEG markers are included
3569	in compressed stream. This control is valid only for encoders.	3569	in compressed stream. This control is valid only for encoders.
3570	</entry>	3570	</entry>
3571	</row>	3571	</row>
3572	<row>	3572	<row>
3573	<entrytbl spanname="descr" cols="2">	3573	<entrytbl spanname="descr" cols="2">
3574	<tbody valign="top">	3574	<tbody valign="top">
3575	<row>	3575	<row>
3576	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry>	3576	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry>
3577	<entry>Application data segment APP<subscript>0</subscript>.</entry>	3577	<entry>Application data segment APP<subscript>0</subscript>.</entry>
3578	</row><row>	3578	</row><row>
3579	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry>	3579	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry>
3580	<entry>Application data segment APP<subscript>1</subscript>.</entry>	3580	<entry>Application data segment APP<subscript>1</subscript>.</entry>
3581	</row><row>	3581	</row><row>
3582	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry>	3582	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry>
3583	<entry>Comment segment.</entry>	3583	<entry>Comment segment.</entry>
3584	</row><row>	3584	</row><row>
3585	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry>	3585	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry>
3586	<entry>Quantization tables segment.</entry>	3586	<entry>Quantization tables segment.</entry>
3587	</row><row>	3587	</row><row>
3588	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry>	3588	<entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry>
3589	<entry>Huffman tables segment.</entry>	3589	<entry>Huffman tables segment.</entry>
3590	</row>	3590	</row>
3591	</tbody>	3591	</tbody>
3592	</entrytbl>	3592	</entrytbl>
3593	</row>	3593	</row>
3594	<row><entry></entry></row>	3594	<row><entry></entry></row>
3595	</tbody>	3595	</tbody>
3596	</tgroup>	3596	</tgroup>
3597	</table>	3597	</table>
3598	<para>For more details about JPEG specification, refer	3598	<para>For more details about JPEG specification, refer
3599	to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>,	3599	to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>,
3600	<xref linkend="w3c-jpeg-jfif"/>.</para>	3600	<xref linkend="w3c-jpeg-jfif"/>.</para>
3601	</section>	3601	</section>
3602	</section>	3602	</section>
3603		3603

Documentation/blackfin/bfin-gpio-notes.txt

Diff comments View file @ c94bed8

Documentation/devicetree/bindings/net/can/fsl-flexcan.txt

Diff comments View file @ c94bed8

1	Flexcan CAN contoller on Freescale's ARM and PowerPC system-on-a-chip (SOC).	1	Flexcan CAN controller on Freescale's ARM and PowerPC system-on-a-chip (SOC).
2		2
3	Required properties:	3	Required properties:
4		4
5	- compatible : Should be "fsl,<processor>-flexcan"	5	- compatible : Should be "fsl,<processor>-flexcan"
6		6
7	An implementation should also claim any of the following compatibles	7	An implementation should also claim any of the following compatibles
8	that it is fully backwards compatible with:	8	that it is fully backwards compatible with:
9		9
10	- fsl,p1010-flexcan	10	- fsl,p1010-flexcan
11		11
12	- reg : Offset and length of the register set for this device	12	- reg : Offset and length of the register set for this device
13	- interrupts : Interrupt tuple for this device	13	- interrupts : Interrupt tuple for this device
14	- clock-frequency : The oscillator frequency driving the flexcan device	14	- clock-frequency : The oscillator frequency driving the flexcan device
15		15
16	Example:	16	Example:
17		17
18	can@1c000 {	18	can@1c000 {
19	compatible = "fsl,p1010-flexcan";	19	compatible = "fsl,p1010-flexcan";
20	reg = <0x1c000 0x1000>;	20	reg = <0x1c000 0x1000>;
21	interrupts = <48 0x2>;	21	interrupts = <48 0x2>;
22	interrupt-parent = <&mpic>;	22	interrupt-parent = <&mpic>;
23	clock-frequency = <200000000>; // filled in by bootloader	23	clock-frequency = <200000000>; // filled in by bootloader
24	};	24	};
25		25

Documentation/dvb/opera-firmware.txt

Diff comments View file @ c94bed8

1	To extract the firmware for the Opera DVB-S1 USB-Box	1	To extract the firmware for the Opera DVB-S1 USB-Box
2	you need to copy the files:	2	you need to copy the files:
3		3
4	2830SCap2.sys	4	2830SCap2.sys
5	2830SLoad2.sys	5	2830SLoad2.sys
6		6
7	from the windriver disk into this directory.	7	from the windriver disk into this directory.
8		8
9	Then run	9	Then run
10		10
11	./get_dvb_firware opera1	11	./get_dvb_firmware opera1
12		12
13	and after that you have 2 files:	13	and after that you have 2 files:
14		14
15	dvb-usb-opera-01.fw	15	dvb-usb-opera-01.fw
16	dvb-usb-opera1-fpga-01.fw	16	dvb-usb-opera1-fpga-01.fw
17		17
18	in here.	18	in here.
19		19
20	Copy them into /lib/firmware/ .	20	Copy them into /lib/firmware/ .
21		21
22	After that the driver can load the firmware	22	After that the driver can load the firmware
23	(if you have enabled firmware loading	23	(if you have enabled firmware loading
24	in kernel config and have hotplug running).	24	in kernel config and have hotplug running).
25		25
26		26
27	Marco Gittler <g.marco@freenet.de>	27	Marco Gittler <g.marco@freenet.de>
		28

Documentation/edac.txt

Diff comments View file @ c94bed8

Documentation/filesystems/nfs/pnfs.txt

Diff comments View file @ c94bed8

Documentation/filesystems/qnx6.txt

Diff comments View file @ c94bed8

Documentation/hwmon/it87

Diff comments View file @ c94bed8

Documentation/memory-hotplug.txt

Diff comments View file @ c94bed8

Documentation/networking/can.txt

Diff comments View file @ c94bed8

Documentation/parisc/debugging

Diff comments View file @ c94bed8

Documentation/sound/alsa/compress_offload.txt

Diff comments View file @ c94bed8

Documentation/static-keys.txt

Diff comments View file @ c94bed8

1	What: /sys/bus/usb/devices/.../power/autosuspend	1	What: /sys/bus/usb/devices/.../power/autosuspend
2	Date: March 2007	2	Date: March 2007
3	KernelVersion: 2.6.21	3	KernelVersion: 2.6.21
4	Contact: Alan Stern <stern@rowland.harvard.edu>	4	Contact: Alan Stern <stern@rowland.harvard.edu>
5	Description:	5	Description:
6	Each USB device directory will contain a file named	6	Each USB device directory will contain a file named
7	power/autosuspend. This file holds the time (in seconds)	7	power/autosuspend. This file holds the time (in seconds)
8	the device must be idle before it will be autosuspended.	8	the device must be idle before it will be autosuspended.
9	0 means the device will be autosuspended as soon as	9	0 means the device will be autosuspended as soon as
10	possible. Negative values will prevent the device from	10	possible. Negative values will prevent the device from
11	being autosuspended at all, and writing a negative value	11	being autosuspended at all, and writing a negative value
12	will resume the device if it is already suspended.	12	will resume the device if it is already suspended.
13		13
14	The autosuspend delay for newly-created devices is set to	14	The autosuspend delay for newly-created devices is set to
15	the value of the usbcore.autosuspend module parameter.	15	the value of the usbcore.autosuspend module parameter.
16		16
17	What: /sys/bus/usb/devices/.../power/persist	17	What: /sys/bus/usb/devices/.../power/persist
18	Date: May 2007	18	Date: May 2007
19	KernelVersion: 2.6.23	19	KernelVersion: 2.6.23
20	Contact: Alan Stern <stern@rowland.harvard.edu>	20	Contact: Alan Stern <stern@rowland.harvard.edu>
21	Description:	21	Description:
22	If CONFIG_USB_PERSIST is set, then each USB device directory	22	If CONFIG_USB_PERSIST is set, then each USB device directory
23	will contain a file named power/persist. The file holds a	23	will contain a file named power/persist. The file holds a
24	boolean value (0 or 1) indicating whether or not the	24	boolean value (0 or 1) indicating whether or not the
25	"USB-Persist" facility is enabled for the device. Since the	25	"USB-Persist" facility is enabled for the device. Since the
26	facility is inherently dangerous, it is disabled by default	26	facility is inherently dangerous, it is disabled by default
27	for all devices except hubs. For more information, see	27	for all devices except hubs. For more information, see
28	Documentation/usb/persist.txt.	28	Documentation/usb/persist.txt.
29		29
30	What: /sys/bus/usb/device/.../power/connected_duration	30	What: /sys/bus/usb/device/.../power/connected_duration
31	Date: January 2008	31	Date: January 2008
32	KernelVersion: 2.6.25	32	KernelVersion: 2.6.25
33	Contact: Sarah Sharp <sarah.a.sharp@intel.com>	33	Contact: Sarah Sharp <sarah.a.sharp@intel.com>
34	Description:	34	Description:
35	If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file	35	If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
36	is present. When read, it returns the total time (in msec)	36	is present. When read, it returns the total time (in msec)
37	that the USB device has been connected to the machine. This	37	that the USB device has been connected to the machine. This
38	file is read-only.	38	file is read-only.
39	Users:	39	Users:
40	PowerTOP <power@bughost.org>	40	PowerTOP <power@bughost.org>
41	http://www.lesswatts.org/projects/powertop/	41	http://www.lesswatts.org/projects/powertop/
42		42
43	What: /sys/bus/usb/device/.../power/active_duration	43	What: /sys/bus/usb/device/.../power/active_duration
44	Date: January 2008	44	Date: January 2008
45	KernelVersion: 2.6.25	45	KernelVersion: 2.6.25
46	Contact: Sarah Sharp <sarah.a.sharp@intel.com>	46	Contact: Sarah Sharp <sarah.a.sharp@intel.com>
47	Description:	47	Description:
48	If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file	48	If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
49	is present. When read, it returns the total time (in msec)	49	is present. When read, it returns the total time (in msec)
50	that the USB device has been active, i.e. not in a suspended	50	that the USB device has been active, i.e. not in a suspended
51	state. This file is read-only.	51	state. This file is read-only.
52		52
53	Tools can use this file and the connected_duration file to	53	Tools can use this file and the connected_duration file to
54	compute the percentage of time that a device has been active.	54	compute the percentage of time that a device has been active.
55	For example,	55	For example,
56	echo $((100 * `cat active_duration` / `cat connected_duration`))	56	echo $((100 * `cat active_duration` / `cat connected_duration`))
57	will give an integer percentage. Note that this does not	57	will give an integer percentage. Note that this does not
58	account for counter wrap.	58	account for counter wrap.
59	Users:	59	Users:
60	PowerTOP <power@bughost.org>	60	PowerTOP <power@bughost.org>
61	http://www.lesswatts.org/projects/powertop/	61	http://www.lesswatts.org/projects/powertop/
62		62
63	What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend	63	What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend
64	Date: January 2008	64	Date: January 2008
65	KernelVersion: 2.6.27	65	KernelVersion: 2.6.27
66	Contact: Sarah Sharp <sarah.a.sharp@intel.com>	66	Contact: Sarah Sharp <sarah.a.sharp@intel.com>
67	Description:	67	Description:
68	When read, this file returns 1 if the interface driver	68	When read, this file returns 1 if the interface driver
69	for this interface supports autosuspend. It also	69	for this interface supports autosuspend. It also
70	returns 1 if no driver has claimed this interface, as an	70	returns 1 if no driver has claimed this interface, as an
71	unclaimed interface will not stop the device from being	71	unclaimed interface will not stop the device from being
72	autosuspended if all other interface drivers are idle.	72	autosuspended if all other interface drivers are idle.
73	The file returns 0 if autosuspend support has not been	73	The file returns 0 if autosuspend support has not been
74	added to the driver.	74	added to the driver.
75	Users:	75	Users:
76	USB PM tool	76	USB PM tool
77	git://git.moblin.org/users/sarah/usb-pm-tool/	77	git://git.moblin.org/users/sarah/usb-pm-tool/
78		78
79	What: /sys/bus/usb/device/.../authorized	79	What: /sys/bus/usb/device/.../authorized
80	Date: July 2008	80	Date: July 2008
81	KernelVersion: 2.6.26	81	KernelVersion: 2.6.26
82	Contact: David Vrabel <david.vrabel@csr.com>	82	Contact: David Vrabel <david.vrabel@csr.com>
83	Description:	83	Description:
84	Authorized devices are available for use by device	84	Authorized devices are available for use by device
85	drivers, non-authorized one are not. By default, wired	85	drivers, non-authorized one are not. By default, wired
86	USB devices are authorized.	86	USB devices are authorized.
87		87
88	Certified Wireless USB devices are not authorized	88	Certified Wireless USB devices are not authorized
89	initially and should be (by writing 1) after the	89	initially and should be (by writing 1) after the
90	device has been authenticated.	90	device has been authenticated.
91		91
92	What: /sys/bus/usb/device/.../wusb_cdid	92	What: /sys/bus/usb/device/.../wusb_cdid
93	Date: July 2008	93	Date: July 2008
94	KernelVersion: 2.6.27	94	KernelVersion: 2.6.27
95	Contact: David Vrabel <david.vrabel@csr.com>	95	Contact: David Vrabel <david.vrabel@csr.com>
96	Description:	96	Description:
97	For Certified Wireless USB devices only.	97	For Certified Wireless USB devices only.
98		98
99	A devices's CDID, as 16 space-separated hex octets.	99	A devices's CDID, as 16 space-separated hex octets.
100		100
101	What: /sys/bus/usb/device/.../wusb_ck	101	What: /sys/bus/usb/device/.../wusb_ck
102	Date: July 2008	102	Date: July 2008
103	KernelVersion: 2.6.27	103	KernelVersion: 2.6.27
104	Contact: David Vrabel <david.vrabel@csr.com>	104	Contact: David Vrabel <david.vrabel@csr.com>
105	Description:	105	Description:
106	For Certified Wireless USB devices only.	106	For Certified Wireless USB devices only.
107		107
108	Write the device's connection key (CK) to start the	108	Write the device's connection key (CK) to start the
109	authentication of the device. The CK is 16	109	authentication of the device. The CK is 16
110	space-separated hex octets.	110	space-separated hex octets.
111		111
112	What: /sys/bus/usb/device/.../wusb_disconnect	112	What: /sys/bus/usb/device/.../wusb_disconnect
113	Date: July 2008	113	Date: July 2008
114	KernelVersion: 2.6.27	114	KernelVersion: 2.6.27
115	Contact: David Vrabel <david.vrabel@csr.com>	115	Contact: David Vrabel <david.vrabel@csr.com>
116	Description:	116	Description:
117	For Certified Wireless USB devices only.	117	For Certified Wireless USB devices only.
118		118
119	Write a 1 to force the device to disconnect	119	Write a 1 to force the device to disconnect
120	(equivalent to unplugging a wired USB device).	120	(equivalent to unplugging a wired USB device).
121		121
122	What: /sys/bus/usb/drivers/.../new_id	122	What: /sys/bus/usb/drivers/.../new_id
123	Date: October 2011	123	Date: October 2011
124	Contact: linux-usb@vger.kernel.org	124	Contact: linux-usb@vger.kernel.org
125	Description:	125	Description:
126	Writing a device ID to this file will attempt to	126	Writing a device ID to this file will attempt to
127	dynamically add a new device ID to a USB device driver.	127	dynamically add a new device ID to a USB device driver.
128	This may allow the driver to support more hardware than	128	This may allow the driver to support more hardware than
129	was included in the driver's static device ID support	129	was included in the driver's static device ID support
130	table at compile time. The format for the device ID is:	130	table at compile time. The format for the device ID is:
131	idVendor idProduct bInterfaceClass.	131	idVendor idProduct bInterfaceClass.
132	The vendor ID and device ID fields are required, the	132	The vendor ID and device ID fields are required, the
133	interface class is optional.	133	interface class is optional.
134	Upon successfully adding an ID, the driver will probe	134	Upon successfully adding an ID, the driver will probe
135	for the device and attempt to bind to it. For example:	135	for the device and attempt to bind to it. For example:
136	# echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id	136	# echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
137		137
138	What: /sys/bus/usb-serial/drivers/.../new_id	138	What: /sys/bus/usb-serial/drivers/.../new_id
139	Date: October 2011	139	Date: October 2011
140	Contact: linux-usb@vger.kernel.org	140	Contact: linux-usb@vger.kernel.org
141	Description:	141	Description:
142	For serial USB drivers, this attribute appears under the	142	For serial USB drivers, this attribute appears under the
143	extra bus folder "usb-serial" in sysfs; apart from that	143	extra bus folder "usb-serial" in sysfs; apart from that
144	difference, all descriptions from the entry	144	difference, all descriptions from the entry
145	"/sys/bus/usb/drivers/.../new_id" apply.	145	"/sys/bus/usb/drivers/.../new_id" apply.
146		146
147	What: /sys/bus/usb/drivers/.../remove_id	147	What: /sys/bus/usb/drivers/.../remove_id
148	Date: November 2009	148	Date: November 2009
149	Contact: CHENG Renquan <rqcheng@smu.edu.sg>	149	Contact: CHENG Renquan <rqcheng@smu.edu.sg>
150	Description:	150	Description:
151	Writing a device ID to this file will remove an ID	151	Writing a device ID to this file will remove an ID
152	that was dynamically added via the new_id sysfs entry.	152	that was dynamically added via the new_id sysfs entry.
153	The format for the device ID is:	153	The format for the device ID is:
154	idVendor idProduct. After successfully	154	idVendor idProduct. After successfully
155	removing an ID, the driver will no longer support the	155	removing an ID, the driver will no longer support the
156	device. This is useful to ensure auto probing won't	156	device. This is useful to ensure auto probing won't
157	match the driver to the device. For example:	157	match the driver to the device. For example:
158	# echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id	158	# echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id
159		159
160	What: /sys/bus/usb/device/.../avoid_reset_quirk	160	What: /sys/bus/usb/device/.../avoid_reset_quirk
161	Date: December 2009	161	Date: December 2009
162	Contact: Oliver Neukum <oliver@neukum.org>	162	Contact: Oliver Neukum <oliver@neukum.org>
163	Description:	163	Description:
164	Writing 1 to this file tells the kernel that this	164	Writing 1 to this file tells the kernel that this
165	device will morph into another mode when it is reset.	165	device will morph into another mode when it is reset.
166	Drivers will not use reset for error handling for	166	Drivers will not use reset for error handling for
167	such devices.	167	such devices.
168	Users:	168	Users:
169	usb_modeswitch	169	usb_modeswitch
170		170
171	What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm	171	What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm
172	Date: September 2011	172	Date: September 2011
173	Contact: Andiry Xu <andiry.xu@amd.com>	173	Contact: Andiry Xu <andiry.xu@amd.com>
174	Description:	174	Description:
175	If CONFIG_USB_SUSPEND is set and a USB 2.0 lpm-capable device	175	If CONFIG_USB_SUSPEND is set and a USB 2.0 lpm-capable device
176	is plugged in to a xHCI host which support link PM, it will	176	is plugged in to a xHCI host which support link PM, it will
177	perform a LPM test; if the test is passed and host supports	177	perform a LPM test; if the test is passed and host supports
178	USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will	178	USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will
179	be enabled for the device and the USB device directory will	179	be enabled for the device and the USB device directory will
180	contain a file named power/usb2_hardware_lpm. The file holds	180	contain a file named power/usb2_hardware_lpm. The file holds
181	a string value (enable or disable) indicating whether or not	181	a string value (enable or disable) indicating whether or not
182	USB2 hardware LPM is enabled for the device. Developer can	182	USB2 hardware LPM is enabled for the device. Developer can
183	write y/Y/1 or n/N/0 to the file to enable/disable the	183	write y/Y/1 or n/N/0 to the file to enable/disable the
184	feature.	184	feature.
185		185
186	What: /sys/bus/usb/devices/.../removable	186	What: /sys/bus/usb/devices/.../removable
187	Date: February 2012	187	Date: February 2012
188	Contact: Matthew Garrett <mjg@redhat.com>	188	Contact: Matthew Garrett <mjg@redhat.com>
189	Description:	189	Description:
190	Some information about whether a given USB device is	190	Some information about whether a given USB device is
191	physically fixed to the platform can be inferred from a	191	physically fixed to the platform can be inferred from a
192	combination of hub decriptor bits and platform-specific data	192	combination of hub descriptor bits and platform-specific data
193	such as ACPI. This file will read either "removable" or	193	such as ACPI. This file will read either "removable" or
194	"fixed" if the information is available, and "unknown"	194	"fixed" if the information is available, and "unknown"
195	otherwise.	195	otherwise.
		196

1	/*	1	/*
2	* File: Documentation/blackfin/bfin-gpio-notes.txt	2	* File: Documentation/blackfin/bfin-gpio-notes.txt
3	* Based on:	3	* Based on:
4	* Author:	4	* Author:
5	*	5	*
6	* Created: $Id: bfin-gpio-note.txt 2008-11-24 16:42 grafyang $	6	* Created: $Id: bfin-gpio-note.txt 2008-11-24 16:42 grafyang $
7	* Description: This file contains the notes in developing/using bfin-gpio.	7	* Description: This file contains the notes in developing/using bfin-gpio.
8	*	8	*
9	*	9	*
10	* Rev:	10	* Rev:
11	*	11	*
12	* Modified:	12	* Modified:
13	* Copyright 2004-2008 Analog Devices Inc.	13	* Copyright 2004-2008 Analog Devices Inc.
14	*	14	*
15	* Bugs: Enter bugs at http://blackfin.uclinux.org/	15	* Bugs: Enter bugs at http://blackfin.uclinux.org/
16	*	16	*
17	*/	17	*/
18		18
19		19
20	1. Blackfin GPIO introduction	20	1. Blackfin GPIO introduction
21		21
22	There are many GPIO pins on Blackfin. Most of these pins are muxed to	22	There are many GPIO pins on Blackfin. Most of these pins are muxed to
23	multi-functions. They can be configured as peripheral, or just as GPIO,	23	multi-functions. They can be configured as peripheral, or just as GPIO,
24	configured to input with interrupt enabled, or output.	24	configured to input with interrupt enabled, or output.
25		25
26	For detailed information, please see "arch/blackfin/kernel/bfin_gpio.c",	26	For detailed information, please see "arch/blackfin/kernel/bfin_gpio.c",
27	or the relevant HRM.	27	or the relevant HRM.
28		28
29		29
30	2. Avoiding resource conflict	30	2. Avoiding resource conflict
31		31
32	Followed function groups are used to avoiding resource conflict,	32	Followed function groups are used to avoiding resource conflict,
33	- Use the pin as peripheral,	33	- Use the pin as peripheral,
34	int peripheral_request(unsigned short per, const char *label);	34	int peripheral_request(unsigned short per, const char *label);
35	int peripheral_request_list(const unsigned short per[], const char *label);	35	int peripheral_request_list(const unsigned short per[], const char *label);
36	void peripheral_free(unsigned short per);	36	void peripheral_free(unsigned short per);
37	void peripheral_free_list(const unsigned short per[]);	37	void peripheral_free_list(const unsigned short per[]);
38	- Use the pin as GPIO,	38	- Use the pin as GPIO,
39	int bfin_gpio_request(unsigned gpio, const char *label);	39	int bfin_gpio_request(unsigned gpio, const char *label);
40	void bfin_gpio_free(unsigned gpio);	40	void bfin_gpio_free(unsigned gpio);
41	- Use the pin as GPIO interrupt,	41	- Use the pin as GPIO interrupt,
42	int bfin_gpio_irq_request(unsigned gpio, const char *label);	42	int bfin_gpio_irq_request(unsigned gpio, const char *label);
43	void bfin_gpio_irq_free(unsigned gpio);	43	void bfin_gpio_irq_free(unsigned gpio);
44		44
45	The request functions will record the function state for a certain pin,	45	The request functions will record the function state for a certain pin,
46	the free functions will clear its function state.	46	the free functions will clear its function state.
47	Once a pin is requested, it can't be requested again before it is freed by	47	Once a pin is requested, it can't be requested again before it is freed by
48	previous caller, otherwise kernel will dump stacks, and the request	48	previous caller, otherwise kernel will dump stacks, and the request
49	function fail.	49	function fail.
50	These functions are wrapped by other functions, most of the users need not	50	These functions are wrapped by other functions, most of the users need not
51	care.	51	care.
52		52
53		53
54	3. But there are some exceptions	54	3. But there are some exceptions
55	- Kernel permit the identical GPIO be requested both as GPIO and GPIO	55	- Kernel permit the identical GPIO be requested both as GPIO and GPIO
56	interrut.	56	interrupt.
57	Some drivers, like gpio-keys, need this behavior. Kernel only print out	57	Some drivers, like gpio-keys, need this behavior. Kernel only print out
58	warning messages like,	58	warning messages like,
59	bfin-gpio: GPIO 24 is already reserved by gpio-keys: BTN0, and you are	59	bfin-gpio: GPIO 24 is already reserved by gpio-keys: BTN0, and you are
60	configuring it as IRQ!	60	configuring it as IRQ!
61		61
62	Note: Consider the case that, if there are two drivers need the	62	Note: Consider the case that, if there are two drivers need the
63	identical GPIO, one of them use it as GPIO, the other use it as	63	identical GPIO, one of them use it as GPIO, the other use it as
64	GPIO interrupt. This will really cause resource conflict. So if	64	GPIO interrupt. This will really cause resource conflict. So if
65	there is any abnormal driver behavior, please check the bfin-gpio	65	there is any abnormal driver behavior, please check the bfin-gpio
66	warning messages.	66	warning messages.
67		67
68	- Kernel permit the identical GPIO be requested from the same driver twice.	68	- Kernel permit the identical GPIO be requested from the same driver twice.
69		69
70		70
71		71
72		72

1	Reference counting in pnfs:	1	Reference counting in pnfs:
2	==========================	2	==========================
3		3
4	The are several inter-related caches. We have layouts which can	4	The are several inter-related caches. We have layouts which can
5	reference multiple devices, each of which can reference multiple data servers.	5	reference multiple devices, each of which can reference multiple data servers.
6	Each data server can be referenced by multiple devices. Each device	6	Each data server can be referenced by multiple devices. Each device
7	can be referenced by multiple layouts. To keep all of this straight,	7	can be referenced by multiple layouts. To keep all of this straight,
8	we need to reference count.	8	we need to reference count.
9		9
10		10
11	struct pnfs_layout_hdr	11	struct pnfs_layout_hdr
12	----------------------	12	----------------------
13	The on-the-wire command LAYOUTGET corresponds to struct	13	The on-the-wire command LAYOUTGET corresponds to struct
14	pnfs_layout_segment, usually referred to by the variable name lseg.	14	pnfs_layout_segment, usually referred to by the variable name lseg.
15	Each nfs_inode may hold a pointer to a cache of of these layout	15	Each nfs_inode may hold a pointer to a cache of of these layout
16	segments in nfsi->layout, of type struct pnfs_layout_hdr.	16	segments in nfsi->layout, of type struct pnfs_layout_hdr.
17		17
18	We reference the header for the inode pointing to it, across each	18	We reference the header for the inode pointing to it, across each
19	outstanding RPC call that references it (LAYOUTGET, LAYOUTRETURN,	19	outstanding RPC call that references it (LAYOUTGET, LAYOUTRETURN,
20	LAYOUTCOMMIT), and for each lseg held within.	20	LAYOUTCOMMIT), and for each lseg held within.
21		21
22	Each header is also (when non-empty) put on a list associated with	22	Each header is also (when non-empty) put on a list associated with
23	struct nfs_client (cl_layouts). Being put on this list does not bump	23	struct nfs_client (cl_layouts). Being put on this list does not bump
24	the reference count, as the layout is kept around by the lseg that	24	the reference count, as the layout is kept around by the lseg that
25	keeps it in the list.	25	keeps it in the list.
26		26
27	deviceid_cache	27	deviceid_cache
28	--------------	28	--------------
29	lsegs reference device ids, which are resolved per nfs_client and	29	lsegs reference device ids, which are resolved per nfs_client and
30	layout driver type. The device ids are held in a RCU cache (struct	30	layout driver type. The device ids are held in a RCU cache (struct
31	nfs4_deviceid_cache). The cache itself is referenced across each	31	nfs4_deviceid_cache). The cache itself is referenced across each
32	mount. The entries (struct nfs4_deviceid) themselves are held across	32	mount. The entries (struct nfs4_deviceid) themselves are held across
33	the lifetime of each lseg referencing them.	33	the lifetime of each lseg referencing them.
34		34
35	RCU is used because the deviceid is basically a write once, read many	35	RCU is used because the deviceid is basically a write once, read many
36	data structure. The hlist size of 32 buckets needs better	36	data structure. The hlist size of 32 buckets needs better
37	justification, but seems reasonable given that we can have multiple	37	justification, but seems reasonable given that we can have multiple
38	deviceid's per filesystem, and multiple filesystems per nfs_client.	38	deviceid's per filesystem, and multiple filesystems per nfs_client.
39		39
40	The hash code is copied from the nfsd code base. A discussion of	40	The hash code is copied from the nfsd code base. A discussion of
41	hashing and variations of this algorithm can be found at:	41	hashing and variations of this algorithm can be found at:
42	http://groups.google.com/group/comp.lang.c/browse_thread/thread/9522965e2b8d3809	42	http://groups.google.com/group/comp.lang.c/browse_thread/thread/9522965e2b8d3809
43		43
44	data server cache	44	data server cache
45	-----------------	45	-----------------
46	file driver devices refer to data servers, which are kept in a module	46	file driver devices refer to data servers, which are kept in a module
47	level cache. Its reference is held over the lifetime of the deviceid	47	level cache. Its reference is held over the lifetime of the deviceid
48	pointing to it.	48	pointing to it.
49		49
50	lseg	50	lseg
51	----	51	----
52	lseg maintains an extra reference corresponding to the NFS_LSEG_VALID	52	lseg maintains an extra reference corresponding to the NFS_LSEG_VALID
53	bit which holds it in the pnfs_layout_hdr's list. When the final lseg	53	bit which holds it in the pnfs_layout_hdr's list. When the final lseg
54	is removed from the pnfs_layout_hdr's list, the NFS_LAYOUT_DESTROYED	54	is removed from the pnfs_layout_hdr's list, the NFS_LAYOUT_DESTROYED
55	bit is set, preventing any new lsegs from being added.	55	bit is set, preventing any new lsegs from being added.
56		56
57	layout drivers	57	layout drivers
58	--------------	58	--------------
59		59
60	PNFS utilizes what is called layout drivers. The STD defines 3 basic	60	PNFS utilizes what is called layout drivers. The STD defines 3 basic
61	layout types: "files" "objects" and "blocks". For each of these types	61	layout types: "files" "objects" and "blocks". For each of these types
62	there is a layout-driver with a common function-vectors table which	62	there is a layout-driver with a common function-vectors table which
63	are called by the nfs-client pnfs-core to implement the different layout	63	are called by the nfs-client pnfs-core to implement the different layout
64	types.	64	types.
65		65
66	Files-layout-driver code is in: fs/nfs/nfs4filelayout.c && nfs4filelayoutdev.c	66	Files-layout-driver code is in: fs/nfs/nfs4filelayout.c && nfs4filelayoutdev.c
67	Objects-layout-deriver code is in: fs/nfs/objlayout/.. directory	67	Objects-layout-deriver code is in: fs/nfs/objlayout/.. directory
68	Blocks-layout-deriver code is in: fs/nfs/blocklayout/.. directory	68	Blocks-layout-deriver code is in: fs/nfs/blocklayout/.. directory
69		69
70	objects-layout setup	70	objects-layout setup
71	--------------------	71	--------------------
72		72
73	As part of the full STD implementation the objlayoutdriver.ko needs, at times,	73	As part of the full STD implementation the objlayoutdriver.ko needs, at times,
74	to automatically login to yet undiscovered iscsi/osd devices. For this the	74	to automatically login to yet undiscovered iscsi/osd devices. For this the
75	driver makes up-calles to a user-mode script called osd_login	75	driver makes up-calles to a user-mode script called osd_login
76		76
77	The path_name of the script to use is by default:	77	The path_name of the script to use is by default:
78	/sbin/osd_login.	78	/sbin/osd_login.
79	This name can be overridden by the Kernel module parameter:	79	This name can be overridden by the Kernel module parameter:
80	objlayoutdriver.osd_login_prog	80	objlayoutdriver.osd_login_prog
81		81
82	If Kernel does not find the osd_login_prog path it will zero it out	82	If Kernel does not find the osd_login_prog path it will zero it out
83	and will not attempt farther logins. An admin can then write new value	83	and will not attempt farther logins. An admin can then write new value
84	to the objlayoutdriver.osd_login_prog Kernel parameter to re-enable it.	84	to the objlayoutdriver.osd_login_prog Kernel parameter to re-enable it.
85		85
86	The /sbin/osd_login is part of the nfs-utils package, and should usually	86	The /sbin/osd_login is part of the nfs-utils package, and should usually
87	be installed on distributions that support this Kernel version.	87	be installed on distributions that support this Kernel version.
88		88
89	The API to the login script is as follows:	89	The API to the login script is as follows:
90	Usage: $0 -u <URI> -o <OSDNAME> -s <SYSTEMID>	90	Usage: $0 -u <URI> -o <OSDNAME> -s <SYSTEMID>
91	Options:	91	Options:
92	-u target uri e.g. iscsi://<ip>:<port>	92	-u target uri e.g. iscsi://<ip>:<port>
93	(allways exists)	93	(allways exists)
94	(More protocols can be defined in the future.	94	(More protocols can be defined in the future.
95	The client does not interpret this string it is	95	The client does not interpret this string it is
96	passed unchanged as recieved from the Server)	96	passed unchanged as received from the Server)
97	-o osdname of the requested target OSD	97	-o osdname of the requested target OSD
98	(Might be empty)	98	(Might be empty)
99	(A string which denotes the OSD name, there is a	99	(A string which denotes the OSD name, there is a
100	limit of 64 chars on this string)	100	limit of 64 chars on this string)
101	-s systemid of the requested target OSD	101	-s systemid of the requested target OSD
102	(Might be empty)	102	(Might be empty)
103	(This string, if not empty is always an hex	103	(This string, if not empty is always an hex
104	representation of the 20 bytes osd_system_id)	104	representation of the 20 bytes osd_system_id)
105		105
106	blocks-layout setup	106	blocks-layout setup
107	-------------------	107	-------------------
108		108
109	TODO: Document the setup needs of the blocks layout driver	109	TODO: Document the setup needs of the blocks layout driver
110		110

1	The QNX6 Filesystem	1	The QNX6 Filesystem
2	===================	2	===================
3		3
4	The qnx6fs is used by newer QNX operating system versions. (e.g. Neutrino)	4	The qnx6fs is used by newer QNX operating system versions. (e.g. Neutrino)
5	It got introduced in QNX 6.4.0 and is used default since 6.4.1.	5	It got introduced in QNX 6.4.0 and is used default since 6.4.1.
6		6
7	Option	7	Option
8	======	8	======
9		9
10	mmi_fs Mount filesystem as used for example by Audi MMI 3G system	10	mmi_fs Mount filesystem as used for example by Audi MMI 3G system
11		11
12	Specification	12	Specification
13	=============	13	=============
14		14
15	qnx6fs shares many properties with traditional Unix filesystems. It has the	15	qnx6fs shares many properties with traditional Unix filesystems. It has the
16	concepts of blocks, inodes and directories.	16	concepts of blocks, inodes and directories.
17	On QNX it is possible to create little endian and big endian qnx6 filesystems.	17	On QNX it is possible to create little endian and big endian qnx6 filesystems.
18	This feature makes it possible to create and use a different endianness fs	18	This feature makes it possible to create and use a different endianness fs
19	for the target (QNX is used on quite a range of embedded systems) plattform	19	for the target (QNX is used on quite a range of embedded systems) plattform
20	running on a different endianess.	20	running on a different endianness.
21	The Linux driver handles endianness transparently. (LE and BE)	21	The Linux driver handles endianness transparently. (LE and BE)
22		22
23	Blocks	23	Blocks
24	------	24	------
25		25
26	The space in the device or file is split up into blocks. These are a fixed	26	The space in the device or file is split up into blocks. These are a fixed
27	size of 512, 1024, 2048 or 4096, which is decided when the filesystem is	27	size of 512, 1024, 2048 or 4096, which is decided when the filesystem is
28	created.	28	created.
29	Blockpointers are 32bit, so the maximum space that can be adressed is	29	Blockpointers are 32bit, so the maximum space that can be addressed is
30	2^32 * 4096 bytes or 16TB	30	2^32 * 4096 bytes or 16TB
31		31
32	The superblocks	32	The superblocks
33	---------------	33	---------------
34		34
35	The superblock contains all global information about the filesystem.	35	The superblock contains all global information about the filesystem.
36	Each qnx6fs got two superblocks, each one having a 64bit serial number.	36	Each qnx6fs got two superblocks, each one having a 64bit serial number.
37	That serial number is used to identify the "active" superblock.	37	That serial number is used to identify the "active" superblock.
38	In write mode with reach new snapshot (after each synchronous write), the	38	In write mode with reach new snapshot (after each synchronous write), the
39	serial of the new master superblock is increased (old superblock serial + 1)	39	serial of the new master superblock is increased (old superblock serial + 1)
40		40
41	So basically the snapshot functionality is realized by an atomic final	41	So basically the snapshot functionality is realized by an atomic final
42	update of the serial number. Before updating that serial, all modifications	42	update of the serial number. Before updating that serial, all modifications
43	are done by copying all modified blocks during that specific write request	43	are done by copying all modified blocks during that specific write request
44	(or period) and building up a new (stable) filesystem structure under the	44	(or period) and building up a new (stable) filesystem structure under the
45	inactive superblock.	45	inactive superblock.
46		46
47	Each superblock holds a set of root inodes for the different filesystem	47	Each superblock holds a set of root inodes for the different filesystem
48	parts. (Inode, Bitmap and Longfilenames)	48	parts. (Inode, Bitmap and Longfilenames)
49	Each of these root nodes holds information like total size of the stored	49	Each of these root nodes holds information like total size of the stored
50	data and the adressing levels in that specific tree.	50	data and the addressing levels in that specific tree.
51	If the level value is 0, up to 16 direct blocks can be adressed by each	51	If the level value is 0, up to 16 direct blocks can be addressed by each
52	node.	52	node.
53	Level 1 adds an additional indirect adressing level where each indirect	53	Level 1 adds an additional indirect addressing level where each indirect
54	adressing block holds up to blocksize / 4 bytes pointers to data blocks.	54	addressing block holds up to blocksize / 4 bytes pointers to data blocks.
55	Level 2 adds an additional indirect adressig block level (so, already up	55	Level 2 adds an additional indirect addressing block level (so, already up
56	to 16 * 256 * 256 = 1048576 blocks that can be adressed by such a tree)a	56	to 16 * 256 * 256 = 1048576 blocks that can be addressed by such a tree).
57		57
58	Unused block pointers are always set to ~0 - regardless of root node,	58	Unused block pointers are always set to ~0 - regardless of root node,
59	indirect adressing blocks or inodes.	59	indirect addressing blocks or inodes.
60	Data leaves are always on the lowest level. So no data is stored on upper	60	Data leaves are always on the lowest level. So no data is stored on upper
61	tree levels.	61	tree levels.
62		62
63	The first Superblock is located at 0x2000. (0x2000 is the bootblock size)	63	The first Superblock is located at 0x2000. (0x2000 is the bootblock size)
64	The Audi MMI 3G first superblock directly starts at byte 0.	64	The Audi MMI 3G first superblock directly starts at byte 0.
65	Second superblock position can either be calculated from the superblock	65	Second superblock position can either be calculated from the superblock
66	information (total number of filesystem blocks) or by taking the highest	66	information (total number of filesystem blocks) or by taking the highest
67	device address, zeroing the last 3 bytes and then substracting 0x1000 from	67	device address, zeroing the last 3 bytes and then subtracting 0x1000 from
68	that address.	68	that address.
69		69
70	0x1000 is the size reserved for each superblock - regardless of the	70	0x1000 is the size reserved for each superblock - regardless of the
71	blocksize of the filesystem.	71	blocksize of the filesystem.
72		72
73	Inodes	73	Inodes
74	------	74	------
75		75
76	Each object in the filesystem is represented by an inode. (index node)	76	Each object in the filesystem is represented by an inode. (index node)
77	The inode structure contains pointers to the filesystem blocks which contain	77	The inode structure contains pointers to the filesystem blocks which contain
78	the data held in the object and all of the metadata about an object except	78	the data held in the object and all of the metadata about an object except
79	its longname. (filenames longer than 27 characters)	79	its longname. (filenames longer than 27 characters)
80	The metadata about an object includes the permissions, owner, group, flags,	80	The metadata about an object includes the permissions, owner, group, flags,
81	size, number of blocks used, access time, change time and modification time.	81	size, number of blocks used, access time, change time and modification time.
82		82
83	Object mode field is POSIX format. (which makes things easier)	83	Object mode field is POSIX format. (which makes things easier)
84		84
85	There are also pointers to the first 16 blocks, if the object data can be	85	There are also pointers to the first 16 blocks, if the object data can be
86	adressed with 16 direct blocks.	86	addressed with 16 direct blocks.
87	For more than 16 blocks an indirect adressing in form of another tree is	87	For more than 16 blocks an indirect addressing in form of another tree is
88	used. (scheme is the same as the one used for the superblock root nodes)	88	used. (scheme is the same as the one used for the superblock root nodes)
89		89
90	The filesize is stored 64bit. Inode counting starts with 1. (whilst long	90	The filesize is stored 64bit. Inode counting starts with 1. (whilst long
91	filename inodes start with 0)	91	filename inodes start with 0)
92		92
93	Directories	93	Directories
94	-----------	94	-----------
95		95
96	A directory is a filesystem object and has an inode just like a file.	96	A directory is a filesystem object and has an inode just like a file.
97	It is a specially formatted file containing records which associate each	97	It is a specially formatted file containing records which associate each
98	name with an inode number.	98	name with an inode number.
99	'.' inode number points to the directory inode	99	'.' inode number points to the directory inode
100	'..' inode number points to the parent directory inode	100	'..' inode number points to the parent directory inode
101	Eeach filename record additionally got a filename length field.	101	Eeach filename record additionally got a filename length field.
102		102
103	One special case are long filenames or subdirectory names.	103	One special case are long filenames or subdirectory names.
104	These got set a filename length field of 0xff in the corresponding directory	104	These got set a filename length field of 0xff in the corresponding directory
105	record plus the longfile inode number also stored in that record.	105	record plus the longfile inode number also stored in that record.
106	With that longfilename inode number, the longfilename tree can be walked	106	With that longfilename inode number, the longfilename tree can be walked
107	starting with the superblock longfilename root node pointers.	107	starting with the superblock longfilename root node pointers.
108		108
109	Special files	109	Special files
110	-------------	110	-------------
111		111
112	Symbolic links are also filesystem objects with inodes. They got a specific	112	Symbolic links are also filesystem objects with inodes. They got a specific
113	bit in the inode mode field identifying them as symbolic link.	113	bit in the inode mode field identifying them as symbolic link.
114	The directory entry file inode pointer points to the target file inode.	114	The directory entry file inode pointer points to the target file inode.
115		115
116	Hard links got an inode, a directory entry, but a specific mode bit set,	116	Hard links got an inode, a directory entry, but a specific mode bit set,
117	no block pointers and the directory file record pointing to the target file	117	no block pointers and the directory file record pointing to the target file
118	inode.	118	inode.
119		119
120	Character and block special devices do not exist in QNX as those files	120	Character and block special devices do not exist in QNX as those files
121	are handled by the QNX kernel/drivers and created in /dev independant of the	121	are handled by the QNX kernel/drivers and created in /dev independent of the
122	underlaying filesystem.	122	underlaying filesystem.
123		123
124	Long filenames	124	Long filenames
125	--------------	125	--------------
126		126
127	Long filenames are stored in a seperate adressing tree. The staring point	127	Long filenames are stored in a separate addressing tree. The staring point
128	is the longfilename root node in the active superblock.	128	is the longfilename root node in the active superblock.
129	Each data block (tree leaves) holds one long filename. That filename is	129	Each data block (tree leaves) holds one long filename. That filename is
130	limited to 510 bytes. The first two starting bytes are used as length field	130	limited to 510 bytes. The first two starting bytes are used as length field
131	for the actual filename.	131	for the actual filename.
132	If that structure shall fit for all allowed blocksizes, it is clear why there	132	If that structure shall fit for all allowed blocksizes, it is clear why there
133	is a limit of 510 bytes for the actual filename stored.	133	is a limit of 510 bytes for the actual filename stored.
134		134
135	Bitmap	135	Bitmap
136	------	136	------
137		137
138	The qnx6fs filesystem allocation bitmap is stored in a tree under bitmap	138	The qnx6fs filesystem allocation bitmap is stored in a tree under bitmap
139	root node in the superblock and each bit in the bitmap represents one	139	root node in the superblock and each bit in the bitmap represents one
140	filesystem block.	140	filesystem block.
141	The first block is block 0, which starts 0x1000 after superblock start.	141	The first block is block 0, which starts 0x1000 after superblock start.
142	So for a normal qnx6fs 0x3000 (bootblock + superblock) is the physical	142	So for a normal qnx6fs 0x3000 (bootblock + superblock) is the physical
143	address at which block 0 is located.	143	address at which block 0 is located.
144		144
145	Bits at the end of the last bitmap block are set to 1, if the device is	145	Bits at the end of the last bitmap block are set to 1, if the device is
146	smaller than addressing space in the bitmap.	146	smaller than addressing space in the bitmap.
147		147
148	Bitmap system area	148	Bitmap system area
149	------------------	149	------------------
150		150
151	The bitmap itself is devided into three parts.	151	The bitmap itself is devided into three parts.
152	First the system area, that is split into two halfs.	152	First the system area, that is split into two halfs.
153	Then userspace.	153	Then userspace.
154		154
155	The requirement for a static, fixed preallocated system area comes from how	155	The requirement for a static, fixed preallocated system area comes from how
156	qnx6fs deals with writes.	156	qnx6fs deals with writes.
157	Each superblock got it's own half of the system area. So superblock #1	157	Each superblock got it's own half of the system area. So superblock #1
158	always uses blocks from the lower half whilst superblock #2 just writes to	158	always uses blocks from the lower half whilst superblock #2 just writes to
159	blocks represented by the upper half bitmap system area bits.	159	blocks represented by the upper half bitmap system area bits.
160		160
161	Bitmap blocks, Inode blocks and indirect addressing blocks for those two	161	Bitmap blocks, Inode blocks and indirect addressing blocks for those two
162	tree structures are treated as system blocks.	162	tree structures are treated as system blocks.
163		163
164	The rational behind that is that a write request can work on a new snapshot	164	The rational behind that is that a write request can work on a new snapshot
165	(system area of the inactive - resp. lower serial numbered superblock) while	165	(system area of the inactive - resp. lower serial numbered superblock) while
166	at the same time there is still a complete stable filesystem structer in the	166	at the same time there is still a complete stable filesystem structer in the
167	other half of the system area.	167	other half of the system area.
168		168
169	When finished with writing (a sync write is completed, the maximum sync leap	169	When finished with writing (a sync write is completed, the maximum sync leap
170	time or a filesystem sync is requested), serial of the previously inactive	170	time or a filesystem sync is requested), serial of the previously inactive
171	superblock atomically is increased and the fs switches over to that - then	171	superblock atomically is increased and the fs switches over to that - then
172	stable declared - superblock.	172	stable declared - superblock.
173		173
174	For all data outside the system area, blocks are just copied while writing.	174	For all data outside the system area, blocks are just copied while writing.
175		175

1	Kernel driver it87	1	Kernel driver it87
2	==================	2	==================
3		3
4	Supported chips:	4	Supported chips:
5	* IT8705F	5	* IT8705F
6	Prefix: 'it87'	6	Prefix: 'it87'
7	Addresses scanned: from Super I/O config space (8 I/O ports)	7	Addresses scanned: from Super I/O config space (8 I/O ports)
8	Datasheet: Once publicly available at the ITE website, but no longer	8	Datasheet: Once publicly available at the ITE website, but no longer
9	* IT8712F	9	* IT8712F
10	Prefix: 'it8712'	10	Prefix: 'it8712'
11	Addresses scanned: from Super I/O config space (8 I/O ports)	11	Addresses scanned: from Super I/O config space (8 I/O ports)
12	Datasheet: Once publicly available at the ITE website, but no longer	12	Datasheet: Once publicly available at the ITE website, but no longer
13	* IT8716F/IT8726F	13	* IT8716F/IT8726F
14	Prefix: 'it8716'	14	Prefix: 'it8716'
15	Addresses scanned: from Super I/O config space (8 I/O ports)	15	Addresses scanned: from Super I/O config space (8 I/O ports)
16	Datasheet: Once publicly available at the ITE website, but no longer	16	Datasheet: Once publicly available at the ITE website, but no longer
17	* IT8718F	17	* IT8718F
18	Prefix: 'it8718'	18	Prefix: 'it8718'
19	Addresses scanned: from Super I/O config space (8 I/O ports)	19	Addresses scanned: from Super I/O config space (8 I/O ports)
20	Datasheet: Once publicly available at the ITE website, but no longer	20	Datasheet: Once publicly available at the ITE website, but no longer
21	* IT8720F	21	* IT8720F
22	Prefix: 'it8720'	22	Prefix: 'it8720'
23	Addresses scanned: from Super I/O config space (8 I/O ports)	23	Addresses scanned: from Super I/O config space (8 I/O ports)
24	Datasheet: Not publicly available	24	Datasheet: Not publicly available
25	* IT8721F/IT8758E	25	* IT8721F/IT8758E
26	Prefix: 'it8721'	26	Prefix: 'it8721'
27	Addresses scanned: from Super I/O config space (8 I/O ports)	27	Addresses scanned: from Super I/O config space (8 I/O ports)
28	Datasheet: Not publicly available	28	Datasheet: Not publicly available
29	* IT8728F	29	* IT8728F
30	Prefix: 'it8728'	30	Prefix: 'it8728'
31	Addresses scanned: from Super I/O config space (8 I/O ports)	31	Addresses scanned: from Super I/O config space (8 I/O ports)
32	Datasheet: Not publicly available	32	Datasheet: Not publicly available
33	* SiS950 [clone of IT8705F]	33	* SiS950 [clone of IT8705F]
34	Prefix: 'it87'	34	Prefix: 'it87'
35	Addresses scanned: from Super I/O config space (8 I/O ports)	35	Addresses scanned: from Super I/O config space (8 I/O ports)
36	Datasheet: No longer be available	36	Datasheet: No longer be available
37		37
38	Authors:	38	Authors:
39	Christophe Gauthron	39	Christophe Gauthron
40	Jean Delvare <khali@linux-fr.org>	40	Jean Delvare <khali@linux-fr.org>
41		41
42		42
43	Module Parameters	43	Module Parameters
44	-----------------	44	-----------------
45		45
46	* update_vbat: int	46	* update_vbat: int
47		47
48	0 if vbat should report power on value, 1 if vbat should be updated after	48	0 if vbat should report power on value, 1 if vbat should be updated after
49	each read. Default is 0. On some boards the battery voltage is provided	49	each read. Default is 0. On some boards the battery voltage is provided
50	by either the battery or the onboard power supply. Only the first reading	50	by either the battery or the onboard power supply. Only the first reading
51	at power on will be the actual battery voltage (which the chip does	51	at power on will be the actual battery voltage (which the chip does
52	automatically). On other boards the battery voltage is always fed to	52	automatically). On other boards the battery voltage is always fed to
53	the chip so can be read at any time. Excessive reading may decrease	53	the chip so can be read at any time. Excessive reading may decrease
54	battery life but no information is given in the datasheet.	54	battery life but no information is given in the datasheet.
55		55
56	* fix_pwm_polarity int	56	* fix_pwm_polarity int
57		57
58	Force PWM polarity to active high (DANGEROUS). Some chips are	58	Force PWM polarity to active high (DANGEROUS). Some chips are
59	misconfigured by BIOS - PWM values would be inverted. This option tries	59	misconfigured by BIOS - PWM values would be inverted. This option tries
60	to fix this. Please contact your BIOS manufacturer and ask him for fix.	60	to fix this. Please contact your BIOS manufacturer and ask him for fix.
61		61
62		62
63	Hardware Interfaces	63	Hardware Interfaces
64	-------------------	64	-------------------
65		65
66	All the chips suported by this driver are LPC Super-I/O chips, accessed	66	All the chips supported by this driver are LPC Super-I/O chips, accessed
67	through the LPC bus (ISA-like I/O ports). The IT8712F additionally has an	67	through the LPC bus (ISA-like I/O ports). The IT8712F additionally has an
68	SMBus interface to the hardware monitoring functions. This driver no	68	SMBus interface to the hardware monitoring functions. This driver no
69	longer supports this interface though, as it is slower and less reliable	69	longer supports this interface though, as it is slower and less reliable
70	than the ISA access, and was only available on a small number of	70	than the ISA access, and was only available on a small number of
71	motherboard models.	71	motherboard models.
72		72
73		73
74	Description	74	Description
75	-----------	75	-----------
76		76
77	This driver implements support for the IT8705F, IT8712F, IT8716F,	77	This driver implements support for the IT8705F, IT8712F, IT8716F,
78	IT8718F, IT8720F, IT8721F, IT8726F, IT8728F, IT8758E and SiS950 chips.	78	IT8718F, IT8720F, IT8721F, IT8726F, IT8728F, IT8758E and SiS950 chips.
79		79
80	These chips are 'Super I/O chips', supporting floppy disks, infrared ports,	80	These chips are 'Super I/O chips', supporting floppy disks, infrared ports,
81	joysticks and other miscellaneous stuff. For hardware monitoring, they	81	joysticks and other miscellaneous stuff. For hardware monitoring, they
82	include an 'environment controller' with 3 temperature sensors, 3 fan	82	include an 'environment controller' with 3 temperature sensors, 3 fan
83	rotation speed sensors, 8 voltage sensors, associated alarms, and chassis	83	rotation speed sensors, 8 voltage sensors, associated alarms, and chassis
84	intrusion detection.	84	intrusion detection.
85		85
86	The IT8712F and IT8716F additionally feature VID inputs, used to report	86	The IT8712F and IT8716F additionally feature VID inputs, used to report
87	the Vcore voltage of the processor. The early IT8712F have 5 VID pins,	87	the Vcore voltage of the processor. The early IT8712F have 5 VID pins,
88	the IT8716F and late IT8712F have 6. They are shared with other functions	88	the IT8716F and late IT8712F have 6. They are shared with other functions
89	though, so the functionality may not be available on a given system.	89	though, so the functionality may not be available on a given system.
90		90
91	The IT8718F and IT8720F also features VID inputs (up to 8 pins) but the value	91	The IT8718F and IT8720F also features VID inputs (up to 8 pins) but the value
92	is stored in the Super-I/O configuration space. Due to technical limitations,	92	is stored in the Super-I/O configuration space. Due to technical limitations,
93	this value can currently only be read once at initialization time, so	93	this value can currently only be read once at initialization time, so
94	the driver won't notice and report changes in the VID value. The two	94	the driver won't notice and report changes in the VID value. The two
95	upper VID bits share their pins with voltage inputs (in5 and in6) so you	95	upper VID bits share their pins with voltage inputs (in5 and in6) so you
96	can't have both on a given board.	96	can't have both on a given board.
97		97
98	The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E and later IT8712F revisions	98	The IT8716F, IT8718F, IT8720F, IT8721F/IT8758E and later IT8712F revisions
99	have support for 2 additional fans. The additional fans are supported by the	99	have support for 2 additional fans. The additional fans are supported by the
100	driver.	100	driver.
101		101
102	The IT8716F, IT8718F, IT8720F and IT8721F/IT8758E, and late IT8712F and	102	The IT8716F, IT8718F, IT8720F and IT8721F/IT8758E, and late IT8712F and
103	IT8705F also have optional 16-bit tachometer counters for fans 1 to 3. This	103	IT8705F also have optional 16-bit tachometer counters for fans 1 to 3. This
104	is better (no more fan clock divider mess) but not compatible with the older	104	is better (no more fan clock divider mess) but not compatible with the older
105	chips and revisions. The 16-bit tachometer mode is enabled by the driver when	105	chips and revisions. The 16-bit tachometer mode is enabled by the driver when
106	one of the above chips is detected.	106	one of the above chips is detected.
107		107
108	The IT8726F is just bit enhanced IT8716F with additional hardware	108	The IT8726F is just bit enhanced IT8716F with additional hardware
109	for AMD power sequencing. Therefore the chip will appear as IT8716F	109	for AMD power sequencing. Therefore the chip will appear as IT8716F
110	to userspace applications.	110	to userspace applications.
111		111
112	The IT8728F is considered compatible with the IT8721F, until a datasheet	112	The IT8728F is considered compatible with the IT8721F, until a datasheet
113	becomes available (hopefully.)	113	becomes available (hopefully.)
114		114
115	Temperatures are measured in degrees Celsius. An alarm is triggered once	115	Temperatures are measured in degrees Celsius. An alarm is triggered once
116	when the Overtemperature Shutdown limit is crossed.	116	when the Overtemperature Shutdown limit is crossed.
117		117
118	Fan rotation speeds are reported in RPM (rotations per minute). An alarm is	118	Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
119	triggered if the rotation speed has dropped below a programmable limit. When	119	triggered if the rotation speed has dropped below a programmable limit. When
120	16-bit tachometer counters aren't used, fan readings can be divided by	120	16-bit tachometer counters aren't used, fan readings can be divided by
121	a programmable divider (1, 2, 4 or 8) to give the readings more range or	121	a programmable divider (1, 2, 4 or 8) to give the readings more range or
122	accuracy. With a divider of 2, the lowest representable value is around	122	accuracy. With a divider of 2, the lowest representable value is around
123	2600 RPM. Not all RPM values can accurately be represented, so some rounding	123	2600 RPM. Not all RPM values can accurately be represented, so some rounding
124	is done.	124	is done.
125		125
126	Voltage sensors (also known as IN sensors) report their values in volts. An	126	Voltage sensors (also known as IN sensors) report their values in volts. An
127	alarm is triggered if the voltage has crossed a programmable minimum or	127	alarm is triggered if the voltage has crossed a programmable minimum or
128	maximum limit. Note that minimum in this case always means 'closest to	128	maximum limit. Note that minimum in this case always means 'closest to
129	zero'; this is important for negative voltage measurements. All voltage	129	zero'; this is important for negative voltage measurements. All voltage
130	inputs can measure voltages between 0 and 4.08 volts, with a resolution of	130	inputs can measure voltages between 0 and 4.08 volts, with a resolution of
131	0.016 volt (except IT8721F/IT8758E and IT8728F: 0.012 volt.) The battery	131	0.016 volt (except IT8721F/IT8758E and IT8728F: 0.012 volt.) The battery
132	voltage in8 does not have limit registers.	132	voltage in8 does not have limit registers.
133		133
134	On the IT8721F/IT8758E, some voltage inputs are internal and scaled inside	134	On the IT8721F/IT8758E, some voltage inputs are internal and scaled inside
135	the chip (in7, in8 and optionally in3). The driver handles this transparently	135	the chip (in7, in8 and optionally in3). The driver handles this transparently
136	so user-space doesn't have to care.	136	so user-space doesn't have to care.
137		137
138	The VID lines (IT8712F/IT8716F/IT8718F/IT8720F) encode the core voltage value:	138	The VID lines (IT8712F/IT8716F/IT8718F/IT8720F) encode the core voltage value:
139	the voltage level your processor should work with. This is hardcoded by	139	the voltage level your processor should work with. This is hardcoded by
140	the mainboard and/or processor itself. It is a value in volts.	140	the mainboard and/or processor itself. It is a value in volts.
141		141
142	If an alarm triggers, it will remain triggered until the hardware register	142	If an alarm triggers, it will remain triggered until the hardware register
143	is read at least once. This means that the cause for the alarm may already	143	is read at least once. This means that the cause for the alarm may already
144	have disappeared! Note that in the current implementation, all hardware	144	have disappeared! Note that in the current implementation, all hardware
145	registers are read whenever any data is read (unless it is less than 1.5	145	registers are read whenever any data is read (unless it is less than 1.5
146	seconds since the last update). This means that you can easily miss	146	seconds since the last update). This means that you can easily miss
147	once-only alarms.	147	once-only alarms.
148		148
149	Out-of-limit readings can also result in beeping, if the chip is properly	149	Out-of-limit readings can also result in beeping, if the chip is properly
150	wired and configured. Beeping can be enabled or disabled per sensor type	150	wired and configured. Beeping can be enabled or disabled per sensor type
151	(temperatures, voltages and fans.)	151	(temperatures, voltages and fans.)
152		152
153	The IT87xx only updates its values each 1.5 seconds; reading it more often	153	The IT87xx only updates its values each 1.5 seconds; reading it more often
154	will do no harm, but will return 'old' values.	154	will do no harm, but will return 'old' values.
155		155
156	To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2,	156	To change sensor N to a thermistor, 'echo 4 > tempN_type' where N is 1, 2,
157	or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'.	157	or 3. To change sensor N to a thermal diode, 'echo 3 > tempN_type'.
158	Give 0 for unused sensor. Any other value is invalid. To configure this at	158	Give 0 for unused sensor. Any other value is invalid. To configure this at
159	startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor;	159	startup, consult lm_sensors's /etc/sensors.conf. (4 = thermistor;
160	3 = thermal diode)	160	3 = thermal diode)
161		161
162		162
163	Fan speed control	163	Fan speed control
164	-----------------	164	-----------------
165		165
166	The fan speed control features are limited to manual PWM mode. Automatic	166	The fan speed control features are limited to manual PWM mode. Automatic
167	"Smart Guardian" mode control handling is only implemented for older chips	167	"Smart Guardian" mode control handling is only implemented for older chips
168	(see below.) However if you want to go for "manual mode" just write 1 to	168	(see below.) However if you want to go for "manual mode" just write 1 to
169	pwmN_enable.	169	pwmN_enable.
170		170
171	If you are only able to control the fan speed with very small PWM values,	171	If you are only able to control the fan speed with very small PWM values,
172	try lowering the PWM base frequency (pwm1_freq). Depending on the fan,	172	try lowering the PWM base frequency (pwm1_freq). Depending on the fan,
173	it may give you a somewhat greater control range. The same frequency is	173	it may give you a somewhat greater control range. The same frequency is
174	used to drive all fan outputs, which is why pwm2_freq and pwm3_freq are	174	used to drive all fan outputs, which is why pwm2_freq and pwm3_freq are
175	read-only.	175	read-only.
176		176
177		177
178	Automatic fan speed control (old interface)	178	Automatic fan speed control (old interface)
179	-------------------------------------------	179	-------------------------------------------
180		180
181	The driver supports the old interface to automatic fan speed control	181	The driver supports the old interface to automatic fan speed control
182	which is implemented by IT8705F chips up to revision F and IT8712F	182	which is implemented by IT8705F chips up to revision F and IT8712F
183	chips up to revision G.	183	chips up to revision G.
184		184
185	This interface implements 4 temperature vs. PWM output trip points.	185	This interface implements 4 temperature vs. PWM output trip points.
186	The PWM output of trip point 4 is always the maximum value (fan running	186	The PWM output of trip point 4 is always the maximum value (fan running
187	at full speed) while the PWM output of the other 3 trip points can be	187	at full speed) while the PWM output of the other 3 trip points can be
188	freely chosen. The temperature of all 4 trip points can be freely chosen.	188	freely chosen. The temperature of all 4 trip points can be freely chosen.
189	Additionally, trip point 1 has an hysteresis temperature attached, to	189	Additionally, trip point 1 has an hysteresis temperature attached, to
190	prevent fast switching between fan on and off.	190	prevent fast switching between fan on and off.
191		191
192	The chip automatically computes the PWM output value based on the input	192	The chip automatically computes the PWM output value based on the input
193	temperature, based on this simple rule: if the temperature value is	193	temperature, based on this simple rule: if the temperature value is
194	between trip point N and trip point N+1 then the PWM output value is	194	between trip point N and trip point N+1 then the PWM output value is
195	the one of trip point N. The automatic control mode is less flexible	195	the one of trip point N. The automatic control mode is less flexible
196	than the manual control mode, but it reacts faster, is more robust and	196	than the manual control mode, but it reacts faster, is more robust and
197	doesn't use CPU cycles.	197	doesn't use CPU cycles.
198		198
199	Trip points must be set properly before switching to automatic fan speed	199	Trip points must be set properly before switching to automatic fan speed
200	control mode. The driver will perform basic integrity checks before	200	control mode. The driver will perform basic integrity checks before
201	actually switching to automatic control mode.	201	actually switching to automatic control mode.
202		202

1	okay, here are some hints for debugging the lower-level parts of	1	okay, here are some hints for debugging the lower-level parts of
2	linux/parisc.	2	linux/parisc.
3		3
4		4
5	1. Absolute addresses	5	1. Absolute addresses
6		6
7	A lot of the assembly code currently runs in real mode, which means	7	A lot of the assembly code currently runs in real mode, which means
8	absolute addresses are used instead of virtual addresses as in the	8	absolute addresses are used instead of virtual addresses as in the
9	rest of the kernel. To translate an absolute address to a virtual	9	rest of the kernel. To translate an absolute address to a virtual
10	address you can lookup in System.map, add __PAGE_OFFSET (0x10000000	10	address you can lookup in System.map, add __PAGE_OFFSET (0x10000000
11	currently).	11	currently).
12		12
13		13
14	2. HPMCs	14	2. HPMCs
15		15
16	When real-mode code tries to access non-existent memory, you'll get	16	When real-mode code tries to access non-existent memory, you'll get
17	an HPMC instead of a kernel oops. To debug an HPMC, try to find	17	an HPMC instead of a kernel oops. To debug an HPMC, try to find
18	the System Responder/Requestor addresses. The System Requestor	18	the System Responder/Requestor addresses. The System Requestor
19	address should match (one of the) processor HPAs (high addresses in	19	address should match (one of the) processor HPAs (high addresses in
20	the I/O range); the System Responder address is the address real-mode	20	the I/O range); the System Responder address is the address real-mode
21	code tried to access.	21	code tried to access.
22		22
23	Typical values for the System Responder address are addresses larger	23	Typical values for the System Responder address are addresses larger
24	than __PAGE_OFFSET (0x10000000) which mean a virtual address didn't	24	than __PAGE_OFFSET (0x10000000) which mean a virtual address didn't
25	get translated to a physical address before real-mode code tried to	25	get translated to a physical address before real-mode code tried to
26	access it.	26	access it.
27		27
28		28
29	3. Q bit fun	29	3. Q bit fun
30		30
31	Certain, very critical code has to clear the Q bit in the PSW. What	31	Certain, very critical code has to clear the Q bit in the PSW. What
32	happens when the Q bit is cleared is the CPU does not update the	32	happens when the Q bit is cleared is the CPU does not update the
33	registers interruption handlers read to find out where the machine	33	registers interruption handlers read to find out where the machine
34	was interrupted - so if you get an interruption between the instruction	34	was interrupted - so if you get an interruption between the instruction
35	that clears the Q bit and the RFI that sets it again you don't know	35	that clears the Q bit and the RFI that sets it again you don't know
36	where exactly it happened. If you're lucky the IAOQ will point to the	36	where exactly it happened. If you're lucky the IAOQ will point to the
37	instrucion that cleared the Q bit, if you're not it points anywhere	37	instruction that cleared the Q bit, if you're not it points anywhere
38	at all. Usually Q bit problems will show themselves in unexplainable	38	at all. Usually Q bit problems will show themselves in unexplainable
39	system hangs or running off the end of physical memory.	39	system hangs or running off the end of physical memory.
40		40

1	compress_offload.txt	1	compress_offload.txt
2	=====================	2	=====================
3	Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>	3	Pierre-Louis.Bossart <pierre-louis.bossart@linux.intel.com>
4	Vinod Koul <vinod.koul@linux.intel.com>	4	Vinod Koul <vinod.koul@linux.intel.com>
5		5
6	Overview	6	Overview
7		7
8	Since its early days, the ALSA API was defined with PCM support or	8	Since its early days, the ALSA API was defined with PCM support or
9	constant bitrates payloads such as IEC61937 in mind. Arguments and	9	constant bitrates payloads such as IEC61937 in mind. Arguments and
10	returned values in frames are the norm, making it a challenge to	10	returned values in frames are the norm, making it a challenge to
11	extend the existing API to compressed data streams.	11	extend the existing API to compressed data streams.
12		12
13	In recent years, audio digital signal processors (DSP) were integrated	13	In recent years, audio digital signal processors (DSP) were integrated
14	in system-on-chip designs, and DSPs are also integrated in audio	14	in system-on-chip designs, and DSPs are also integrated in audio
15	codecs. Processing compressed data on such DSPs results in a dramatic	15	codecs. Processing compressed data on such DSPs results in a dramatic
16	reduction of power consumption compared to host-based	16	reduction of power consumption compared to host-based
17	processing. Support for such hardware has not been very good in Linux,	17	processing. Support for such hardware has not been very good in Linux,
18	mostly because of a lack of a generic API available in the mainline	18	mostly because of a lack of a generic API available in the mainline
19	kernel.	19	kernel.
20		20
21	Rather than requiring a compability break with an API change of the	21	Rather than requiring a compatibility break with an API change of the
22	ALSA PCM interface, a new 'Compressed Data' API is introduced to	22	ALSA PCM interface, a new 'Compressed Data' API is introduced to
23	provide a control and data-streaming interface for audio DSPs.	23	provide a control and data-streaming interface for audio DSPs.
24		24
25	The design of this API was inspired by the 2-year experience with the	25	The design of this API was inspired by the 2-year experience with the
26	Intel Moorestown SOC, with many corrections required to upstream the	26	Intel Moorestown SOC, with many corrections required to upstream the
27	API in the mainline kernel instead of the staging tree and make it	27	API in the mainline kernel instead of the staging tree and make it
28	usable by others.	28	usable by others.
29		29
30	Requirements	30	Requirements
31		31
32	The main requirements are:	32	The main requirements are:
33		33
34	- separation between byte counts and time. Compressed formats may have	34	- separation between byte counts and time. Compressed formats may have
35	a header per file, per frame, or no header at all. The payload size	35	a header per file, per frame, or no header at all. The payload size
36	may vary from frame-to-frame. As a result, it is not possible to	36	may vary from frame-to-frame. As a result, it is not possible to
37	estimate reliably the duration of audio buffers when handling	37	estimate reliably the duration of audio buffers when handling
38	compressed data. Dedicated mechanisms are required to allow for	38	compressed data. Dedicated mechanisms are required to allow for
39	reliable audio-video synchronization, which requires precise	39	reliable audio-video synchronization, which requires precise
40	reporting of the number of samples rendered at any given time.	40	reporting of the number of samples rendered at any given time.
41		41
42	- Handling of multiple formats. PCM data only requires a specification	42	- Handling of multiple formats. PCM data only requires a specification
43	of the sampling rate, number of channels and bits per sample. In	43	of the sampling rate, number of channels and bits per sample. In
44	contrast, compressed data comes in a variety of formats. Audio DSPs	44	contrast, compressed data comes in a variety of formats. Audio DSPs
45	may also provide support for a limited number of audio encoders and	45	may also provide support for a limited number of audio encoders and
46	decoders embedded in firmware, or may support more choices through	46	decoders embedded in firmware, or may support more choices through
47	dynamic download of libraries.	47	dynamic download of libraries.
48		48
49	- Focus on main formats. This API provides support for the most	49	- Focus on main formats. This API provides support for the most
50	popular formats used for audio and video capture and playback. It is	50	popular formats used for audio and video capture and playback. It is
51	likely that as audio compression technology advances, new formats	51	likely that as audio compression technology advances, new formats
52	will be added.	52	will be added.
53		53
54	- Handling of multiple configurations. Even for a given format like	54	- Handling of multiple configurations. Even for a given format like
55	AAC, some implementations may support AAC multichannel but HE-AAC	55	AAC, some implementations may support AAC multichannel but HE-AAC
56	stereo. Likewise WMA10 level M3 may require too much memory and cpu	56	stereo. Likewise WMA10 level M3 may require too much memory and cpu
57	cycles. The new API needs to provide a generic way of listing these	57	cycles. The new API needs to provide a generic way of listing these
58	formats.	58	formats.
59		59
60	- Rendering/Grabbing only. This API does not provide any means of	60	- Rendering/Grabbing only. This API does not provide any means of
61	hardware acceleration, where PCM samples are provided back to	61	hardware acceleration, where PCM samples are provided back to
62	user-space for additional processing. This API focuses instead on	62	user-space for additional processing. This API focuses instead on
63	streaming compressed data to a DSP, with the assumption that the	63	streaming compressed data to a DSP, with the assumption that the
64	decoded samples are routed to a physical output or logical back-end.	64	decoded samples are routed to a physical output or logical back-end.
65		65
66	- Complexity hiding. Existing user-space multimedia frameworks all	66	- Complexity hiding. Existing user-space multimedia frameworks all
67	have existing enums/structures for each compressed format. This new	67	have existing enums/structures for each compressed format. This new
68	API assumes the existence of a platform-specific compatibility layer	68	API assumes the existence of a platform-specific compatibility layer
69	to expose, translate and make use of the capabilities of the audio	69	to expose, translate and make use of the capabilities of the audio
70	DSP, eg. Android HAL or PulseAudio sinks. By construction, regular	70	DSP, eg. Android HAL or PulseAudio sinks. By construction, regular
71	applications are not supposed to make use of this API.	71	applications are not supposed to make use of this API.
72		72
73		73
74	Design	74	Design
75		75
76	The new API shares a number of concepts with with the PCM API for flow	76	The new API shares a number of concepts with with the PCM API for flow
77	control. Start, pause, resume, drain and stop commands have the same	77	control. Start, pause, resume, drain and stop commands have the same
78	semantics no matter what the content is.	78	semantics no matter what the content is.
79		79
80	The concept of memory ring buffer divided in a set of fragments is	80	The concept of memory ring buffer divided in a set of fragments is
81	borrowed from the ALSA PCM API. However, only sizes in bytes can be	81	borrowed from the ALSA PCM API. However, only sizes in bytes can be
82	specified.	82	specified.
83		83
84	Seeks/trick modes are assumed to be handled by the host.	84	Seeks/trick modes are assumed to be handled by the host.
85		85
86	The notion of rewinds/forwards is not supported. Data committed to the	86	The notion of rewinds/forwards is not supported. Data committed to the
87	ring buffer cannot be invalidated, except when dropping all buffers.	87	ring buffer cannot be invalidated, except when dropping all buffers.
88		88
89	The Compressed Data API does not make any assumptions on how the data	89	The Compressed Data API does not make any assumptions on how the data
90	is transmitted to the audio DSP. DMA transfers from main memory to an	90	is transmitted to the audio DSP. DMA transfers from main memory to an
91	embedded audio cluster or to a SPI interface for external DSPs are	91	embedded audio cluster or to a SPI interface for external DSPs are
92	possible. As in the ALSA PCM case, a core set of routines is exposed;	92	possible. As in the ALSA PCM case, a core set of routines is exposed;
93	each driver implementer will have to write support for a set of	93	each driver implementer will have to write support for a set of
94	mandatory routines and possibly make use of optional ones.	94	mandatory routines and possibly make use of optional ones.
95		95
96	The main additions are	96	The main additions are
97		97
98	- get_caps	98	- get_caps
99	This routine returns the list of audio formats supported. Querying the	99	This routine returns the list of audio formats supported. Querying the
100	codecs on a capture stream will return encoders, decoders will be	100	codecs on a capture stream will return encoders, decoders will be
101	listed for playback streams.	101	listed for playback streams.
102		102
103	- get_codec_caps For each codec, this routine returns a list of	103	- get_codec_caps For each codec, this routine returns a list of
104	capabilities. The intent is to make sure all the capabilities	104	capabilities. The intent is to make sure all the capabilities
105	correspond to valid settings, and to minimize the risks of	105	correspond to valid settings, and to minimize the risks of
106	configuration failures. For example, for a complex codec such as AAC,	106	configuration failures. For example, for a complex codec such as AAC,
107	the number of channels supported may depend on a specific profile. If	107	the number of channels supported may depend on a specific profile. If
108	the capabilities were exposed with a single descriptor, it may happen	108	the capabilities were exposed with a single descriptor, it may happen
109	that a specific combination of profiles/channels/formats may not be	109	that a specific combination of profiles/channels/formats may not be
110	supported. Likewise, embedded DSPs have limited memory and cpu cycles,	110	supported. Likewise, embedded DSPs have limited memory and cpu cycles,
111	it is likely that some implementations make the list of capabilities	111	it is likely that some implementations make the list of capabilities
112	dynamic and dependent on existing workloads. In addition to codec	112	dynamic and dependent on existing workloads. In addition to codec
113	settings, this routine returns the minimum buffer size handled by the	113	settings, this routine returns the minimum buffer size handled by the
114	implementation. This information can be a function of the DMA buffer	114	implementation. This information can be a function of the DMA buffer
115	sizes, the number of bytes required to synchronize, etc, and can be	115	sizes, the number of bytes required to synchronize, etc, and can be
116	used by userspace to define how much needs to be written in the ring	116	used by userspace to define how much needs to be written in the ring
117	buffer before playback can start.	117	buffer before playback can start.
118		118
119	- set_params	119	- set_params
120	This routine sets the configuration chosen for a specific codec. The	120	This routine sets the configuration chosen for a specific codec. The
121	most important field in the parameters is the codec type; in most	121	most important field in the parameters is the codec type; in most
122	cases decoders will ignore other fields, while encoders will strictly	122	cases decoders will ignore other fields, while encoders will strictly
123	comply to the settings	123	comply to the settings
124		124
125	- get_params	125	- get_params
126	This routines returns the actual settings used by the DSP. Changes to	126	This routines returns the actual settings used by the DSP. Changes to
127	the settings should remain the exception.	127	the settings should remain the exception.
128		128
129	- get_timestamp	129	- get_timestamp
130	The timestamp becomes a multiple field structure. It lists the number	130	The timestamp becomes a multiple field structure. It lists the number
131	of bytes transferred, the number of samples processed and the number	131	of bytes transferred, the number of samples processed and the number
132	of samples rendered/grabbed. All these values can be used to determine	132	of samples rendered/grabbed. All these values can be used to determine
133	the avarage bitrate, figure out if the ring buffer needs to be	133	the avarage bitrate, figure out if the ring buffer needs to be
134	refilled or the delay due to decoding/encoding/io on the DSP.	134	refilled or the delay due to decoding/encoding/io on the DSP.
135		135
136	Note that the list of codecs/profiles/modes was derived from the	136	Note that the list of codecs/profiles/modes was derived from the
137	OpenMAX AL specification instead of reinventing the wheel.	137	OpenMAX AL specification instead of reinventing the wheel.
138	Modifications include:	138	Modifications include:
139	- Addition of FLAC and IEC formats	139	- Addition of FLAC and IEC formats
140	- Merge of encoder/decoder capabilities	140	- Merge of encoder/decoder capabilities
141	- Profiles/modes listed as bitmasks to make descriptors more compact	141	- Profiles/modes listed as bitmasks to make descriptors more compact
142	- Addition of set_params for decoders (missing in OpenMAX AL)	142	- Addition of set_params for decoders (missing in OpenMAX AL)
143	- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)	143	- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)
144	- Addition of format information for WMA	144	- Addition of format information for WMA
145	- Addition of encoding options when required (derived from OpenMAX IL)	145	- Addition of encoding options when required (derived from OpenMAX IL)
146	- Addition of rateControlSupported (missing in OpenMAX AL)	146	- Addition of rateControlSupported (missing in OpenMAX AL)
147		147
148	Not supported:	148	Not supported:
149		149
150	- Support for VoIP/circuit-switched calls is not the target of this	150	- Support for VoIP/circuit-switched calls is not the target of this
151	API. Support for dynamic bit-rate changes would require a tight	151	API. Support for dynamic bit-rate changes would require a tight
152	coupling between the DSP and the host stack, limiting power savings.	152	coupling between the DSP and the host stack, limiting power savings.
153		153
154	- Packet-loss concealment is not supported. This would require an	154	- Packet-loss concealment is not supported. This would require an
155	additional interface to let the decoder synthesize data when frames	155	additional interface to let the decoder synthesize data when frames
156	are lost during transmission. This may be added in the future.	156	are lost during transmission. This may be added in the future.
157		157
158	- Volume control/routing is not handled by this API. Devices exposing a	158	- Volume control/routing is not handled by this API. Devices exposing a
159	compressed data interface will be considered as regular ALSA devices;	159	compressed data interface will be considered as regular ALSA devices;
160	volume changes and routing information will be provided with regular	160	volume changes and routing information will be provided with regular
161	ALSA kcontrols.	161	ALSA kcontrols.
162		162
163	- Embedded audio effects. Such effects should be enabled in the same	163	- Embedded audio effects. Such effects should be enabled in the same
164	manner, no matter if the input was PCM or compressed.	164	manner, no matter if the input was PCM or compressed.
165		165
166	- multichannel IEC encoding. Unclear if this is required.	166	- multichannel IEC encoding. Unclear if this is required.
167		167
168	- Encoding/decoding acceleration is not supported as mentioned	168	- Encoding/decoding acceleration is not supported as mentioned
169	above. It is possible to route the output of a decoder to a capture	169	above. It is possible to route the output of a decoder to a capture
170	stream, or even implement transcoding capabilities. This routing	170	stream, or even implement transcoding capabilities. This routing
171	would be enabled with ALSA kcontrols.	171	would be enabled with ALSA kcontrols.
172		172
173	- Audio policy/resource management. This API does not provide any	173	- Audio policy/resource management. This API does not provide any
174	hooks to query the utilization of the audio DSP, nor any premption	174	hooks to query the utilization of the audio DSP, nor any premption
175	mechanisms.	175	mechanisms.
176		176
177	- No notion of underun/overrun. Since the bytes written are compressed	177	- No notion of underun/overrun. Since the bytes written are compressed
178	in nature and data written/read doesn't translate directly to	178	in nature and data written/read doesn't translate directly to
179	rendered output in time, this does not deal with underrun/overun and	179	rendered output in time, this does not deal with underrun/overun and
180	maybe dealt in user-library	180	maybe dealt in user-library
181		181
182	Credits:	182	Credits:
183	- Mark Brown and Liam Girdwood for discussions on the need for this API	183	- Mark Brown and Liam Girdwood for discussions on the need for this API
184	- Harsha Priya for her work on intel_sst compressed API	184	- Harsha Priya for her work on intel_sst compressed API
185	- Rakesh Ughreja for valuable feedback	185	- Rakesh Ughreja for valuable feedback
186	- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for	186	- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for
187	demonstrating and quantifying the benefits of audio offload on a	187	demonstrating and quantifying the benefits of audio offload on a
188	real platform.	188	real platform.
189		189