aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/video4linux')
-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.saa71344
-rw-r--r--Documentation/video4linux/README.cx888
-rw-r--r--Documentation/video4linux/gspca.txt19
-rw-r--r--Documentation/video4linux/si470x.txt1
-rw-r--r--Documentation/video4linux/v4l2-framework.txt521
10 files changed, 588 insertions, 30 deletions
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..b8d470596b0c 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,5 @@
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]
155154 -> Avermedia AVerTV GO 007 FM Plus [1461:f31d]
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/si470x.txt b/Documentation/video4linux/si470x.txt
index 11c5fd22a332..49679e6aaa76 100644
--- a/Documentation/video4linux/si470x.txt
+++ b/Documentation/video4linux/si470x.txt
@@ -41,6 +41,7 @@ chips are known to work:
41- 10c4:818a: Silicon Labs USB FM Radio Reference Design 41- 10c4:818a: Silicon Labs USB FM Radio Reference Design
42- 06e1:a155: ADS/Tech FM Radio Receiver (formerly Instant FM Music) (RDX-155-EF) 42- 06e1:a155: ADS/Tech FM Radio Receiver (formerly Instant FM Music) (RDX-155-EF)
43- 1b80:d700: KWorld USB FM Radio SnapMusic Mobile 700 (FM700) 43- 1b80:d700: KWorld USB FM Radio SnapMusic Mobile 700 (FM700)
44- 10c5:819a: DealExtreme USB Radio
44 45
45 46
46Software 47Software
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
new file mode 100644
index 000000000000..ff124374e9ba
--- /dev/null
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -0,0 +1,521 @@
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_dbg_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- v4l2_dev: set to the v4l2_device parent device.
394- name: set to something descriptive and unique.
395- fops: set to the v4l2_file_operations struct.
396- ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance
397 (highly recommended to use this and it might become compulsory in the
398 future!), then set this to your v4l2_ioctl_ops struct.
399
400If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or
401.ioctl to video_ioctl2 in your v4l2_file_operations struct.
402
403The v4l2_file_operations struct is a subset of file_operations. The main
404difference is that the inode argument is omitted since it is never used.
405
406
407video_device registration
408-------------------------
409
410Next you register the video device: this will create the character device
411for you.
412
413 err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
414 if (err) {
415 video_device_release(vdev); /* or kfree(my_vdev); */
416 return err;
417 }
418
419Which device is registered depends on the type argument. The following
420types exist:
421
422VFL_TYPE_GRABBER: videoX for video input/output devices
423VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext)
424VFL_TYPE_RADIO: radioX for radio tuners
425VFL_TYPE_VTX: vtxX for teletext devices (deprecated, don't use)
426
427The last argument gives you a certain amount of control over the device
428kernel number used (i.e. the X in videoX). Normally you will pass -1 to
429let the v4l2 framework pick the first free number. But if a driver creates
430many devices, then it can be useful to have different video devices in
431separate ranges. For example, video capture devices start at 0, video
432output devices start at 16.
433
434So you can use the last argument to specify a minimum kernel number and
435the v4l2 framework will try to pick the first free number that is equal
436or higher to what you passed. If that fails, then it will just pick the
437first free number.
438
439Whenever a device node is created some attributes are also created for you.
440If you look in /sys/class/video4linux you see the devices. Go into e.g.
441video0 and you will see 'name' and 'index' attributes. The 'name' attribute
442is the 'name' field of the video_device struct. The 'index' attribute is
443a device node index that can be assigned by the driver, or that is calculated
444for you.
445
446If you call video_register_device(), then the index is just increased by
4471 for each device node you register. The first video device node you register
448always starts off with 0.
449
450Alternatively you can call video_register_device_index() which is identical
451to video_register_device(), but with an extra index argument. Here you can
452pass a specific index value (between 0 and 31) that should be used.
453
454Users can setup udev rules that utilize the index attribute to make fancy
455device names (e.g. 'mpegX' for MPEG video capture device nodes).
456
457After the device was successfully registered, then you can use these fields:
458
459- vfl_type: the device type passed to video_register_device.
460- minor: the assigned device minor number.
461- num: the device kernel number (i.e. the X in videoX).
462- index: the device index number (calculated or set explicitly using
463 video_register_device_index).
464
465If the registration failed, then you need to call video_device_release()
466to free the allocated video_device struct, or free your own struct if the
467video_device was embedded in it. The vdev->release() callback will never
468be called if the registration failed, nor should you ever attempt to
469unregister the device if the registration failed.
470
471
472video_device cleanup
473--------------------
474
475When the video device nodes have to be removed, either during the unload
476of the driver or because the USB device was disconnected, then you should
477unregister them:
478
479 video_unregister_device(vdev);
480
481This will remove the device nodes from sysfs (causing udev to remove them
482from /dev).
483
484After video_unregister_device() returns no new opens can be done.
485
486However, in the case of USB devices some application might still have one
487of these device nodes open. You should block all new accesses to read,
488write, poll, etc. except possibly for certain ioctl operations like
489queueing buffers.
490
491When the last user of the video device node exits, then the vdev->release()
492callback is called and you can do the final cleanup there.
493
494
495video_device helper functions
496-----------------------------
497
498There are a few useful helper functions:
499
500You can set/get driver private data in the video_device struct using:
501
502void *video_get_drvdata(struct video_device *dev);
503void video_set_drvdata(struct video_device *dev, void *data);
504
505Note that you can safely call video_set_drvdata() before calling
506video_register_device().
507
508And this function:
509
510struct video_device *video_devdata(struct file *file);
511
512returns the video_device belonging to the file struct.
513
514The final helper function combines video_get_drvdata with
515video_devdata:
516
517void *video_drvdata(struct file *file);
518
519You can go from a video_device struct to the v4l2_device struct using:
520
521struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-17 16:25:42 -0500