aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorRusty Russell <rusty@rustcorp.com.au>2008-12-31 07:35:57 -0500
committerRusty Russell <rusty@rustcorp.com.au>2008-12-31 07:35:57 -0500
commit2ca1a615835d9f4990f42102ab1f2ef434e7e89c (patch)
tree726cf3d5f29a6c66c44e4bd68e7ebed2fd83d059 /Documentation
parente12f0102ac81d660c9f801d0a0e10ccf4537a9de (diff)
parent6a94cb73064c952255336cc57731904174b2c58f (diff)
Merge branch 'master' of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6
Conflicts: arch/x86/kernel/io_apic.c
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/RCU/00-INDEX2
-rw-r--r--Documentation/RCU/trace.txt413
-rw-r--r--Documentation/arm/pxa/mfp.txt286
-rw-r--r--Documentation/block/biodoc.txt6
-rw-r--r--Documentation/dvb/technisat.txt69
-rw-r--r--Documentation/fb/pxafb.txt92
-rw-r--r--Documentation/filesystems/xfs.txt4
-rw-r--r--Documentation/lguest/lguest.c66
-rw-r--r--Documentation/lockstat.txt51
-rw-r--r--Documentation/scsi/cxgb3i.txt85
-rw-r--r--Documentation/video4linux/API.html43
-rw-r--r--Documentation/video4linux/CARDLIST.bttv7
-rw-r--r--Documentation/video4linux/CARDLIST.cx238851
-rw-r--r--Documentation/video4linux/CARDLIST.cx885
-rw-r--r--Documentation/video4linux/CARDLIST.em28xx9
-rw-r--r--Documentation/video4linux/CARDLIST.saa71343
-rw-r--r--Documentation/video4linux/README.cx888
-rw-r--r--Documentation/video4linux/gspca.txt19
-rw-r--r--Documentation/video4linux/v4l2-framework.txt520
19 files changed, 1575 insertions, 114 deletions
diff --git a/Documentation/RCU/00-INDEX b/Documentation/RCU/00-INDEX
index 461481dfb7c3..7dc0695a8f90 100644
--- a/Documentation/RCU/00-INDEX
+++ b/Documentation/RCU/00-INDEX
@@ -16,6 +16,8 @@ RTFP.txt
16 - List of RCU papers (bibliography) going back to 1980. 16 - List of RCU papers (bibliography) going back to 1980.
17torture.txt 17torture.txt
18 - RCU Torture Test Operation (CONFIG_RCU_TORTURE_TEST) 18 - RCU Torture Test Operation (CONFIG_RCU_TORTURE_TEST)
19trace.txt
20 - CONFIG_RCU_TRACE debugfs files and formats
19UP.txt 21UP.txt
20 - RCU on Uniprocessor Systems 22 - RCU on Uniprocessor Systems
21whatisRCU.txt 23whatisRCU.txt
diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt
new file mode 100644
index 000000000000..068848240a8b
--- /dev/null
+++ b/Documentation/RCU/trace.txt
@@ -0,0 +1,413 @@
1CONFIG_RCU_TRACE debugfs Files and Formats
2
3
4The rcupreempt and rcutree implementations of RCU provide debugfs trace
5output that summarizes counters and state. This information is useful for
6debugging RCU itself, and can sometimes also help to debug abuses of RCU.
7Note that the rcuclassic implementation of RCU does not provide debugfs
8trace output.
9
10The following sections describe the debugfs files and formats for
11preemptable RCU (rcupreempt) and hierarchical RCU (rcutree).
12
13
14Preemptable RCU debugfs Files and Formats
15
16This implementation of RCU provides three debugfs files under the
17top-level directory RCU: rcu/rcuctrs (which displays the per-CPU
18counters used by preemptable RCU) rcu/rcugp (which displays grace-period
19counters), and rcu/rcustats (which internal counters for debugging RCU).
20
21The output of "cat rcu/rcuctrs" looks as follows:
22
23CPU last cur F M
24 0 5 -5 0 0
25 1 -1 0 0 0
26 2 0 1 0 0
27 3 0 1 0 0
28 4 0 1 0 0
29 5 0 1 0 0
30 6 0 2 0 0
31 7 0 -1 0 0
32 8 0 1 0 0
33ggp = 26226, state = waitzero
34
35The per-CPU fields are as follows:
36
37o "CPU" gives the CPU number. Offline CPUs are not displayed.
38
39o "last" gives the value of the counter that is being decremented
40 for the current grace period phase. In the example above,
41 the counters sum to 4, indicating that there are still four
42 RCU read-side critical sections still running that started
43 before the last counter flip.
44
45o "cur" gives the value of the counter that is currently being
46 both incremented (by rcu_read_lock()) and decremented (by
47 rcu_read_unlock()). In the example above, the counters sum to
48 1, indicating that there is only one RCU read-side critical section
49 still running that started after the last counter flip.
50
51o "F" indicates whether RCU is waiting for this CPU to acknowledge
52 a counter flip. In the above example, RCU is not waiting on any,
53 which is consistent with the state being "waitzero" rather than
54 "waitack".
55
56o "M" indicates whether RCU is waiting for this CPU to execute a
57 memory barrier. In the above example, RCU is not waiting on any,
58 which is consistent with the state being "waitzero" rather than
59 "waitmb".
60
61o "ggp" is the global grace-period counter.
62
63o "state" is the RCU state, which can be one of the following:
64
65 o "idle": there is no grace period in progress.
66
67 o "waitack": RCU just incremented the global grace-period
68 counter, which has the effect of reversing the roles of
69 the "last" and "cur" counters above, and is waiting for
70 all the CPUs to acknowledge the flip. Once the flip has
71 been acknowledged, CPUs will no longer be incrementing
72 what are now the "last" counters, so that their sum will
73 decrease monotonically down to zero.
74
75 o "waitzero": RCU is waiting for the sum of the "last" counters
76 to decrease to zero.
77
78 o "waitmb": RCU is waiting for each CPU to execute a memory
79 barrier, which ensures that instructions from a given CPU's
80 last RCU read-side critical section cannot be reordered
81 with instructions following the memory-barrier instruction.
82
83The output of "cat rcu/rcugp" looks as follows:
84
85oldggp=48870 newggp=48873
86
87Note that reading from this file provokes a synchronize_rcu(). The
88"oldggp" value is that of "ggp" from rcu/rcuctrs above, taken before
89executing the synchronize_rcu(), and the "newggp" value is also the
90"ggp" value, but taken after the synchronize_rcu() command returns.
91
92
93The output of "cat rcu/rcugp" looks as follows:
94
95na=1337955 nl=40 wa=1337915 wl=44 da=1337871 dl=0 dr=1337871 di=1337871
961=50989 e1=6138 i1=49722 ie1=82 g1=49640 a1=315203 ae1=265563 a2=49640
97z1=1401244 ze1=1351605 z2=49639 m1=5661253 me1=5611614 m2=49639
98
99These are counters tracking internal preemptable-RCU events, however,
100some of them may be useful for debugging algorithms using RCU. In
101particular, the "nl", "wl", and "dl" values track the number of RCU
102callbacks in various states. The fields are as follows:
103
104o "na" is the total number of RCU callbacks that have been enqueued
105 since boot.
106
107o "nl" is the number of RCU callbacks waiting for the previous
108 grace period to end so that they can start waiting on the next
109 grace period.
110
111o "wa" is the total number of RCU callbacks that have started waiting
112 for a grace period since boot. "na" should be roughly equal to
113 "nl" plus "wa".
114
115o "wl" is the number of RCU callbacks currently waiting for their
116 grace period to end.
117
118o "da" is the total number of RCU callbacks whose grace periods
119 have completed since boot. "wa" should be roughly equal to
120 "wl" plus "da".
121
122o "dr" is the total number of RCU callbacks that have been removed
123 from the list of callbacks ready to invoke. "dr" should be roughly
124 equal to "da".
125
126o "di" is the total number of RCU callbacks that have been invoked
127 since boot. "di" should be roughly equal to "da", though some
128 early versions of preemptable RCU had a bug so that only the
129 last CPU's count of invocations was displayed, rather than the
130 sum of all CPU's counts.
131
132o "1" is the number of calls to rcu_try_flip(). This should be
133 roughly equal to the sum of "e1", "i1", "a1", "z1", and "m1"
134 described below. In other words, the number of times that
135 the state machine is visited should be equal to the sum of the
136 number of times that each state is visited plus the number of
137 times that the state-machine lock acquisition failed.
138
139o "e1" is the number of times that rcu_try_flip() was unable to
140 acquire the fliplock.
141
142o "i1" is the number of calls to rcu_try_flip_idle().
143
144o "ie1" is the number of times rcu_try_flip_idle() exited early
145 due to the calling CPU having no work for RCU.
146
147o "g1" is the number of times that rcu_try_flip_idle() decided
148 to start a new grace period. "i1" should be roughly equal to
149 "ie1" plus "g1".
150
151o "a1" is the number of calls to rcu_try_flip_waitack().
152
153o "ae1" is the number of times that rcu_try_flip_waitack() found
154 that at least one CPU had not yet acknowledge the new grace period
155 (AKA "counter flip").
156
157o "a2" is the number of time rcu_try_flip_waitack() found that
158 all CPUs had acknowledged. "a1" should be roughly equal to
159 "ae1" plus "a2". (This particular output was collected on
160 a 128-CPU machine, hence the smaller-than-usual fraction of
161 calls to rcu_try_flip_waitack() finding all CPUs having already
162 acknowledged.)
163
164o "z1" is the number of calls to rcu_try_flip_waitzero().
165
166o "ze1" is the number of times that rcu_try_flip_waitzero() found
167 that not all of the old RCU read-side critical sections had
168 completed.
169
170o "z2" is the number of times that rcu_try_flip_waitzero() finds
171 the sum of the counters equal to zero, in other words, that
172 all of the old RCU read-side critical sections had completed.
173 The value of "z1" should be roughly equal to "ze1" plus
174 "z2".
175
176o "m1" is the number of calls to rcu_try_flip_waitmb().
177
178o "me1" is the number of times that rcu_try_flip_waitmb() finds
179 that at least one CPU has not yet executed a memory barrier.
180
181o "m2" is the number of times that rcu_try_flip_waitmb() finds that
182 all CPUs have executed a memory barrier.
183
184
185Hierarchical RCU debugfs Files and Formats
186
187This implementation of RCU provides three debugfs files under the
188top-level directory RCU: rcu/rcudata (which displays fields in struct
189rcu_data), rcu/rcugp (which displays grace-period counters), and
190rcu/rcuhier (which displays the struct rcu_node hierarchy).
191
192The output of "cat rcu/rcudata" looks as follows:
193
194rcu:
195 0 c=4011 g=4012 pq=1 pqc=4011 qp=0 rpfq=1 rp=3c2a dt=23301/73 dn=2 df=1882 of=0 ri=2126 ql=2 b=10
196 1 c=4011 g=4012 pq=1 pqc=4011 qp=0 rpfq=3 rp=39a6 dt=78073/1 dn=2 df=1402 of=0 ri=1875 ql=46 b=10
197 2 c=4010 g=4010 pq=1 pqc=4010 qp=0 rpfq=-5 rp=1d12 dt=16646/0 dn=2 df=3140 of=0 ri=2080 ql=0 b=10
198 3 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=2b50 dt=21159/1 dn=2 df=2230 of=0 ri=1923 ql=72 b=10
199 4 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=1644 dt=5783/1 dn=2 df=3348 of=0 ri=2805 ql=7 b=10
200 5 c=4012 g=4013 pq=0 pqc=4011 qp=1 rpfq=3 rp=1aac dt=5879/1 dn=2 df=3140 of=0 ri=2066 ql=10 b=10
201 6 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=ed8 dt=5847/1 dn=2 df=3797 of=0 ri=1266 ql=10 b=10
202 7 c=4012 g=4013 pq=1 pqc=4012 qp=1 rpfq=3 rp=1fa2 dt=6199/1 dn=2 df=2795 of=0 ri=2162 ql=28 b=10
203rcu_bh:
204 0 c=-268 g=-268 pq=1 pqc=-268 qp=0 rpfq=-145 rp=21d6 dt=23301/73 dn=2 df=0 of=0 ri=0 ql=0 b=10
205 1 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-170 rp=20ce dt=78073/1 dn=2 df=26 of=0 ri=5 ql=0 b=10
206 2 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-83 rp=fbd dt=16646/0 dn=2 df=28 of=0 ri=4 ql=0 b=10
207 3 c=-268 g=-268 pq=1 pqc=-268 qp=0 rpfq=-105 rp=178c dt=21159/1 dn=2 df=28 of=0 ri=2 ql=0 b=10
208 4 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-30 rp=b54 dt=5783/1 dn=2 df=32 of=0 ri=0 ql=0 b=10
209 5 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-29 rp=df5 dt=5879/1 dn=2 df=30 of=0 ri=3 ql=0 b=10
210 6 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-28 rp=788 dt=5847/1 dn=2 df=32 of=0 ri=0 ql=0 b=10
211 7 c=-268 g=-268 pq=1 pqc=-268 qp=1 rpfq=-53 rp=1098 dt=6199/1 dn=2 df=30 of=0 ri=3 ql=0 b=10
212
213The first section lists the rcu_data structures for rcu, the second for
214rcu_bh. Each section has one line per CPU, or eight for this 8-CPU system.
215The fields are as follows:
216
217o The number at the beginning of each line is the CPU number.
218 CPUs numbers followed by an exclamation mark are offline,
219 but have been online at least once since boot. There will be
220 no output for CPUs that have never been online, which can be
221 a good thing in the surprisingly common case where NR_CPUS is
222 substantially larger than the number of actual CPUs.
223
224o "c" is the count of grace periods that this CPU believes have
225 completed. CPUs in dynticks idle mode may lag quite a ways
226 behind, for example, CPU 4 under "rcu" above, which has slept
227 through the past 25 RCU grace periods. It is not unusual to
228 see CPUs lagging by thousands of grace periods.
229
230o "g" is the count of grace periods that this CPU believes have
231 started. Again, CPUs in dynticks idle mode may lag behind.
232 If the "c" and "g" values are equal, this CPU has already
233 reported a quiescent state for the last RCU grace period that
234 it is aware of, otherwise, the CPU believes that it owes RCU a
235 quiescent state.
236
237o "pq" indicates that this CPU has passed through a quiescent state
238 for the current grace period. It is possible for "pq" to be
239 "1" and "c" different than "g", which indicates that although
240 the CPU has passed through a quiescent state, either (1) this
241 CPU has not yet reported that fact, (2) some other CPU has not
242 yet reported for this grace period, or (3) both.
243
244o "pqc" indicates which grace period the last-observed quiescent
245 state for this CPU corresponds to. This is important for handling
246 the race between CPU 0 reporting an extended dynticks-idle
247 quiescent state for CPU 1 and CPU 1 suddenly waking up and
248 reporting its own quiescent state. If CPU 1 was the last CPU
249 for the current grace period, then the CPU that loses this race
250 will attempt to incorrectly mark CPU 1 as having checked in for
251 the next grace period!
252
253o "qp" indicates that RCU still expects a quiescent state from
254 this CPU.
255
256o "rpfq" is the number of rcu_pending() calls on this CPU required
257 to induce this CPU to invoke force_quiescent_state().
258
259o "rp" is low-order four hex digits of the count of how many times
260 rcu_pending() has been invoked on this CPU.
261
262o "dt" is the current value of the dyntick counter that is incremented
263 when entering or leaving dynticks idle state, either by the
264 scheduler or by irq. The number after the "/" is the interrupt
265 nesting depth when in dyntick-idle state, or one greater than
266 the interrupt-nesting depth otherwise.
267
268 This field is displayed only for CONFIG_NO_HZ kernels.
269
270o "dn" is the current value of the dyntick counter that is incremented
271 when entering or leaving dynticks idle state via NMI. If both
272 the "dt" and "dn" values are even, then this CPU is in dynticks
273 idle mode and may be ignored by RCU. If either of these two
274 counters is odd, then RCU must be alert to the possibility of
275 an RCU read-side critical section running on this CPU.
276
277 This field is displayed only for CONFIG_NO_HZ kernels.
278
279o "df" is the number of times that some other CPU has forced a
280 quiescent state on behalf of this CPU due to this CPU being in
281 dynticks-idle state.
282
283 This field is displayed only for CONFIG_NO_HZ kernels.
284
285o "of" is the number of times that some other CPU has forced a
286 quiescent state on behalf of this CPU due to this CPU being
287 offline. In a perfect world, this might neve happen, but it
288 turns out that offlining and onlining a CPU can take several grace
289 periods, and so there is likely to be an extended period of time
290 when RCU believes that the CPU is online when it really is not.
291 Please note that erring in the other direction (RCU believing a
292 CPU is offline when it is really alive and kicking) is a fatal
293 error, so it makes sense to err conservatively.
294
295o "ri" is the number of times that RCU has seen fit to send a
296 reschedule IPI to this CPU in order to get it to report a
297 quiescent state.
298
299o "ql" is the number of RCU callbacks currently residing on
300 this CPU. This is the total number of callbacks, regardless
301 of what state they are in (new, waiting for grace period to
302 start, waiting for grace period to end, ready to invoke).
303
304o "b" is the batch limit for this CPU. If more than this number
305 of RCU callbacks is ready to invoke, then the remainder will
306 be deferred.
307
308
309The output of "cat rcu/rcugp" looks as follows:
310
311rcu: completed=33062 gpnum=33063
312rcu_bh: completed=464 gpnum=464
313
314Again, this output is for both "rcu" and "rcu_bh". The fields are
315taken from the rcu_state structure, and are as follows:
316
317o "completed" is the number of grace periods that have completed.
318 It is comparable to the "c" field from rcu/rcudata in that a
319 CPU whose "c" field matches the value of "completed" is aware
320 that the corresponding RCU grace period has completed.
321
322o "gpnum" is the number of grace periods that have started. It is
323 comparable to the "g" field from rcu/rcudata in that a CPU
324 whose "g" field matches the value of "gpnum" is aware that the
325 corresponding RCU grace period has started.
326
327 If these two fields are equal (as they are for "rcu_bh" above),
328 then there is no grace period in progress, in other words, RCU
329 is idle. On the other hand, if the two fields differ (as they
330 do for "rcu" above), then an RCU grace period is in progress.
331
332
333The output of "cat rcu/rcuhier" looks as follows, with very long lines:
334
335c=6902 g=6903 s=2 jfq=3 j=72c7 nfqs=13142/nfqsng=0(13142) fqlh=6
3361/1 0:127 ^0
3373/3 0:35 ^0 0/0 36:71 ^1 0/0 72:107 ^2 0/0 108:127 ^3
3383/3f 0:5 ^0 2/3 6:11 ^1 0/0 12:17 ^2 0/0 18:23 ^3 0/0 24:29 ^4 0/0 30:35 ^5 0/0 36:41 ^0 0/0 42:47 ^1 0/0 48:53 ^2 0/0 54:59 ^3 0/0 60:65 ^4 0/0 66:71 ^5 0/0 72:77 ^0 0/0 78:83 ^1 0/0 84:89 ^2 0/0 90:95 ^3 0/0 96:101 ^4 0/0 102:107 ^5 0/0 108:113 ^0 0/0 114:119 ^1 0/0 120:125 ^2 0/0 126:127 ^3
339rcu_bh:
340c=-226 g=-226 s=1 jfq=-5701 j=72c7 nfqs=88/nfqsng=0(88) fqlh=0
3410/1 0:127 ^0
3420/3 0:35 ^0 0/0 36:71 ^1 0/0 72:107 ^2 0/0 108:127 ^3
3430/3f 0:5 ^0 0/3 6:11 ^1 0/0 12:17 ^2 0/0 18:23 ^3 0/0 24:29 ^4 0/0 30:35 ^5 0/0 36:41 ^0 0/0 42:47 ^1 0/0 48:53 ^2 0/0 54:59 ^3 0/0 60:65 ^4 0/0 66:71 ^5 0/0 72:77 ^0 0/0 78:83 ^1 0/0 84:89 ^2 0/0 90:95 ^3 0/0 96:101 ^4 0/0 102:107 ^5 0/0 108:113 ^0 0/0 114:119 ^1 0/0 120:125 ^2 0/0 126:127 ^3
344
345This is once again split into "rcu" and "rcu_bh" portions. The fields are
346as follows:
347
348o "c" is exactly the same as "completed" under rcu/rcugp.
349
350o "g" is exactly the same as "gpnum" under rcu/rcugp.
351
352o "s" is the "signaled" state that drives force_quiescent_state()'s
353 state machine.
354
355o "jfq" is the number of jiffies remaining for this grace period
356 before force_quiescent_state() is invoked to help push things
357 along. Note that CPUs in dyntick-idle mode thoughout the grace
358 period will not report on their own, but rather must be check by
359 some other CPU via force_quiescent_state().
360
361o "j" is the low-order four hex digits of the jiffies counter.
362 Yes, Paul did run into a number of problems that turned out to
363 be due to the jiffies counter no longer counting. Why do you ask?
364
365o "nfqs" is the number of calls to force_quiescent_state() since
366 boot.
367
368o "nfqsng" is the number of useless calls to force_quiescent_state(),
369 where there wasn't actually a grace period active. This can
370 happen due to races. The number in parentheses is the difference
371 between "nfqs" and "nfqsng", or the number of times that
372 force_quiescent_state() actually did some real work.
373
374o "fqlh" is the number of calls to force_quiescent_state() that
375 exited immediately (without even being counted in nfqs above)
376 due to contention on ->fqslock.
377
378o Each element of the form "1/1 0:127 ^0" represents one struct
379 rcu_node. Each line represents one level of the hierarchy, from
380 root to leaves. It is best to think of the rcu_data structures
381 as forming yet another level after the leaves. Note that there
382 might be either one, two, or three levels of rcu_node structures,
383 depending on the relationship between CONFIG_RCU_FANOUT and
384 CONFIG_NR_CPUS.
385
386 o The numbers separated by the "/" are the qsmask followed
387 by the qsmaskinit. The qsmask will have one bit
388 set for each entity in the next lower level that
389 has not yet checked in for the current grace period.
390 The qsmaskinit will have one bit for each entity that is
391 currently expected to check in during each grace period.
392 The value of qsmaskinit is assigned to that of qsmask
393 at the beginning of each grace period.
394
395 For example, for "rcu", the qsmask of the first entry
396 of the lowest level is 0x14, meaning that we are still
397 waiting for CPUs 2 and 4 to check in for the current
398 grace period.
399
400 o The numbers separated by the ":" are the range of CPUs
401 served by this struct rcu_node. This can be helpful
402 in working out how the hierarchy is wired together.
403
404 For example, the first entry at the lowest level shows
405 "0:5", indicating that it covers CPUs 0 through 5.
406
407 o The number after the "^" indicates the bit in the
408 next higher level rcu_node structure that this
409 rcu_node structure corresponds to.
410
411 For example, the first entry at the lowest level shows
412 "^0", indicating that it corresponds to bit zero in
413 the first entry at the middle level.
diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.txt
new file mode 100644
index 000000000000..a179e5bc02c9
--- /dev/null
+++ b/Documentation/arm/pxa/mfp.txt
@@ -0,0 +1,286 @@
1 MFP Configuration for PXA2xx/PXA3xx Processors
2
3 Eric Miao <eric.miao@marvell.com>
4
5MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and
6later PXA series processors. This document describes the existing MFP API,
7and how board/platform driver authors could make use of it.
8
9 Basic Concept
10===============
11
12Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP
13mechanism is introduced from PXA3xx to completely move the pin-mux functions
14out of the GPIO controller. In addition to pin-mux configurations, the MFP
15also controls the low power state, driving strength, pull-up/down and event
16detection of each pin. Below is a diagram of internal connections between
17the MFP logic and the remaining SoC peripherals:
18
19 +--------+
20 | |--(GPIO19)--+
21 | GPIO | |
22 | |--(GPIO...) |
23 +--------+ |
24 | +---------+
25 +--------+ +------>| |
26 | PWM2 |--(PWM_OUT)-------->| MFP |
27 +--------+ +------>| |-------> to external PAD
28 | +---->| |
29 +--------+ | | +-->| |
30 | SSP2 |---(TXD)----+ | | +---------+
31 +--------+ | |
32 | |
33 +--------+ | |
34 | Keypad |--(MKOUT4)----+ |
35 +--------+ |
36 |
37 +--------+ |
38 | UART2 |---(TXD)--------+
39 +--------+
40
41NOTE: the external pad is named as MFP_PIN_GPIO19, it doesn't necessarily
42mean it's dedicated for GPIO19, only as a hint that internally this pin
43can be routed from GPIO19 of the GPIO controller.
44
45To better understand the change from PXA25x/PXA27x GPIO alternate function
46to this new MFP mechanism, here are several key points:
47
48 1. GPIO controller on PXA3xx is now a dedicated controller, same as other
49 internal controllers like PWM, SSP and UART, with 128 internal signals
50 which can be routed to external through one or more MFPs (e.g. GPIO<0>
51 can be routed through either MFP_PIN_GPIO0 as well as MFP_PIN_GPIO0_2,
52 see arch/arm/mach-pxa/mach/include/mfp-pxa300.h)
53
54 2. Alternate function configuration is removed from this GPIO controller,
55 the remaining functions are pure GPIO-specific, i.e.
56
57 - GPIO signal level control
58 - GPIO direction control
59 - GPIO level change detection
60
61 3. Low power state for each pin is now controlled by MFP, this means the
62 PGSRx registers on PXA2xx are now useless on PXA3xx
63
64 4. Wakeup detection is now controlled by MFP, PWER does not control the
65 wakeup from GPIO(s) any more, depending on the sleeping state, ADxER
66 (as defined in pxa3xx-regs.h) controls the wakeup from MFP
67
68NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally
69mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical
70pad (or ball).
71
72 MFP API Usage
73===============
74
75For board code writers, here are some guidelines:
76
771. include ONE of the following header files in your <board>.c:
78
79 - #include <mach/mfp-pxa25x.h>
80 - #include <mach/mfp-pxa27x.h>
81 - #include <mach/mfp-pxa300.h>
82 - #include <mach/mfp-pxa320.h>
83 - #include <mach/mfp-pxa930.h>
84
85 NOTE: only one file in your <board>.c, depending on the processors used,
86 because pin configuration definitions may conflict in these file (i.e.
87 same name, different meaning and settings on different processors). E.g.
88 for zylonite platform, which support both PXA300/PXA310 and PXA320, two
89 separate files are introduced: zylonite_pxa300.c and zylonite_pxa320.c
90 (in addition to handle MFP configuration differences, they also handle
91 the other differences between the two combinations).
92
93 NOTE: PXA300 and PXA310 are almost identical in pin configurations (with
94 PXA310 supporting some additional ones), thus the difference is actually
95 covered in a single mfp-pxa300.h.
96
972. prepare an array for the initial pin configurations, e.g.:
98
99 static unsigned long mainstone_pin_config[] __initdata = {
100 /* Chip Select */
101 GPIO15_nCS_1,
102
103 /* LCD - 16bpp Active TFT */
104 GPIOxx_TFT_LCD_16BPP,
105 GPIO16_PWM0_OUT, /* Backlight */
106
107 /* MMC */
108 GPIO32_MMC_CLK,
109 GPIO112_MMC_CMD,
110 GPIO92_MMC_DAT_0,
111 GPIO109_MMC_DAT_1,
112 GPIO110_MMC_DAT_2,
113 GPIO111_MMC_DAT_3,
114
115 ...
116
117 /* GPIO */
118 GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH,
119 };
120
121 a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(),
122 and written to the actual registers, they are useless and may discard,
123 adding '__initdata' will help save some additional bytes here.
124
125 b) when there is only one possible pin configurations for a component,
126 some simplified definitions can be used, e.g. GPIOxx_TFT_LCD_16BPP on
127 PXA25x and PXA27x processors
128
129 c) if by board design, a pin can be configured to wake up the system
130 from low power state, it can be 'OR'ed with any of:
131
132 WAKEUP_ON_EDGE_BOTH
133 WAKEUP_ON_EDGE_RISE
134 WAKEUP_ON_EDGE_FALL
135 WAKEUP_ON_LEVEL_HIGH - specifically for enabling of keypad GPIOs,
136
137 to indicate that this pin has the capability of wake-up the system,
138 and on which edge(s). This, however, doesn't necessarily mean the
139 pin _will_ wakeup the system, it will only when set_irq_wake() is
140 invoked with the corresponding GPIO IRQ (GPIO_IRQ(xx) or gpio_to_irq())
141 and eventually calls gpio_set_wake() for the actual register setting.
142
143 d) although PXA3xx MFP supports edge detection on each pin, the
144 internal logic will only wakeup the system when those specific bits
145 in ADxER registers are set, which can be well mapped to the
146 corresponding peripheral, thus set_irq_wake() can be called with
147 the peripheral IRQ to enable the wakeup.
148
149
150 MFP on PXA3xx
151===============
152
153Every external I/O pad on PXA3xx (excluding those for special purpose) has
154one MFP logic associated, and is controlled by one MFP register (MFPR).
155
156The MFPR has the following bit definitions (for PXA300/PXA310/PXA320):
157
158 31 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
159 +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
160 | RESERVED |PS|PU|PD| DRIVE |SS|SD|SO|EC|EF|ER|--| AF_SEL |
161 +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
162
163 Bit 3: RESERVED
164 Bit 4: EDGE_RISE_EN - enable detection of rising edge on this pin
165 Bit 5: EDGE_FALL_EN - enable detection of falling edge on this pin
166 Bit 6: EDGE_CLEAR - disable edge detection on this pin
167 Bit 7: SLEEP_OE_N - enable outputs during low power modes
168 Bit 8: SLEEP_DATA - output data on the pin during low power modes
169 Bit 9: SLEEP_SEL - selection control for low power modes signals
170 Bit 13: PULLDOWN_EN - enable the internal pull-down resistor on this pin
171 Bit 14: PULLUP_EN - enable the internal pull-up resistor on this pin
172 Bit 15: PULL_SEL - pull state controlled by selected alternate function
173 (0) or by PULL{UP,DOWN}_EN bits (1)
174
175 Bit 0 - 2: AF_SEL - alternate function selection, 8 possibilities, from 0-7
176 Bit 10-12: DRIVE - drive strength and slew rate
177 0b000 - fast 1mA
178 0b001 - fast 2mA
179 0b002 - fast 3mA
180 0b003 - fast 4mA
181 0b004 - slow 6mA
182 0b005 - fast 6mA
183 0b006 - slow 10mA
184 0b007 - fast 10mA
185
186 MFP Design for PXA2xx/PXA3xx
187==============================
188
189Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified
190MFP API is introduced to cover both series of processors.
191
192The basic idea of this design is to introduce definitions for all possible pin
193configurations, these definitions are processor and platform independent, and
194the actual API invoked to convert these definitions into register settings and
195make them effective there-after.
196
197 Files Involved
198 --------------
199
200 - arch/arm/mach-pxa/include/mach/mfp.h
201
202 for
203 1. Unified pin definitions - enum constants for all configurable pins
204 2. processor-neutral bit definitions for a possible MFP configuration
205
206 - arch/arm/mach-pxa/include/mach/mfp-pxa3xx.h
207
208 for PXA3xx specific MFPR register bit definitions and PXA3xx common pin
209 configurations
210
211 - arch/arm/mach-pxa/include/mach/mfp-pxa2xx.h
212
213 for PXA2xx specific definitions and PXA25x/PXA27x common pin configurations
214
215 - arch/arm/mach-pxa/include/mach/mfp-pxa25x.h
216 arch/arm/mach-pxa/include/mach/mfp-pxa27x.h
217 arch/arm/mach-pxa/include/mach/mfp-pxa300.h
218 arch/arm/mach-pxa/include/mach/mfp-pxa320.h
219 arch/arm/mach-pxa/include/mach/mfp-pxa930.h
220
221 for processor specific definitions
222
223 - arch/arm/mach-pxa/mfp-pxa3xx.c
224 - arch/arm/mach-pxa/mfp-pxa2xx.c
225
226 for implementation of the pin configuration to take effect for the actual
227 processor.
228
229 Pin Configuration
230 -----------------
231
232 The following comments are copied from mfp.h (see the actual source code
233 for most updated info)
234
235 /*
236 * a possible MFP configuration is represented by a 32-bit integer
237 *
238 * bit 0.. 9 - MFP Pin Number (1024 Pins Maximum)
239 * bit 10..12 - Alternate Function Selection
240 * bit 13..15 - Drive Strength
241 * bit 16..18 - Low Power Mode State
242 * bit 19..20 - Low Power Mode Edge Detection
243 * bit 21..22 - Run Mode Pull State
244 *
245 * to facilitate the definition, the following macros are provided
246 *
247 * MFP_CFG_DEFAULT - default MFP configuration value, with
248 * alternate function = 0,
249 * drive strength = fast 3mA (MFP_DS03X)
250 * low power mode = default
251 * edge detection = none
252 *
253 * MFP_CFG - default MFPR value with alternate function
254 * MFP_CFG_DRV - default MFPR value with alternate function and
255 * pin drive strength
256 * MFP_CFG_LPM - default MFPR value with alternate function and
257 * low power mode
258 * MFP_CFG_X - default MFPR value with alternate function,
259 * pin drive strength and low power mode
260 */
261
262 Examples of pin configurations are:
263
264 #define GPIO94_SSP3_RXD MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT)
265
266 which reads GPIO94 can be configured as SSP3_RXD, with alternate function
267 selection of 1, driving strength of 0b101, and a float state in low power
268 modes.
269
270 NOTE: this is the default setting of this pin being configured as SSP3_RXD
271 which can be modified a bit in board code, though it is not recommended to
272 do so, simply because this default setting is usually carefully encoded,
273 and is supposed to work in most cases.
274
275 Register Settings
276 -----------------
277
278 Register settings on PXA3xx for a pin configuration is actually very
279 straight-forward, most bits can be converted directly into MFPR value
280 in a easier way. Two sets of MFPR values are calculated: the run-time
281 ones and the low power mode ones, to allow different settings.
282
283 The conversion from a generic pin configuration to the actual register
284 settings on PXA2xx is a bit complicated: many registers are involved,
285 including GAFRx, GPDRx, PGSRx, PWER, PKWR, PFER and PRER. Please see
286 mfp-pxa2xx.c for how the conversion is made.
diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt
index 4dbb8be1c991..3c5434c83daf 100644
--- a/Documentation/block/biodoc.txt
+++ b/Documentation/block/biodoc.txt
@@ -914,7 +914,7 @@ I/O scheduler, a.k.a. elevator, is implemented in two layers. Generic dispatch
914queue and specific I/O schedulers. Unless stated otherwise, elevator is used 914queue and specific I/O schedulers. Unless stated otherwise, elevator is used
915to refer to both parts and I/O scheduler to specific I/O schedulers. 915to refer to both parts and I/O scheduler to specific I/O schedulers.
916 916
917Block layer implements generic dispatch queue in ll_rw_blk.c and elevator.c. 917Block layer implements generic dispatch queue in block/*.c.
918The generic dispatch queue is responsible for properly ordering barrier 918The generic dispatch queue is responsible for properly ordering barrier
919requests, requeueing, handling non-fs requests and all other subtleties. 919requests, requeueing, handling non-fs requests and all other subtleties.
920 920
@@ -926,8 +926,8 @@ be built inside the kernel. Each queue can choose different one and can also
926change to another one dynamically. 926change to another one dynamically.
927 927
928A block layer call to the i/o scheduler follows the convention elv_xxx(). This 928A block layer call to the i/o scheduler follows the convention elv_xxx(). This
929calls elevator_xxx_fn in the elevator switch (drivers/block/elevator.c). Oh, 929calls elevator_xxx_fn in the elevator switch (block/elevator.c). Oh, xxx
930xxx and xxx might not match exactly, but use your imagination. If an elevator 930and xxx might not match exactly, but use your imagination. If an elevator
931doesn't implement a function, the switch does nothing or some minimal house 931doesn't implement a function, the switch does nothing or some minimal house
932keeping work. 932keeping work.
933 933
diff --git a/Documentation/dvb/technisat.txt b/Documentation/dvb/technisat.txt
new file mode 100644
index 000000000000..cdf6ee4b2da1
--- /dev/null
+++ b/Documentation/dvb/technisat.txt
@@ -0,0 +1,69 @@
1How to set up the Technisat devices
2===================================
3
41) Find out what device you have
5================================
6
7First start your linux box with a shipped kernel:
8lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example:
902:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip / Technisat SkyStar2 DVB card (rev 02)
10
11dmesg | grep frontend may show you for example:
12DVB: registering frontend 0 (Conexant CX24123/CX24109)...
13
142) Kernel compilation:
15======================
16
17If the Technisat is the only TV device in your box get rid of unnecessary modules and check this one:
18"Multimedia devices" => "Customise analog and hybrid tuner modules to build"
19In this directory uncheck every driver which is activated there.
20
21Then please activate:
222a) Main module part:
23
24a.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters"
25b.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC PCI" in case of a PCI card OR
26c.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Technisat/B2C2 Air/Sky/Cable2PC USB" in case of an USB 1.1 adapter
27d.)"Multimedia devices" => "DVB/ATSC adapters" => "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters" => "Enable debug for the B2C2 FlexCop drivers"
28Notice: d.) is helpful for troubleshooting
29
302b) Frontend module part:
31
321.) Revision 2.3:
33a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
34b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink VP310/MT312/ZL10313 based"
35
362.) Revision 2.6:
37a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
38b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0299 based"
39
403.) Revision 2.7:
41a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
42b.)"Multimedia devices" => "Customise DVB frontends" => "Samsung S5H1420 based"
43c.)"Multimedia devices" => "Customise DVB frontends" => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS"
44d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller"
45
464.) Revision 2.8:
47a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
48b.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24113/CX24128 tuner for DVB-S/DSS"
49c.)"Multimedia devices" => "Customise DVB frontends" => "Conexant CX24123 based"
50d.)"Multimedia devices" => "Customise DVB frontends" => "ISL6421 SEC controller"
51
525.) DVB-T card:
53a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
54b.)"Multimedia devices" => "Customise DVB frontends" => "Zarlink MT352 based"
55
566.) DVB-C card:
57a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
58b.)"Multimedia devices" => "Customise DVB frontends" => "ST STV0297 based"
59
607.) ATSC card 1st generation:
61a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
62b.)"Multimedia devices" => "Customise DVB frontends" => "Broadcom BCM3510"
63
648.) ATSC card 2nd generation:
65a.)"Multimedia devices" => "Customise DVB frontends" => "Customise the frontend modules to build"
66b.)"Multimedia devices" => "Customise DVB frontends" => "NxtWave Communications NXT2002/NXT2004 based"
67c.)"Multimedia devices" => "Customise DVB frontends" => "LG Electronics LGDT3302/LGDT3303 based"
68
69Author: Uwe Bugla <uwe.bugla@gmx.de> December 2008
diff --git a/Documentation/fb/pxafb.txt b/Documentation/fb/pxafb.txt
index db9b8500b43b..d143a0a749f9 100644
--- a/Documentation/fb/pxafb.txt
+++ b/Documentation/fb/pxafb.txt
@@ -5,9 +5,13 @@ The driver supports the following options, either via
5options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in. 5options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in.
6 6
7For example: 7For example:
8 modprobe pxafb options=mode:640x480-8,passive 8 modprobe pxafb options=vmem:2M,mode:640x480-8,passive
9or on the kernel command line 9or on the kernel command line
10 video=pxafb:mode:640x480-8,passive 10 video=pxafb:vmem:2M,mode:640x480-8,passive
11
12vmem: VIDEO_MEM_SIZE
13 Amount of video memory to allocate (can be suffixed with K or M
14 for kilobytes or megabytes)
11 15
12mode:XRESxYRES[-BPP] 16mode:XRESxYRES[-BPP]
13 XRES == LCCR1_PPL + 1 17 XRES == LCCR1_PPL + 1
@@ -52,3 +56,87 @@ outputen:POLARITY
52pixclockpol:POLARITY 56pixclockpol:POLARITY
53 pixel clock polarity 57 pixel clock polarity
54 0 => falling edge, 1 => rising edge 58 0 => falling edge, 1 => rising edge
59
60
61Overlay Support for PXA27x and later LCD controllers
62====================================================
63
64 PXA27x and later processors support overlay1 and overlay2 on-top of the
65 base framebuffer (although under-neath the base is also possible). They
66 support palette and no-palette RGB formats, as well as YUV formats (only
67 available on overlay2). These overlays have dedicated DMA channels and
68 behave in a similar way as a framebuffer.
69
70 However, there are some differences between these overlay framebuffers
71 and normal framebuffers, as listed below:
72
73 1. overlay can start at a 32-bit word aligned position within the base
74 framebuffer, which means they have a start (x, y). This information
75 is encoded into var->nonstd (no, var->xoffset and var->yoffset are
76 not for such purpose).
77
78 2. overlay framebuffer is allocated dynamically according to specified
79 'struct fb_var_screeninfo', the amount is decided by:
80
81 var->xres_virtual * var->yres_virtual * bpp
82
83 bpp = 16 -- for RGB565 or RGBT555
84 = 24 -- for YUV444 packed
85 = 24 -- for YUV444 planar
86 = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)
87 = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)
88
89 NOTE:
90
91 a. overlay does not support panning in x-direction, thus
92 var->xres_virtual will always be equal to var->xres
93
94 b. line length of overlay(s) must be on a 32-bit word boundary,
95 for YUV planar modes, it is a requirement for the component
96 with minimum bits per pixel, e.g. for YUV420, Cr component
97 for one pixel is actually 2-bits, it means the line length
98 should be a multiple of 16-pixels
99
100 c. starting horizontal position (XPOS) should start on a 32-bit
101 word boundary, otherwise the fb_check_var() will just fail.
102
103 d. the rectangle of the overlay should be within the base plane,
104 otherwise fail
105
106 Applications should follow the sequence below to operate an overlay
107 framebuffer:
108
109 a. open("/dev/fb[1-2]", ...)
110 b. ioctl(fd, FBIOGET_VSCREENINFO, ...)
111 c. modify 'var' with desired parameters:
112 1) var->xres and var->yres
113 2) larger var->yres_virtual if more memory is required,
114 usually for double-buffering
115 3) var->nonstd for starting (x, y) and color format
116 4) var->{red, green, blue, transp} if RGB mode is to be used
117 d. ioctl(fd, FBIOPUT_VSCREENINFO, ...)
118 e. ioctl(fd, FBIOGET_FSCREENINFO, ...)
119 f. mmap
120 g. ...
121
122 3. for YUV planar formats, these are actually not supported within the
123 framebuffer framework, application has to take care of the offsets
124 and lengths of each component within the framebuffer.
125
126 4. var->nonstd is used to pass starting (x, y) position and color format,
127 the detailed bit fields are shown below:
128
129 31 23 20 10 0
130 +-----------------+---+----------+----------+
131 | ... unused ... |FOR| XPOS | YPOS |
132 +-----------------+---+----------+----------+
133
134 FOR - color format, as defined by OVERLAY_FORMAT_* in pxafb.h
135 0 - RGB
136 1 - YUV444 PACKED
137 2 - YUV444 PLANAR
138 3 - YUV422 PLANAR
139 4 - YUR420 PLANAR
140
141 XPOS - starting horizontal position
142 YPOS - starting vertical position
diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
index 0a1668ba2600..9878f50d6ed6 100644
--- a/Documentation/filesystems/xfs.txt
+++ b/Documentation/filesystems/xfs.txt
@@ -229,10 +229,6 @@ The following sysctls are available for the XFS filesystem:
229 ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl 229 ISGID bit is cleared if the irix_sgid_inherit compatibility sysctl
230 is set. 230 is set.
231 231
232 fs.xfs.restrict_chown (Min: 0 Default: 1 Max: 1)
233 Controls whether unprivileged users can use chown to "give away"
234 a file to another user.
235
236 fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1) 232 fs.xfs.inherit_sync (Min: 0 Default: 1 Max: 1)
237 Setting this to "1" will cause the "sync" flag set 233 Setting this to "1" will cause the "sync" flag set
238 by the xfs_io(8) chattr command on a directory to be 234 by the xfs_io(8) chattr command on a directory to be
diff --git a/Documentation/lguest/lguest.c b/Documentation/lguest/lguest.c
index 804520633fcf..f2dbbf3bdeab 100644
--- a/Documentation/lguest/lguest.c
+++ b/Documentation/lguest/lguest.c
@@ -481,51 +481,6 @@ static unsigned long load_initrd(const char *name, unsigned long mem)
481 /* We return the initrd size. */ 481 /* We return the initrd size. */
482 return len; 482 return len;
483} 483}
484
485/* Once we know how much memory we have we can construct simple linear page
486 * tables which set virtual == physical which will get the Guest far enough
487 * into the boot to create its own.
488 *
489 * We lay them out of the way, just below the initrd (which is why we need to
490 * know its size here). */
491static unsigned long setup_pagetables(unsigned long mem,
492 unsigned long initrd_size)
493{
494 unsigned long *pgdir, *linear;
495 unsigned int mapped_pages, i, linear_pages;
496 unsigned int ptes_per_page = getpagesize()/sizeof(void *);
497
498 mapped_pages = mem/getpagesize();
499
500 /* Each PTE page can map ptes_per_page pages: how many do we need? */
501 linear_pages = (mapped_pages + ptes_per_page-1)/ptes_per_page;
502
503 /* We put the toplevel page directory page at the top of memory. */
504 pgdir = from_guest_phys(mem) - initrd_size - getpagesize();
505
506 /* Now we use the next linear_pages pages as pte pages */
507 linear = (void *)pgdir - linear_pages*getpagesize();
508
509 /* Linear mapping is easy: put every page's address into the mapping in
510 * order. PAGE_PRESENT contains the flags Present, Writable and
511 * Executable. */
512 for (i = 0; i < mapped_pages; i++)
513 linear[i] = ((i * getpagesize()) | PAGE_PRESENT);
514
515 /* The top level points to the linear page table pages above. */
516 for (i = 0; i < mapped_pages; i += ptes_per_page) {
517 pgdir[i/ptes_per_page]
518 = ((to_guest_phys(linear) + i*sizeof(void *))
519 | PAGE_PRESENT);
520 }
521
522 verbose("Linear mapping of %u pages in %u pte pages at %#lx\n",
523 mapped_pages, linear_pages, to_guest_phys(linear));
524
525 /* We return the top level (guest-physical) address: the kernel needs
526 * to know where it is. */
527 return to_guest_phys(pgdir);
528}
529/*:*/ 484/*:*/
530 485
531/* Simple routine to roll all the commandline arguments together with spaces 486/* Simple routine to roll all the commandline arguments together with spaces
@@ -548,13 +503,13 @@ static void concat(char *dst, char *args[])
548 503
549/*L:185 This is where we actually tell the kernel to initialize the Guest. We 504/*L:185 This is where we actually tell the kernel to initialize the Guest. We
550 * saw the arguments it expects when we looked at initialize() in lguest_user.c: 505 * saw the arguments it expects when we looked at initialize() in lguest_user.c:
551 * the base of Guest "physical" memory, the top physical page to allow, the 506 * the base of Guest "physical" memory, the top physical page to allow and the
552 * top level pagetable and the entry point for the Guest. */ 507 * entry point for the Guest. */
553static int tell_kernel(unsigned long pgdir, unsigned long start) 508static int tell_kernel(unsigned long start)
554{ 509{
555 unsigned long args[] = { LHREQ_INITIALIZE, 510 unsigned long args[] = { LHREQ_INITIALIZE,
556 (unsigned long)guest_base, 511 (unsigned long)guest_base,
557 guest_limit / getpagesize(), pgdir, start }; 512 guest_limit / getpagesize(), start };
558 int fd; 513 int fd;
559 514
560 verbose("Guest: %p - %p (%#lx)\n", 515 verbose("Guest: %p - %p (%#lx)\n",
@@ -1030,7 +985,7 @@ static void update_device_status(struct device *dev)
1030 /* Zero out the virtqueues. */ 985 /* Zero out the virtqueues. */
1031 for (vq = dev->vq; vq; vq = vq->next) { 986 for (vq = dev->vq; vq; vq = vq->next) {
1032 memset(vq->vring.desc, 0, 987 memset(vq->vring.desc, 0,
1033 vring_size(vq->config.num, getpagesize())); 988 vring_size(vq->config.num, LGUEST_VRING_ALIGN));
1034 lg_last_avail(vq) = 0; 989 lg_last_avail(vq) = 0;
1035 } 990 }
1036 } else if (dev->desc->status & VIRTIO_CONFIG_S_FAILED) { 991 } else if (dev->desc->status & VIRTIO_CONFIG_S_FAILED) {
@@ -1211,7 +1166,7 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs,
1211 void *p; 1166 void *p;
1212 1167
1213 /* First we need some memory for this virtqueue. */ 1168 /* First we need some memory for this virtqueue. */
1214 pages = (vring_size(num_descs, getpagesize()) + getpagesize() - 1) 1169 pages = (vring_size(num_descs, LGUEST_VRING_ALIGN) + getpagesize() - 1)
1215 / getpagesize(); 1170 / getpagesize();
1216 p = get_pages(pages); 1171 p = get_pages(pages);
1217 1172
@@ -1228,7 +1183,7 @@ static void add_virtqueue(struct device *dev, unsigned int num_descs,
1228 vq->config.pfn = to_guest_phys(p) / getpagesize(); 1183 vq->config.pfn = to_guest_phys(p) / getpagesize();
1229 1184
1230 /* Initialize the vring. */ 1185 /* Initialize the vring. */
1231 vring_init(&vq->vring, num_descs, p, getpagesize()); 1186 vring_init(&vq->vring, num_descs, p, LGUEST_VRING_ALIGN);
1232 1187
1233 /* Append virtqueue to this device's descriptor. We use 1188 /* Append virtqueue to this device's descriptor. We use
1234 * device_config() to get the end of the device's current virtqueues; 1189 * device_config() to get the end of the device's current virtqueues;
@@ -1941,7 +1896,7 @@ int main(int argc, char *argv[])
1941{ 1896{
1942 /* Memory, top-level pagetable, code startpoint and size of the 1897 /* Memory, top-level pagetable, code startpoint and size of the
1943 * (optional) initrd. */ 1898 * (optional) initrd. */
1944 unsigned long mem = 0, pgdir, start, initrd_size = 0; 1899 unsigned long mem = 0, start, initrd_size = 0;
1945 /* Two temporaries and the /dev/lguest file descriptor. */ 1900 /* Two temporaries and the /dev/lguest file descriptor. */
1946 int i, c, lguest_fd; 1901 int i, c, lguest_fd;
1947 /* The boot information for the Guest. */ 1902 /* The boot information for the Guest. */
@@ -2040,9 +1995,6 @@ int main(int argc, char *argv[])
2040 boot->hdr.type_of_loader = 0xFF; 1995 boot->hdr.type_of_loader = 0xFF;
2041 } 1996 }
2042 1997
2043 /* Set up the initial linear pagetables, starting below the initrd. */
2044 pgdir = setup_pagetables(mem, initrd_size);
2045
2046 /* The Linux boot header contains an "E820" memory map: ours is a 1998 /* The Linux boot header contains an "E820" memory map: ours is a
2047 * simple, single region. */ 1999 * simple, single region. */
2048 boot->e820_entries = 1; 2000 boot->e820_entries = 1;
@@ -2064,7 +2016,7 @@ int main(int argc, char *argv[])
2064 2016
2065 /* We tell the kernel to initialize the Guest: this returns the open 2017 /* We tell the kernel to initialize the Guest: this returns the open
2066 * /dev/lguest file descriptor. */ 2018 * /dev/lguest file descriptor. */
2067 lguest_fd = tell_kernel(pgdir, start); 2019 lguest_fd = tell_kernel(start);
2068 2020
2069 /* We clone off a thread, which wakes the Launcher whenever one of the 2021 /* We clone off a thread, which wakes the Launcher whenever one of the
2070 * input file descriptors needs attention. We call this the Waker, and 2022 * input file descriptors needs attention. We call this the Waker, and
diff --git a/Documentation/lockstat.txt b/Documentation/lockstat.txt
index 4ba4664ce5c3..9cb9138f7a79 100644
--- a/Documentation/lockstat.txt
+++ b/Documentation/lockstat.txt
@@ -71,35 +71,50 @@ Look at the current lock statistics:
71 71
72# less /proc/lock_stat 72# less /proc/lock_stat
73 73
7401 lock_stat version 0.2 7401 lock_stat version 0.3
7502 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 7502 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
7603 class name con-bounces contentions waittime-min waittime-max waittime-total acq-bounces acquisitions holdtime-min holdtime-max holdtime-total 7603 class name con-bounces contentions waittime-min waittime-max waittime-total acq-bounces acquisitions holdtime-min holdtime-max holdtime-total
7704 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 7704 -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
7805 7805
7906 &inode->i_data.tree_lock-W: 15 21657 0.18 1093295.30 11547131054.85 58 10415 0.16 87.51 6387.60 7906 &mm->mmap_sem-W: 233 538 18446744073708 22924.27 607243.51 1342 45806 1.71 8595.89 1180582.34
8007 &inode->i_data.tree_lock-R: 0 0 0.00 0.00 0.00 23302 231198 0.25 8.45 98023.38 8007 &mm->mmap_sem-R: 205 587 18446744073708 28403.36 731975.00 1940 412426 0.58 187825.45 6307502.88
8108 -------------------------- 8108 ---------------
8209 &inode->i_data.tree_lock 0 [<ffffffff8027c08f>] add_to_page_cache+0x5f/0x190 8209 &mm->mmap_sem 487 [<ffffffff8053491f>] do_page_fault+0x466/0x928
8310 8310 &mm->mmap_sem 179 [<ffffffff802a6200>] sys_mprotect+0xcd/0x21d
8411 ............................................................................................................................................................................................... 8411 &mm->mmap_sem 279 [<ffffffff80210a57>] sys_mmap+0x75/0xce
8512 8512 &mm->mmap_sem 76 [<ffffffff802a490b>] sys_munmap+0x32/0x59
8613 dcache_lock: 1037 1161 0.38 45.32 774.51 6611 243371 0.15 306.48 77387.24 8613 ---------------
8714 ----------- 8714 &mm->mmap_sem 270 [<ffffffff80210a57>] sys_mmap+0x75/0xce
8815 dcache_lock 180 [<ffffffff802c0d7e>] sys_getcwd+0x11e/0x230 8815 &mm->mmap_sem 431 [<ffffffff8053491f>] do_page_fault+0x466/0x928
8916 dcache_lock 165 [<ffffffff802c002a>] d_alloc+0x15a/0x210 8916 &mm->mmap_sem 138 [<ffffffff802a490b>] sys_munmap+0x32/0x59
9017 dcache_lock 33 [<ffffffff8035818d>] _atomic_dec_and_lock+0x4d/0x70 9017 &mm->mmap_sem 145 [<ffffffff802a6200>] sys_mprotect+0xcd/0x21d
9118 dcache_lock 1 [<ffffffff802beef8>] shrink_dcache_parent+0x18/0x130 9118
9219 ...............................................................................................................................................................................................
9320
9421 dcache_lock: 621 623 0.52 118.26 1053.02 6745 91930 0.29 316.29 118423.41
9522 -----------
9623 dcache_lock 179 [<ffffffff80378274>] _atomic_dec_and_lock+0x34/0x54
9724 dcache_lock 113 [<ffffffff802cc17b>] d_alloc+0x19a/0x1eb
9825 dcache_lock 99 [<ffffffff802ca0dc>] d_rehash+0x1b/0x44
9926 dcache_lock 104 [<ffffffff802cbca0>] d_instantiate+0x36/0x8a
10027 -----------
10128 dcache_lock 192 [<ffffffff80378274>] _atomic_dec_and_lock+0x34/0x54
10229 dcache_lock 98 [<ffffffff802ca0dc>] d_rehash+0x1b/0x44
10330 dcache_lock 72 [<ffffffff802cc17b>] d_alloc+0x19a/0x1eb
10431 dcache_lock 112 [<ffffffff802cbca0>] d_instantiate+0x36/0x8a
92 105
93This excerpt shows the first two lock class statistics. Line 01 shows the 106This excerpt shows the first two lock class statistics. Line 01 shows the
94output version - each time the format changes this will be updated. Line 02-04 107output version - each time the format changes this will be updated. Line 02-04
95show the header with column descriptions. Lines 05-10 and 13-18 show the actual 108show the header with column descriptions. Lines 05-18 and 20-31 show the actual
96statistics. These statistics come in two parts; the actual stats separated by a 109statistics. These statistics come in two parts; the actual stats separated by a
97short separator (line 08, 14) from the contention points. 110short separator (line 08, 13) from the contention points.
98 111
99The first lock (05-10) is a read/write lock, and shows two lines above the 112The first lock (05-18) is a read/write lock, and shows two lines above the
100short separator. The contention points don't match the column descriptors, 113short separator. The contention points don't match the column descriptors,
101they have two: contentions and [<IP>] symbol. 114they have two: contentions and [<IP>] symbol. The second set of contention
115points are the points we're contending with.
102 116
117The integer part of the time values is in us.
103 118
104View the top contending locks: 119View the top contending locks:
105 120
diff --git a/Documentation/scsi/cxgb3i.txt b/Documentation/scsi/cxgb3i.txt
new file mode 100644
index 000000000000..8141fa01978e
--- /dev/null
+++ b/Documentation/scsi/cxgb3i.txt
@@ -0,0 +1,85 @@
1Chelsio S3 iSCSI Driver for Linux
2
3Introduction
4============
5
6The Chelsio T3 ASIC based Adapters (S310, S320, S302, S304, Mezz cards, etc.
7series of products) supports iSCSI acceleration and iSCSI Direct Data Placement
8(DDP) where the hardware handles the expensive byte touching operations, such
9as CRC computation and verification, and direct DMA to the final host memory
10destination:
11
12 - iSCSI PDU digest generation and verification
13
14 On transmitting, Chelsio S3 h/w computes and inserts the Header and
15 Data digest into the PDUs.
16 On receiving, Chelsio S3 h/w computes and verifies the Header and
17 Data digest of the PDUs.
18
19 - Direct Data Placement (DDP)
20
21 S3 h/w can directly place the iSCSI Data-In or Data-Out PDU's
22 payload into pre-posted final destination host-memory buffers based
23 on the Initiator Task Tag (ITT) in Data-In or Target Task Tag (TTT)
24 in Data-Out PDUs.
25
26 - PDU Transmit and Recovery
27
28 On transmitting, S3 h/w accepts the complete PDU (header + data)
29 from the host driver, computes and inserts the digests, decomposes
30 the PDU into multiple TCP segments if necessary, and transmit all
31 the TCP segments onto the wire. It handles TCP retransmission if
32 needed.
33
34 On receving, S3 h/w recovers the iSCSI PDU by reassembling TCP
35 segments, separating the header and data, calculating and verifying
36 the digests, then forwards the header to the host. The payload data,
37 if possible, will be directly placed into the pre-posted host DDP
38 buffer. Otherwise, the payload data will be sent to the host too.
39
40The cxgb3i driver interfaces with open-iscsi initiator and provides the iSCSI
41acceleration through Chelsio hardware wherever applicable.
42
43Using the cxgb3i Driver
44=======================
45
46The following steps need to be taken to accelerates the open-iscsi initiator:
47
481. Load the cxgb3i driver: "modprobe cxgb3i"
49
50 The cxgb3i module registers a new transport class "cxgb3i" with open-iscsi.
51
52 * in the case of recompiling the kernel, the cxgb3i selection is located at
53 Device Drivers
54 SCSI device support --->
55 [*] SCSI low-level drivers --->
56 <M> Chelsio S3xx iSCSI support
57
582. Create an interface file located under /etc/iscsi/ifaces/ for the new
59 transport class "cxgb3i".
60
61 The content of the file should be in the following format:
62 iface.transport_name = cxgb3i
63 iface.net_ifacename = <ethX>
64 iface.ipaddress = <iscsi ip address>
65
66 * if iface.ipaddress is specified, <iscsi ip address> needs to be either the
67 same as the ethX's ip address or an address on the same subnet. Make
68 sure the ip address is unique in the network.
69
703. edit /etc/iscsi/iscsid.conf
71 The default setting for MaxRecvDataSegmentLength (131072) is too big,
72 replace "node.conn[0].iscsi.MaxRecvDataSegmentLength" to be a value no
73 bigger than 15360 (for example 8192):
74
75 node.conn[0].iscsi.MaxRecvDataSegmentLength = 8192
76
77 * The login would fail for a normal session if MaxRecvDataSegmentLength is
78 too big. A error message in the format of
79 "cxgb3i: ERR! MaxRecvSegmentLength <X> too big. Need to be <= <Y>."
80 would be logged to dmesg.
81
824. To direct open-iscsi traffic to go through cxgb3i's accelerated path,
83 "-I <iface file name>" option needs to be specified with most of the
84 iscsiadm command. <iface file name> is the transport interface file created
85 in step 2.
diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html
index afbe9ae7ee96..d749d41f647b 100644
--- a/Documentation/video4linux/API.html
+++ b/Documentation/video4linux/API.html
@@ -1,16 +1,27 @@
1<TITLE>V4L API</TITLE> 1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<H1>Video For Linux APIs</H1> 2<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
3<table border=0> 3 <head>
4<tr> 4 <meta content="text/html;charset=ISO-8859-2" http-equiv="Content-Type" />
5<td> 5 <title>V4L API</title>
6<A HREF=http://www.linuxtv.org/downloads/video4linux/API/V4L1_API.html> 6 </head>
7V4L original API</a> 7 <body>
8</td><td> 8 <h1>Video For Linux APIs</h1>
9Obsoleted by V4L2 API 9 <table border="0">
10</td></tr><tr><td> 10 <tr>
11<A HREF=http://www.linuxtv.org/downloads/video4linux/API/V4L2_API> 11 <td>
12V4L2 API</a> 12 <a href="http://www.linuxtv.org/downloads/video4linux/API/V4L1_API.html">V4L original API</a>
13</td><td> 13 </td>
14Should be used for new projects 14 <td>
15</td></tr> 15 Obsoleted by V4L2 API
16</table> 16 </td>
17 </tr>
18 <tr>
19 <td>
20 <a href="http://www.linuxtv.org/downloads/video4linux/API/V4L2_API">V4L2 API</a>
21 </td>
22 <td>Should be used for new projects
23 </td>
24 </tr>
25 </table>
26 </body>
27</html>
diff --git a/Documentation/video4linux/CARDLIST.bttv b/Documentation/video4linux/CARDLIST.bttv
index 60ba66836038..0d93fa1ac25e 100644
--- a/Documentation/video4linux/CARDLIST.bttv
+++ b/Documentation/video4linux/CARDLIST.bttv
@@ -104,8 +104,8 @@
104103 -> Grand X-Guard / Trust 814PCI [0304:0102] 104103 -> Grand X-Guard / Trust 814PCI [0304:0102]
105104 -> Nebula Electronics DigiTV [0071:0101] 105104 -> Nebula Electronics DigiTV [0071:0101]
106105 -> ProVideo PV143 [aa00:1430,aa00:1431,aa00:1432,aa00:1433,aa03:1433] 106105 -> ProVideo PV143 [aa00:1430,aa00:1431,aa00:1432,aa00:1433,aa03:1433]
107106 -> PHYTEC VD-009-X1 MiniDIN (bt878) 107106 -> PHYTEC VD-009-X1 VD-011 MiniDIN (bt878)
108107 -> PHYTEC VD-009-X1 Combi (bt878) 108107 -> PHYTEC VD-009-X1 VD-011 Combi (bt878)
109108 -> PHYTEC VD-009 MiniDIN (bt878) 109108 -> PHYTEC VD-009 MiniDIN (bt878)
110109 -> PHYTEC VD-009 Combi (bt878) 110109 -> PHYTEC VD-009 Combi (bt878)
111110 -> IVC-100 [ff00:a132] 111110 -> IVC-100 [ff00:a132]
@@ -151,3 +151,6 @@
151150 -> Geovision GV-600 [008a:763c] 151150 -> Geovision GV-600 [008a:763c]
152151 -> Kozumi KTV-01C 152151 -> Kozumi KTV-01C
153152 -> Encore ENL TV-FM-2 [1000:1801] 153152 -> Encore ENL TV-FM-2 [1000:1801]
154153 -> PHYTEC VD-012 (bt878)
155154 -> PHYTEC VD-012-X1 (bt878)
156155 -> PHYTEC VD-012-X2 (bt878)
diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885
index 64823ccacd69..35ea130e9898 100644
--- a/Documentation/video4linux/CARDLIST.cx23885
+++ b/Documentation/video4linux/CARDLIST.cx23885
@@ -11,3 +11,4 @@
11 10 -> DViCO FusionHDTV7 Dual Express [18ac:d618] 11 10 -> DViCO FusionHDTV7 Dual Express [18ac:d618]
12 11 -> DViCO FusionHDTV DVB-T Dual Express [18ac:db78] 12 11 -> DViCO FusionHDTV DVB-T Dual Express [18ac:db78]
13 12 -> Leadtek Winfast PxDVR3200 H [107d:6681] 13 12 -> Leadtek Winfast PxDVR3200 H [107d:6681]
14 13 -> Compro VideoMate E650F [185b:e800]
diff --git a/Documentation/video4linux/CARDLIST.cx88 b/Documentation/video4linux/CARDLIST.cx88
index a5227e308f4a..0d08f1edcf6d 100644
--- a/Documentation/video4linux/CARDLIST.cx88
+++ b/Documentation/video4linux/CARDLIST.cx88
@@ -2,7 +2,7 @@
2 1 -> Hauppauge WinTV 34xxx models [0070:3400,0070:3401] 2 1 -> Hauppauge WinTV 34xxx models [0070:3400,0070:3401]
3 2 -> GDI Black Gold [14c7:0106,14c7:0107] 3 2 -> GDI Black Gold [14c7:0106,14c7:0107]
4 3 -> PixelView [1554:4811] 4 3 -> PixelView [1554:4811]
5 4 -> ATI TV Wonder Pro [1002:00f8] 5 4 -> ATI TV Wonder Pro [1002:00f8,1002:00f9]
6 5 -> Leadtek Winfast 2000XP Expert [107d:6611,107d:6613] 6 5 -> Leadtek Winfast 2000XP Expert [107d:6611,107d:6613]
7 6 -> AverTV Studio 303 (M126) [1461:000b] 7 6 -> AverTV Studio 303 (M126) [1461:000b]
8 7 -> MSI TV-@nywhere Master [1462:8606] 8 7 -> MSI TV-@nywhere Master [1462:8606]
@@ -74,3 +74,6 @@
74 73 -> TeVii S420 DVB-S [d420:9022] 74 73 -> TeVii S420 DVB-S [d420:9022]
75 74 -> Prolink Pixelview Global Extreme [1554:4976] 75 74 -> Prolink Pixelview Global Extreme [1554:4976]
76 75 -> PROF 7300 DVB-S/S2 [B033:3033] 76 75 -> PROF 7300 DVB-S/S2 [B033:3033]
77 76 -> SATTRADE ST4200 DVB-S/S2 [b200:4200]
78 77 -> TBS 8910 DVB-S [8910:8888]
79 78 -> Prof 6200 DVB-S [b022:3022]
diff --git a/Documentation/video4linux/CARDLIST.em28xx b/Documentation/video4linux/CARDLIST.em28xx
index 187cc48d0924..75bded8a4aa2 100644
--- a/Documentation/video4linux/CARDLIST.em28xx
+++ b/Documentation/video4linux/CARDLIST.em28xx
@@ -1,5 +1,5 @@
1 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800] 1 0 -> Unknown EM2800 video grabber (em2800) [eb1a:2800]
2 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883] 2 1 -> Unknown EM2750/28xx video grabber (em2820/em2840) [eb1a:2820,eb1a:2821,eb1a:2860,eb1a:2861,eb1a:2870,eb1a:2881,eb1a:2883]
3 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036] 3 2 -> Terratec Cinergy 250 USB (em2820/em2840) [0ccd:0036]
4 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208] 4 3 -> Pinnacle PCTV USB 2 (em2820/em2840) [2304:0208]
5 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201] 5 4 -> Hauppauge WinTV USB 2 (em2820/em2840) [2040:4200,2040:4201]
@@ -12,9 +12,9 @@
12 11 -> Terratec Hybrid XS (em2880) [0ccd:0042] 12 11 -> Terratec Hybrid XS (em2880) [0ccd:0042]
13 12 -> Kworld PVR TV 2800 RF (em2820/em2840) 13 12 -> Kworld PVR TV 2800 RF (em2820/em2840)
14 13 -> Terratec Prodigy XS (em2880) [0ccd:0047] 14 13 -> Terratec Prodigy XS (em2880) [0ccd:0047]
15 14 -> Pixelview Prolink PlayTV USB 2.0 (em2820/em2840) [eb1a:2821] 15 14 -> Pixelview Prolink PlayTV USB 2.0 (em2820/em2840)
16 15 -> V-Gear PocketTV (em2800) 16 15 -> V-Gear PocketTV (em2800)
17 16 -> Hauppauge WinTV HVR 950 (em2883) [2040:6513,2040:6517,2040:651b,2040:651f] 17 16 -> Hauppauge WinTV HVR 950 (em2883) [2040:6513,2040:6517,2040:651b]
18 17 -> Pinnacle PCTV HD Pro Stick (em2880) [2304:0227] 18 17 -> Pinnacle PCTV HD Pro Stick (em2880) [2304:0227]
19 18 -> Hauppauge WinTV HVR 900 (R2) (em2880) [2040:6502] 19 18 -> Hauppauge WinTV HVR 900 (R2) (em2880) [2040:6502]
20 19 -> PointNix Intra-Oral Camera (em2860) 20 19 -> PointNix Intra-Oral Camera (em2860)
@@ -27,7 +27,6 @@
27 26 -> Hercules Smart TV USB 2.0 (em2820/em2840) 27 26 -> Hercules Smart TV USB 2.0 (em2820/em2840)
28 27 -> Pinnacle PCTV USB 2 (Philips FM1216ME) (em2820/em2840) 28 27 -> Pinnacle PCTV USB 2 (Philips FM1216ME) (em2820/em2840)
29 28 -> Leadtek Winfast USB II Deluxe (em2820/em2840) 29 28 -> Leadtek Winfast USB II Deluxe (em2820/em2840)
30 29 -> Pinnacle Dazzle DVC 100 (em2820/em2840)
31 30 -> Videology 20K14XUSB USB2.0 (em2820/em2840) 30 30 -> Videology 20K14XUSB USB2.0 (em2820/em2840)
32 31 -> Usbgear VD204v9 (em2821) 31 31 -> Usbgear VD204v9 (em2821)
33 32 -> Supercomp USB 2.0 TV (em2821) 32 32 -> Supercomp USB 2.0 TV (em2821)
@@ -57,3 +56,5 @@
57 56 -> Pinnacle Hybrid Pro (2) (em2882) [2304:0226] 56 56 -> Pinnacle Hybrid Pro (2) (em2882) [2304:0226]
58 57 -> Kworld PlusTV HD Hybrid 330 (em2883) [eb1a:a316] 57 57 -> Kworld PlusTV HD Hybrid 330 (em2883) [eb1a:a316]
59 58 -> Compro VideoMate ForYou/Stereo (em2820/em2840) [185b:2041] 58 58 -> Compro VideoMate ForYou/Stereo (em2820/em2840) [185b:2041]
59 60 -> Hauppauge WinTV HVR 850 (em2883) [2040:651f]
60 61 -> Pixelview PlayTV Box 4 USB 2.0 (em2820/em2840)
diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134
index dc67eef38ff9..335aef4dcaeb 100644
--- a/Documentation/video4linux/CARDLIST.saa7134
+++ b/Documentation/video4linux/CARDLIST.saa7134
@@ -10,7 +10,7 @@
10 9 -> Medion 5044 10 9 -> Medion 5044
11 10 -> Kworld/KuroutoShikou SAA7130-TVPCI 11 10 -> Kworld/KuroutoShikou SAA7130-TVPCI
12 11 -> Terratec Cinergy 600 TV [153b:1143] 12 11 -> Terratec Cinergy 600 TV [153b:1143]
13 12 -> Medion 7134 [16be:0003] 13 12 -> Medion 7134 [16be:0003,16be:5000]
14 13 -> Typhoon TV+Radio 90031 14 13 -> Typhoon TV+Radio 90031
15 14 -> ELSA EX-VISION 300TV [1048:226b] 15 14 -> ELSA EX-VISION 300TV [1048:226b]
16 15 -> ELSA EX-VISION 500TV [1048:226a] 16 15 -> ELSA EX-VISION 500TV [1048:226a]
@@ -151,3 +151,4 @@
151150 -> Zogis Real Angel 220 151150 -> Zogis Real Angel 220
152151 -> ADS Tech Instant HDTV [1421:0380] 152151 -> ADS Tech Instant HDTV [1421:0380]
153152 -> Asus Tiger Rev:1.00 [1043:4857] 153152 -> Asus Tiger Rev:1.00 [1043:4857]
154153 -> Kworld Plus TV Analog Lite PCI [17de:7128]
diff --git a/Documentation/video4linux/README.cx88 b/Documentation/video4linux/README.cx88
index 166d5960b1a9..35fae23f883b 100644
--- a/Documentation/video4linux/README.cx88
+++ b/Documentation/video4linux/README.cx88
@@ -1,4 +1,3 @@
1
2cx8800 release notes 1cx8800 release notes
3==================== 2====================
4 3
@@ -10,21 +9,20 @@ current status
10 9
11video 10video
12 - Basically works. 11 - Basically works.
13 - Some minor image quality glitches. 12 - For now, only capture and read(). Overlay isn't supported.
14 - For now only capture, overlay support isn't completed yet.
15 13
16audio 14audio
17 - The chip specs for the on-chip TV sound decoder are next 15 - The chip specs for the on-chip TV sound decoder are next
18 to useless :-/ 16 to useless :-/
19 - Neverless the builtin TV sound decoder starts working now, 17 - Neverless the builtin TV sound decoder starts working now,
20 at least for PAL-BG. Other TV norms need other code ... 18 at least for some standards.
21 FOR ANY REPORTS ON THIS PLEASE MENTION THE TV NORM YOU ARE 19 FOR ANY REPORTS ON THIS PLEASE MENTION THE TV NORM YOU ARE
22 USING. 20 USING.
23 - Most tuner chips do provide mono sound, which may or may not 21 - Most tuner chips do provide mono sound, which may or may not
24 be useable depending on the board design. With the Hauppauge 22 be useable depending on the board design. With the Hauppauge
25 cards it works, so there is mono sound available as fallback. 23 cards it works, so there is mono sound available as fallback.
26 - audio data dma (i.e. recording without loopback cable to the 24 - audio data dma (i.e. recording without loopback cable to the
27 sound card) should be possible, but there is no code yet ... 25 sound card) is supported via cx88-alsa.
28 26
29vbi 27vbi
30 - Code present. Works for NTSC closed caption. PAL and other 28 - Code present. Works for NTSC closed caption. PAL and other
diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt
index 004818fab040..1c58a7630146 100644
--- a/Documentation/video4linux/gspca.txt
+++ b/Documentation/video4linux/gspca.txt
@@ -50,9 +50,14 @@ ov519 045e:028c Micro$oft xbox cam
50spca508 0461:0815 Micro Innovation IC200 50spca508 0461:0815 Micro Innovation IC200
51sunplus 0461:0821 Fujifilm MV-1 51sunplus 0461:0821 Fujifilm MV-1
52zc3xx 0461:0a00 MicroInnovation WebCam320 52zc3xx 0461:0a00 MicroInnovation WebCam320
53stv06xx 046d:0840 QuickCam Express
54stv06xx 046d:0850 LEGO cam / QuickCam Web
55stv06xx 046d:0870 Dexxa WebCam USB
53spca500 046d:0890 Logitech QuickCam traveler 56spca500 046d:0890 Logitech QuickCam traveler
54vc032x 046d:0892 Logitech Orbicam 57vc032x 046d:0892 Logitech Orbicam
55vc032x 046d:0896 Logitech Orbicam 58vc032x 046d:0896 Logitech Orbicam
59vc032x 046d:0897 Logitech QuickCam for Dell notebooks
60zc3xx 046d:089d Logitech QuickCam E2500
56zc3xx 046d:08a0 Logitech QC IM 61zc3xx 046d:08a0 Logitech QC IM
57zc3xx 046d:08a1 Logitech QC IM 0x08A1 +sound 62zc3xx 046d:08a1 Logitech QC IM 0x08A1 +sound
58zc3xx 046d:08a2 Labtec Webcam Pro 63zc3xx 046d:08a2 Labtec Webcam Pro
@@ -169,6 +174,9 @@ spca500 06bd:0404 Agfa CL20
169spca500 06be:0800 Optimedia 174spca500 06be:0800 Optimedia
170sunplus 06d6:0031 Trust 610 LCD PowerC@m Zoom 175sunplus 06d6:0031 Trust 610 LCD PowerC@m Zoom
171spca506 06e1:a190 ADS Instant VCD 176spca506 06e1:a190 ADS Instant VCD
177ov534 06f8:3002 Hercules Blog Webcam
178ov534 06f8:3003 Hercules Dualpix HD Weblog
179sonixj 06f8:3004 Hercules Classic Silver
172spca508 0733:0110 ViewQuest VQ110 180spca508 0733:0110 ViewQuest VQ110
173spca508 0130:0130 Clone Digital Webcam 11043 181spca508 0130:0130 Clone Digital Webcam 11043
174spca501 0733:0401 Intel Create and Share 182spca501 0733:0401 Intel Create and Share
@@ -199,7 +207,8 @@ sunplus 08ca:2050 Medion MD 41437
199sunplus 08ca:2060 Aiptek PocketDV5300 207sunplus 08ca:2060 Aiptek PocketDV5300
200tv8532 0923:010f ICM532 cams 208tv8532 0923:010f ICM532 cams
201mars 093a:050f Mars-Semi Pc-Camera 209mars 093a:050f Mars-Semi Pc-Camera
202pac207 093a:2460 PAC207 Qtec Webcam 100 210pac207 093a:2460 Qtec Webcam 100
211pac207 093a:2461 HP Webcam
203pac207 093a:2463 Philips SPC 220 NC 212pac207 093a:2463 Philips SPC 220 NC
204pac207 093a:2464 Labtec Webcam 1200 213pac207 093a:2464 Labtec Webcam 1200
205pac207 093a:2468 PAC207 214pac207 093a:2468 PAC207
@@ -213,10 +222,13 @@ pac7311 093a:2603 PAC7312
213pac7311 093a:2608 Trust WB-3300p 222pac7311 093a:2608 Trust WB-3300p
214pac7311 093a:260e Gigaware VGA PC Camera, Trust WB-3350p, SIGMA cam 2350 223pac7311 093a:260e Gigaware VGA PC Camera, Trust WB-3350p, SIGMA cam 2350
215pac7311 093a:260f SnakeCam 224pac7311 093a:260f SnakeCam
225pac7311 093a:2620 Apollo AC-905
216pac7311 093a:2621 PAC731x 226pac7311 093a:2621 PAC731x
227pac7311 093a:2622 Genius Eye 312
217pac7311 093a:2624 PAC7302 228pac7311 093a:2624 PAC7302
218pac7311 093a:2626 Labtec 2200 229pac7311 093a:2626 Labtec 2200
219pac7311 093a:262a Webcam 300k 230pac7311 093a:262a Webcam 300k
231pac7311 093a:262c Philips SPC 230 NC
220zc3xx 0ac8:0302 Z-star Vimicro zc0302 232zc3xx 0ac8:0302 Z-star Vimicro zc0302
221vc032x 0ac8:0321 Vimicro generic vc0321 233vc032x 0ac8:0321 Vimicro generic vc0321
222vc032x 0ac8:0323 Vimicro Vc0323 234vc032x 0ac8:0323 Vimicro Vc0323
@@ -249,11 +261,13 @@ sonixj 0c45:60c0 Sangha Sn535
249sonixj 0c45:60ec SN9C105+MO4000 261sonixj 0c45:60ec SN9C105+MO4000
250sonixj 0c45:60fb Surfer NoName 262sonixj 0c45:60fb Surfer NoName
251sonixj 0c45:60fc LG-LIC300 263sonixj 0c45:60fc LG-LIC300
264sonixj 0c45:60fe Microdia Audio
252sonixj 0c45:6128 Microdia/Sonix SNP325 265sonixj 0c45:6128 Microdia/Sonix SNP325
253sonixj 0c45:612a Avant Camera 266sonixj 0c45:612a Avant Camera
254sonixj 0c45:612c Typhoon Rasy Cam 1.3MPix 267sonixj 0c45:612c Typhoon Rasy Cam 1.3MPix
255sonixj 0c45:6130 Sonix Pccam 268sonixj 0c45:6130 Sonix Pccam
256sonixj 0c45:6138 Sn9c120 Mo4000 269sonixj 0c45:6138 Sn9c120 Mo4000
270sonixj 0c45:613a Microdia Sonix PC Camera
257sonixj 0c45:613b Surfer SN-206 271sonixj 0c45:613b Surfer SN-206
258sonixj 0c45:613c Sonix Pccam168 272sonixj 0c45:613c Sonix Pccam168
259sonixj 0c45:6143 Sonix Pccam168 273sonixj 0c45:6143 Sonix Pccam168
@@ -263,6 +277,9 @@ etoms 102c:6251 Qcam xxxxxx VGA
263zc3xx 10fd:0128 Typhoon Webshot II USB 300k 0x0128 277zc3xx 10fd:0128 Typhoon Webshot II USB 300k 0x0128
264spca561 10fd:7e50 FlyCam Usb 100 278spca561 10fd:7e50 FlyCam Usb 100
265zc3xx 10fd:8050 Typhoon Webshot II USB 300k 279zc3xx 10fd:8050 Typhoon Webshot II USB 300k
280ov534 1415:2000 Sony HD Eye for PS3 (SLEH 00201)
281pac207 145f:013a Trust WB-1300N
282vc032x 15b8:6002 HP 2.0 Megapixel rz406aa
266spca501 1776:501c Arowana 300K CMOS Camera 283spca501 1776:501c Arowana 300K CMOS Camera
267t613 17a1:0128 TASCORP JPEG Webcam, NGS Cyclops 284t613 17a1:0128 TASCORP JPEG Webcam, NGS Cyclops
268vc032x 17ef:4802 Lenovo Vc0323+MI1310_SOC 285vc032x 17ef:4802 Lenovo Vc0323+MI1310_SOC
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
new file mode 100644
index 000000000000..eeae76c22a93
--- /dev/null
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -0,0 +1,520 @@
1Overview of the V4L2 driver framework
2=====================================
3
4This text documents the various structures provided by the V4L2 framework and
5their relationships.
6
7
8Introduction
9------------
10
11The V4L2 drivers tend to be very complex due to the complexity of the
12hardware: most devices have multiple ICs, export multiple device nodes in
13/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input
14(IR) devices.
15
16Especially the fact that V4L2 drivers have to setup supporting ICs to
17do audio/video muxing/encoding/decoding makes it more complex than most.
18Usually these ICs are connected to the main bridge driver through one or
19more I2C busses, but other busses can also be used. Such devices are
20called 'sub-devices'.
21
22For a long time the framework was limited to the video_device struct for
23creating V4L device nodes and video_buf for handling the video buffers
24(note that this document does not discuss the video_buf framework).
25
26This meant that all drivers had to do the setup of device instances and
27connecting to sub-devices themselves. Some of this is quite complicated
28to do right and many drivers never did do it correctly.
29
30There is also a lot of common code that could never be refactored due to
31the lack of a framework.
32
33So this framework sets up the basic building blocks that all drivers
34need and this same framework should make it much easier to refactor
35common code into utility functions shared by all drivers.
36
37
38Structure of a driver
39---------------------
40
41All drivers have the following structure:
42
431) A struct for each device instance containing the device state.
44
452) A way of initializing and commanding sub-devices (if any).
46
473) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX, /dev/radioX and
48 /dev/vtxX) and keeping track of device-node specific data.
49
504) Filehandle-specific structs containing per-filehandle data.
51
52This is a rough schematic of how it all relates:
53
54 device instances
55 |
56 +-sub-device instances
57 |
58 \-V4L2 device nodes
59 |
60 \-filehandle instances
61
62
63Structure of the framework
64--------------------------
65
66The framework closely resembles the driver structure: it has a v4l2_device
67struct for the device instance data, a v4l2_subdev struct to refer to
68sub-device instances, the video_device struct stores V4L2 device node data
69and in the future a v4l2_fh struct will keep track of filehandle instances
70(this is not yet implemented).
71
72
73struct v4l2_device
74------------------
75
76Each device instance is represented by a struct v4l2_device (v4l2-device.h).
77Very simple devices can just allocate this struct, but most of the time you
78would embed this struct inside a larger struct.
79
80You must register the device instance:
81
82 v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
83
84Registration will initialize the v4l2_device struct and link dev->driver_data
85to v4l2_dev. Registration will also set v4l2_dev->name to a value derived from
86dev (driver name followed by the bus_id, to be precise). You may change the
87name after registration if you want.
88
89The first 'dev' argument is normally the struct device pointer of a pci_dev,
90usb_device or platform_device.
91
92You unregister with:
93
94 v4l2_device_unregister(struct v4l2_device *v4l2_dev);
95
96Unregistering will also automatically unregister all subdevs from the device.
97
98Sometimes you need to iterate over all devices registered by a specific
99driver. This is usually the case if multiple device drivers use the same
100hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
101hardware. The same is true for alsa drivers for example.
102
103You can iterate over all registered devices as follows:
104
105static int callback(struct device *dev, void *p)
106{
107 struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
108
109 /* test if this device was inited */
110 if (v4l2_dev == NULL)
111 return 0;
112 ...
113 return 0;
114}
115
116int iterate(void *p)
117{
118 struct device_driver *drv;
119 int err;
120
121 /* Find driver 'ivtv' on the PCI bus.
122 pci_bus_type is a global. For USB busses use usb_bus_type. */
123 drv = driver_find("ivtv", &pci_bus_type);
124 /* iterate over all ivtv device instances */
125 err = driver_for_each_device(drv, NULL, p, callback);
126 put_driver(drv);
127 return err;
128}
129
130Sometimes you need to keep a running counter of the device instance. This is
131commonly used to map a device instance to an index of a module option array.
132
133The recommended approach is as follows:
134
135static atomic_t drv_instance = ATOMIC_INIT(0);
136
137static int __devinit drv_probe(struct pci_dev *dev,
138 const struct pci_device_id *pci_id)
139{
140 ...
141 state->instance = atomic_inc_return(&drv_instance) - 1;
142}
143
144
145struct v4l2_subdev
146------------------
147
148Many drivers need to communicate with sub-devices. These devices can do all
149sort of tasks, but most commonly they handle audio and/or video muxing,
150encoding or decoding. For webcams common sub-devices are sensors and camera
151controllers.
152
153Usually these are I2C devices, but not necessarily. In order to provide the
154driver with a consistent interface to these sub-devices the v4l2_subdev struct
155(v4l2-subdev.h) was created.
156
157Each sub-device driver must have a v4l2_subdev struct. This struct can be
158stand-alone for simple sub-devices or it might be embedded in a larger struct
159if more state information needs to be stored. Usually there is a low-level
160device struct (e.g. i2c_client) that contains the device data as setup
161by the kernel. It is recommended to store that pointer in the private
162data of v4l2_subdev using v4l2_set_subdevdata(). That makes it easy to go
163from a v4l2_subdev to the actual low-level bus-specific device data.
164
165You also need a way to go from the low-level struct to v4l2_subdev. For the
166common i2c_client struct the i2c_set_clientdata() call is used to store a
167v4l2_subdev pointer, for other busses you may have to use other methods.
168
169From the bridge driver perspective you load the sub-device module and somehow
170obtain the v4l2_subdev pointer. For i2c devices this is easy: you call
171i2c_get_clientdata(). For other busses something similar needs to be done.
172Helper functions exists for sub-devices on an I2C bus that do most of this
173tricky work for you.
174
175Each v4l2_subdev contains function pointers that sub-device drivers can
176implement (or leave NULL if it is not applicable). Since sub-devices can do
177so many different things and you do not want to end up with a huge ops struct
178of which only a handful of ops are commonly implemented, the function pointers
179are sorted according to category and each category has its own ops struct.
180
181The top-level ops struct contains pointers to the category ops structs, which
182may be NULL if the subdev driver does not support anything from that category.
183
184It looks like this:
185
186struct v4l2_subdev_core_ops {
187 int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_chip_ident *chip);
188 int (*log_status)(struct v4l2_subdev *sd);
189 int (*init)(struct v4l2_subdev *sd, u32 val);
190 ...
191};
192
193struct v4l2_subdev_tuner_ops {
194 ...
195};
196
197struct v4l2_subdev_audio_ops {
198 ...
199};
200
201struct v4l2_subdev_video_ops {
202 ...
203};
204
205struct v4l2_subdev_ops {
206 const struct v4l2_subdev_core_ops *core;
207 const struct v4l2_subdev_tuner_ops *tuner;
208 const struct v4l2_subdev_audio_ops *audio;
209 const struct v4l2_subdev_video_ops *video;
210};
211
212The core ops are common to all subdevs, the other categories are implemented
213depending on the sub-device. E.g. a video device is unlikely to support the
214audio ops and vice versa.
215
216This setup limits the number of function pointers while still making it easy
217to add new ops and categories.
218
219A sub-device driver initializes the v4l2_subdev struct using:
220
221 v4l2_subdev_init(subdev, &ops);
222
223Afterwards you need to initialize subdev->name with a unique name and set the
224module owner. This is done for you if you use the i2c helper functions.
225
226A device (bridge) driver needs to register the v4l2_subdev with the
227v4l2_device:
228
229 int err = v4l2_device_register_subdev(device, subdev);
230
231This can fail if the subdev module disappeared before it could be registered.
232After this function was called successfully the subdev->dev field points to
233the v4l2_device.
234
235You can unregister a sub-device using:
236
237 v4l2_device_unregister_subdev(subdev);
238
239Afterwards the subdev module can be unloaded and subdev->dev == NULL.
240
241You can call an ops function either directly:
242
243 err = subdev->ops->core->g_chip_ident(subdev, &chip);
244
245but it is better and easier to use this macro:
246
247 err = v4l2_subdev_call(subdev, core, g_chip_ident, &chip);
248
249The macro will to the right NULL pointer checks and returns -ENODEV if subdev
250is NULL, -ENOIOCTLCMD if either subdev->core or subdev->core->g_chip_ident is
251NULL, or the actual result of the subdev->ops->core->g_chip_ident ops.
252
253It is also possible to call all or a subset of the sub-devices:
254
255 v4l2_device_call_all(dev, 0, core, g_chip_ident, &chip);
256
257Any subdev that does not support this ops is skipped and error results are
258ignored. If you want to check for errors use this:
259
260 err = v4l2_device_call_until_err(dev, 0, core, g_chip_ident, &chip);
261
262Any error except -ENOIOCTLCMD will exit the loop with that error. If no
263errors (except -ENOIOCTLCMD) occured, then 0 is returned.
264
265The second argument to both calls is a group ID. If 0, then all subdevs are
266called. If non-zero, then only those whose group ID match that value will
267be called. Before a bridge driver registers a subdev it can set subdev->grp_id
268to whatever value it wants (it's 0 by default). This value is owned by the
269bridge driver and the sub-device driver will never modify or use it.
270
271The group ID gives the bridge driver more control how callbacks are called.
272For example, there may be multiple audio chips on a board, each capable of
273changing the volume. But usually only one will actually be used when the
274user want to change the volume. You can set the group ID for that subdev to
275e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
276v4l2_device_call_all(). That ensures that it will only go to the subdev
277that needs it.
278
279The advantage of using v4l2_subdev is that it is a generic struct and does
280not contain any knowledge about the underlying hardware. So a driver might
281contain several subdevs that use an I2C bus, but also a subdev that is
282controlled through GPIO pins. This distinction is only relevant when setting
283up the device, but once the subdev is registered it is completely transparent.
284
285
286I2C sub-device drivers
287----------------------
288
289Since these drivers are so common, special helper functions are available to
290ease the use of these drivers (v4l2-common.h).
291
292The recommended method of adding v4l2_subdev support to an I2C driver is to
293embed the v4l2_subdev struct into the state struct that is created for each
294I2C device instance. Very simple devices have no state struct and in that case
295you can just create a v4l2_subdev directly.
296
297A typical state struct would look like this (where 'chipname' is replaced by
298the name of the chip):
299
300struct chipname_state {
301 struct v4l2_subdev sd;
302 ... /* additional state fields */
303};
304
305Initialize the v4l2_subdev struct as follows:
306
307 v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
308
309This function will fill in all the fields of v4l2_subdev and ensure that the
310v4l2_subdev and i2c_client both point to one another.
311
312You should also add a helper inline function to go from a v4l2_subdev pointer
313to a chipname_state struct:
314
315static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
316{
317 return container_of(sd, struct chipname_state, sd);
318}
319
320Use this to go from the v4l2_subdev struct to the i2c_client struct:
321
322 struct i2c_client *client = v4l2_get_subdevdata(sd);
323
324And this to go from an i2c_client to a v4l2_subdev struct:
325
326 struct v4l2_subdev *sd = i2c_get_clientdata(client);
327
328Finally you need to make a command function to make driver->command()
329call the right subdev_ops functions:
330
331static int subdev_command(struct i2c_client *client, unsigned cmd, void *arg)
332{
333 return v4l2_subdev_command(i2c_get_clientdata(client), cmd, arg);
334}
335
336If driver->command is never used then you can leave this out. Eventually the
337driver->command usage should be removed from v4l.
338
339Make sure to call v4l2_device_unregister_subdev(sd) when the remove() callback
340is called. This will unregister the sub-device from the bridge driver. It is
341safe to call this even if the sub-device was never registered.
342
343
344The bridge driver also has some helper functions it can use:
345
346struct v4l2_subdev *sd = v4l2_i2c_new_subdev(adapter, "module_foo", "chipid", 0x36);
347
348This loads the given module (can be NULL if no module needs to be loaded) and
349calls i2c_new_device() with the given i2c_adapter and chip/address arguments.
350If all goes well, then it registers the subdev with the v4l2_device. It gets
351the v4l2_device by calling i2c_get_adapdata(adapter), so you should make sure
352that adapdata is set to v4l2_device when you setup the i2c_adapter in your
353driver.
354
355You can also use v4l2_i2c_new_probed_subdev() which is very similar to
356v4l2_i2c_new_subdev(), except that it has an array of possible I2C addresses
357that it should probe. Internally it calls i2c_new_probed_device().
358
359Both functions return NULL if something went wrong.
360
361
362struct video_device
363-------------------
364
365The actual device nodes in the /dev directory are created using the
366video_device struct (v4l2-dev.h). This struct can either be allocated
367dynamically or embedded in a larger struct.
368
369To allocate it dynamically use:
370
371 struct video_device *vdev = video_device_alloc();
372
373 if (vdev == NULL)
374 return -ENOMEM;
375
376 vdev->release = video_device_release;
377
378If you embed it in a larger struct, then you must set the release()
379callback to your own function:
380
381 struct video_device *vdev = &my_vdev->vdev;
382
383 vdev->release = my_vdev_release;
384
385The release callback must be set and it is called when the last user
386of the video device exits.
387
388The default video_device_release() callback just calls kfree to free the
389allocated memory.
390
391You should also set these fields:
392
393- parent: set to the parent device (same device as was used to register
394 v4l2_device).
395- name: set to something descriptive and unique.
396- fops: set to the file_operations struct.
397- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
398 (highly recommended to use this and it might become compulsory in the
399 future!), then set this to your v4l2_ioctl_ops struct.
400
401If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to
402__video_ioctl2 or .ioctl to video_ioctl2 in your file_operations struct.
403
404
405video_device registration
406-------------------------
407
408Next you register the video device: this will create the character device
409for you.
410
411 err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
412 if (err) {
413 video_device_release(vdev); // or kfree(my_vdev);
414 return err;
415 }
416
417Which device is registered depends on the type argument. The following
418types exist:
419
420VFL_TYPE_GRABBER: videoX for video input/output devices
421VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
422VFL_TYPE_RADIO: radioX for radio tuners
423VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use)
424
425The last argument gives you a certain amount of control over the device
426kernel number used (i.e. the X in videoX). Normally you will pass -1 to
427let the v4l2 framework pick the first free number. But if a driver creates
428many devices, then it can be useful to have different video devices in
429separate ranges. For example, video capture devices start at 0, video
430output devices start at 16.
431
432So you can use the last argument to specify a minimum kernel number and
433the v4l2 framework will try to pick the first free number that is equal
434or higher to what you passed. If that fails, then it will just pick the
435first free number.
436
437Whenever a device node is created some attributes are also created for you.
438If you look in /sys/class/video4linux you see the devices. Go into e.g.
439video0 and you will see 'name' and 'index' attributes. The 'name' attribute
440is the 'name' field of the video_device struct. The 'index' attribute is
441a device node index that can be assigned by the driver, or that is calculated
442for you.
443
444If you call video_register_device(), then the index is just increased by
4451 for each device node you register. The first video device node you register
446always starts off with 0.
447
448Alternatively you can call video_register_device_index() which is identical
449to video_register_device(), but with an extra index argument. Here you can
450pass a specific index value (between 0 and 31) that should be used.
451
452Users can setup udev rules that utilize the index attribute to make fancy
453device names (e.g. 'mpegX' for MPEG video capture device nodes).
454
455After the device was successfully registered, then you can use these fields:
456
457- vfl_type: the device type passed to video_register_device.
458- minor: the assigned device minor number.
459- num: the device kernel number (i.e. the X in videoX).
460- index: the device index number (calculated or set explicitly using
461 video_register_device_index).
462
463If the registration failed, then you need to call video_device_release()
464to free the allocated video_device struct, or free your own struct if the
465video_device was embedded in it. The vdev->release() callback will never
466be called if the registration failed, nor should you ever attempt to
467unregister the device if the registration failed.
468
469
470video_device cleanup
471--------------------
472
473When the video device nodes have to be removed, either during the unload
474of the driver or because the USB device was disconnected, then you should
475unregister them:
476
477 video_unregister_device(vdev);
478
479This will remove the device nodes from sysfs (causing udev to remove them
480from /dev).
481
482After video_unregister_device() returns no new opens can be done.
483
484However, in the case of USB devices some application might still have one
485of these device nodes open. You should block all new accesses to read,
486write, poll, etc. except possibly for certain ioctl operations like
487queueing buffers.
488
489When the last user of the video device node exits, then the vdev->release()
490callback is called and you can do the final cleanup there.
491
492
493video_device helper functions
494-----------------------------
495
496There are a few useful helper functions:
497
498You can set/get driver private data in the video_device struct using:
499
500void *video_get_drvdata(struct video_device *dev);
501void video_set_drvdata(struct video_device *dev, void *data);
502
503Note that you can safely call video_set_drvdata() before calling
504video_register_device().
505
506And this function:
507
508struct video_device *video_devdata(struct file *file);
509
510returns the video_device belonging to the file struct.
511
512The final helper function combines video_get_drvdata with
513video_devdata:
514
515void *video_drvdata(struct file *file);
516
517You can go from a video_device struct to the v4l2_device struct using:
518
519struct v4l2_device *v4l2_dev = dev_get_drvdata(vdev->parent);
520