Commit | Line | Data |
---|---|---|
1da177e4 | 1 | |
6e204090 MK |
2 | W996[87]CF JPEG USB Dual Mode Camera Chip |
3 | Driver for Linux 2.6 (basic version) | |
4 | ========================================= | |
1da177e4 | 5 | |
6e204090 | 6 | - Documentation - |
1da177e4 LT |
7 | |
8 | ||
9 | Index | |
10 | ===== | |
11 | 1. Copyright | |
12 | 2. Disclaimer | |
13 | 3. License | |
14 | 4. Overview | |
15 | 5. Supported devices | |
16 | 6. Module dependencies | |
17 | 7. Module loading | |
992caacf | 18 | 8. Module parameters |
1da177e4 LT |
19 | 9. Contact information |
20 | 10. Credits | |
21 | ||
22 | ||
23 | 1. Copyright | |
24 | ============ | |
25 | Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it> | |
26 | ||
27 | ||
28 | 2. Disclaimer | |
29 | ============= | |
30 | Winbond is a trademark of Winbond Electronics Corporation. | |
31 | This software is not sponsored or developed by Winbond. | |
32 | ||
33 | ||
34 | 3. License | |
35 | ========== | |
36 | This program is free software; you can redistribute it and/or modify | |
37 | it under the terms of the GNU General Public License as published by | |
38 | the Free Software Foundation; either version 2 of the License, or | |
39 | (at your option) any later version. | |
40 | ||
41 | This program is distributed in the hope that it will be useful, | |
42 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
43 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
44 | GNU General Public License for more details. | |
45 | ||
46 | You should have received a copy of the GNU General Public License | |
47 | along with this program; if not, write to the Free Software | |
48 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
49 | ||
50 | ||
51 | 4. Overview | |
52 | =========== | |
53 | This driver supports the video streaming capabilities of the devices mounting | |
54 | Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681 | |
55 | based cameras should be supported as well. | |
56 | ||
57 | The driver is divided into two modules: the basic one, "w9968cf", is needed for | |
58 | the supported devices to work; the second one, "w9968cf-vpp", is an optional | |
59 | module, which provides some useful video post-processing functions like video | |
7f2c01ab | 60 | decoding, up-scaling and colour conversions. |
1da177e4 | 61 | |
7f2c01ab AB |
62 | Note that the official kernels do neither include nor support the second |
63 | module for performance purposes. Therefore, it is always recommended to | |
64 | download and install the latest and complete release of the driver, | |
65 | replacing the existing one, if present. | |
1da177e4 LT |
66 | |
67 | The latest and full-featured version of the W996[87]CF driver can be found at: | |
68 | http://www.linux-projects.org. Please refer to the documentation included in | |
69 | that package, if you are going to use it. | |
70 | ||
71 | Up to 32 cameras can be handled at the same time. They can be connected and | |
72 | disconnected from the host many times without turning off the computer, if | |
73 | your system supports the hotplug facility. | |
74 | ||
75 | To change the default settings for each camera, many parameters can be passed | |
76 | through command line when the module is loaded into memory. | |
77 | ||
78 | The driver relies on the Video4Linux, USB and I2C core modules. It has been | |
79 | designed to run properly on SMP systems as well. An additional module, | |
80 | "ovcamchip", is mandatory; it provides support for some OmniVision image | |
81 | sensors connected to the W996[87]CF chips; if found in the system, the module | |
82 | will be automatically loaded by default (provided that the kernel has been | |
83 | compiled with the automatic module loading option). | |
84 | ||
85 | ||
86 | 5. Supported devices | |
87 | ==================== | |
88 | At the moment, known W996[87]CF and OV681 based devices are: | |
89 | - Aroma Digi Pen VGA Dual Mode ADG-5000 (unknown image sensor) | |
90 | - AVerMedia AVerTV USB (SAA7111A, Philips FI1216Mk2 tuner, PT2313L audio chip) | |
91 | - Creative Labs Video Blaster WebCam Go (OmniVision OV7610 sensor) | |
92 | - Creative Labs Video Blaster WebCam Go Plus (OmniVision OV7620 sensor) | |
93 | - Lebon LDC-035A (unknown image sensor) | |
94 | - Ezonics EZ-802 EZMega Cam (OmniVision OV8610C sensor) | |
95 | - OmniVision OV8610-EDE (OmniVision OV8610 sensor) | |
96 | - OPCOM Digi Pen VGA Dual Mode Pen Camera (unknown image sensor) | |
97 | - Pretec Digi Pen-II (OmniVision OV7620 sensor) | |
98 | - Pretec DigiPen-480 (OmniVision OV8610 sensor) | |
99 | ||
100 | If you know any other W996[87]CF or OV681 based cameras, please contact me. | |
101 | ||
102 | The list above does not imply that all those devices work with this driver: up | |
103 | until now only webcams that have an image sensor supported by the "ovcamchip" | |
104 | module work. Kernel messages will always tell you whether this is case. | |
105 | ||
106 | Possible external microcontrollers of those webcams are not supported: this | |
107 | means that still images cannot be downloaded from the device memory. | |
108 | ||
109 | Furthermore, it's worth to note that I was only able to run tests on my | |
110 | "Creative Labs Video Blaster WebCam Go". Donations of other models, for | |
111 | additional testing and full support, would be much appreciated. | |
112 | ||
113 | ||
114 | 6. Module dependencies | |
115 | ====================== | |
116 | For it to work properly, the driver needs kernel support for Video4Linux, USB | |
117 | and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not | |
1864cfb1 | 118 | actually using any external "ovcamchip" module, given that the W996[87]CF |
1da177e4 LT |
119 | driver depends on the version of the module present in the official kernels. |
120 | ||
121 | The following options of the kernel configuration file must be enabled and | |
122 | corresponding modules must be compiled: | |
123 | ||
124 | # Multimedia devices | |
125 | # | |
126 | CONFIG_VIDEO_DEV=m | |
127 | ||
128 | # I2C support | |
129 | # | |
130 | CONFIG_I2C=m | |
131 | ||
132 | The I2C core module can be compiled statically in the kernel as well. | |
133 | ||
134 | # OmniVision Camera Chip support | |
135 | # | |
136 | CONFIG_VIDEO_OVCAMCHIP=m | |
137 | ||
138 | # USB support | |
139 | # | |
140 | CONFIG_USB=m | |
141 | ||
142 | In addition, depending on the hardware being used, only one of the modules | |
143 | below is necessary: | |
144 | ||
145 | # USB Host Controller Drivers | |
146 | # | |
147 | CONFIG_USB_EHCI_HCD=m | |
148 | CONFIG_USB_UHCI_HCD=m | |
149 | CONFIG_USB_OHCI_HCD=m | |
150 | ||
151 | And finally: | |
152 | ||
153 | # USB Multimedia devices | |
154 | # | |
155 | CONFIG_USB_W9968CF=m | |
156 | ||
157 | ||
158 | 7. Module loading | |
159 | ================= | |
160 | To use the driver, it is necessary to load the "w9968cf" module into memory | |
161 | after every other module required. | |
162 | ||
163 | Loading can be done this way, from root: | |
164 | ||
165 | [root@localhost home]# modprobe usbcore | |
166 | [root@localhost home]# modprobe i2c-core | |
167 | [root@localhost home]# modprobe videodev | |
168 | [root@localhost home]# modprobe w9968cf | |
169 | ||
170 | At this point the pertinent devices should be recognized: "dmesg" can be used | |
171 | to analyze kernel messages: | |
172 | ||
173 | [user@localhost home]$ dmesg | |
174 | ||
175 | There are a lot of parameters the module can use to change the default | |
176 | settings for each device. To list every possible parameter with a brief | |
177 | explanation about them and which syntax to use, it is recommended to run the | |
178 | "modinfo" command: | |
179 | ||
180 | [root@locahost home]# modinfo w9968cf | |
181 | ||
182 | ||
183 | 8. Module parameters | |
184 | ==================== | |
185 | Module parameters are listed below: | |
186 | ------------------------------------------------------------------------------- | |
187 | Name: ovmod_load | |
188 | Type: bool | |
189 | Syntax: <0|1> | |
190 | Description: Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled. | |
6e204090 MK |
191 | If enabled, 'insmod' searches for the required 'ovcamchip' |
192 | module in the system, according to its configuration, and | |
193 | loads that module automatically. This action is performed as | |
194 | once soon as the 'w9968cf' module is loaded into memory. | |
1da177e4 | 195 | Default: 1 |
1da177e4 | 196 | ------------------------------------------------------------------------------- |
1864cfb1 MK |
197 | Name: simcams |
198 | Type: int | |
199 | Syntax: <n> | |
1da177e4 | 200 | Description: Number of cameras allowed to stream simultaneously. |
6e204090 | 201 | n may vary from 0 to 32. |
1da177e4 LT |
202 | Default: 32 |
203 | ------------------------------------------------------------------------------- | |
204 | Name: video_nr | |
205 | Type: int array (min = 0, max = 32) | |
1864cfb1 | 206 | Syntax: <-1|n[,...]> |
1da177e4 | 207 | Description: Specify V4L minor mode number. |
6e204090 MK |
208 | -1 = use next available |
209 | n = use minor number n | |
210 | You can specify up to 32 cameras this way. | |
211 | For example: | |
212 | video_nr=-1,2,-1 would assign minor number 2 to the second | |
213 | recognized camera and use auto for the first one and for every | |
214 | other camera. | |
1da177e4 LT |
215 | Default: -1 |
216 | ------------------------------------------------------------------------------- | |
217 | Name: packet_size | |
218 | Type: int array (min = 0, max = 32) | |
1864cfb1 | 219 | Syntax: <n[,...]> |
1da177e4 | 220 | Description: Specify the maximum data payload size in bytes for alternate |
6e204090 | 221 | settings, for each device. n is scaled between 63 and 1023. |
1da177e4 LT |
222 | Default: 1023 |
223 | ------------------------------------------------------------------------------- | |
224 | Name: max_buffers | |
225 | Type: int array (min = 0, max = 32) | |
226 | Syntax: <n[,...]> | |
227 | Description: For advanced users. | |
6e204090 MK |
228 | Specify the maximum number of video frame buffers to allocate |
229 | for each device, from 2 to 32. | |
1da177e4 LT |
230 | Default: 2 |
231 | ------------------------------------------------------------------------------- | |
232 | Name: double_buffer | |
233 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 234 | Syntax: <0|1[,...]> |
1da177e4 | 235 | Description: Hardware double buffering: 0 disabled, 1 enabled. |
6e204090 MK |
236 | It should be enabled if you want smooth video output: if you |
237 | obtain out of sync. video, disable it, or try to | |
238 | decrease the 'clockdiv' module parameter value. | |
1da177e4 LT |
239 | Default: 1 for every device. |
240 | ------------------------------------------------------------------------------- | |
241 | Name: clamping | |
242 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 243 | Syntax: <0|1[,...]> |
1da177e4 LT |
244 | Description: Video data clamping: 0 disabled, 1 enabled. |
245 | Default: 0 for every device. | |
246 | ------------------------------------------------------------------------------- | |
247 | Name: filter_type | |
248 | Type: int array (min = 0, max = 32) | |
1864cfb1 | 249 | Syntax: <0|1|2[,...]> |
1da177e4 | 250 | Description: Video filter type. |
6e204090 MK |
251 | 0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter. |
252 | The filter is used to reduce noise and aliasing artifacts | |
253 | produced by the CCD or CMOS image sensor. | |
1da177e4 LT |
254 | Default: 0 for every device. |
255 | ------------------------------------------------------------------------------- | |
256 | Name: largeview | |
257 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 258 | Syntax: <0|1[,...]> |
1da177e4 LT |
259 | Description: Large view: 0 disabled, 1 enabled. |
260 | Default: 1 for every device. | |
261 | ------------------------------------------------------------------------------- | |
262 | Name: upscaling | |
263 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 264 | Syntax: <0|1[,...]> |
1da177e4 | 265 | Description: Software scaling (for non-compressed video only): |
6e204090 MK |
266 | 0 disabled, 1 enabled. |
267 | Disable it if you have a slow CPU or you don't have enough | |
268 | memory. | |
1da177e4 LT |
269 | Default: 0 for every device. |
270 | Note: If 'w9968cf-vpp' is not present, this parameter is set to 0. | |
271 | ------------------------------------------------------------------------------- | |
272 | Name: decompression | |
273 | Type: int array (min = 0, max = 32) | |
274 | Syntax: <0|1|2[,...]> | |
275 | Description: Software video decompression: | |
6e204090 MK |
276 | 0 = disables decompression |
277 | (doesn't allow formats needing decompression). | |
278 | 1 = forces decompression | |
279 | (allows formats needing decompression only). | |
280 | 2 = allows any permitted formats. | |
281 | Formats supporting (de)compressed video are YUV422P and | |
282 | YUV420P/YUV420 in any resolutions where width and height are | |
283 | multiples of 16. | |
1da177e4 LT |
284 | Default: 2 for every device. |
285 | Note: If 'w9968cf-vpp' is not present, forcing decompression is not | |
6e204090 | 286 | allowed; in this case this parameter is set to 2. |
1da177e4 LT |
287 | ------------------------------------------------------------------------------- |
288 | Name: force_palette | |
289 | Type: int array (min = 0, max = 32) | |
290 | Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]> | |
291 | Description: Force picture palette. | |
6e204090 MK |
292 | In order: |
293 | 0 = Off - allows any of the following formats: | |
294 | 9 = UYVY 16 bpp - Original video, compression disabled | |
295 | 10 = YUV420 12 bpp - Original video, compression enabled | |
296 | 13 = YUV422P 16 bpp - Original video, compression enabled | |
297 | 15 = YUV420P 12 bpp - Original video, compression enabled | |
298 | 8 = YUVY 16 bpp - Software conversion from UYVY | |
299 | 7 = YUV422 16 bpp - Software conversion from UYVY | |
300 | 1 = GREY 8 bpp - Software conversion from UYVY | |
301 | 6 = RGB555 16 bpp - Software conversion from UYVY | |
302 | 3 = RGB565 16 bpp - Software conversion from UYVY | |
303 | 4 = RGB24 24 bpp - Software conversion from UYVY | |
304 | 5 = RGB32 32 bpp - Software conversion from UYVY | |
305 | When not 0, this parameter will override 'decompression'. | |
1da177e4 LT |
306 | Default: 0 for every device. Initial palette is 9 (UYVY). |
307 | Note: If 'w9968cf-vpp' is not present, this parameter is set to 9. | |
308 | ------------------------------------------------------------------------------- | |
309 | Name: force_rgb | |
310 | Type: bool array (min = 0, max = 32) | |
311 | Syntax: <0|1[,...]> | |
312 | Description: Read RGB video data instead of BGR: | |
6e204090 MK |
313 | 1 = use RGB component ordering. |
314 | 0 = use BGR component ordering. | |
315 | This parameter has effect when using RGBX palettes only. | |
1da177e4 LT |
316 | Default: 0 for every device. |
317 | ------------------------------------------------------------------------------- | |
318 | Name: autobright | |
319 | Type: bool array (min = 0, max = 32) | |
320 | Syntax: <0|1[,...]> | |
321 | Description: Image sensor automatically changes brightness: | |
6e204090 | 322 | 0 = no, 1 = yes |
1da177e4 LT |
323 | Default: 0 for every device. |
324 | ------------------------------------------------------------------------------- | |
325 | Name: autoexp | |
326 | Type: bool array (min = 0, max = 32) | |
327 | Syntax: <0|1[,...]> | |
328 | Description: Image sensor automatically changes exposure: | |
6e204090 | 329 | 0 = no, 1 = yes |
1da177e4 LT |
330 | Default: 1 for every device. |
331 | ------------------------------------------------------------------------------- | |
332 | Name: lightfreq | |
333 | Type: int array (min = 0, max = 32) | |
334 | Syntax: <50|60[,...]> | |
335 | Description: Light frequency in Hz: | |
6e204090 | 336 | 50 for European and Asian lighting, 60 for American lighting. |
1da177e4 LT |
337 | Default: 50 for every device. |
338 | ------------------------------------------------------------------------------- | |
339 | Name: bandingfilter | |
340 | Type: bool array (min = 0, max = 32) | |
1864cfb1 MK |
341 | Syntax: <0|1[,...]> |
342 | Description: Banding filter to reduce effects of fluorescent | |
6e204090 MK |
343 | lighting: |
344 | 0 disabled, 1 enabled. | |
345 | This filter tries to reduce the pattern of horizontal | |
346 | light/dark bands caused by some (usually fluorescent) lighting. | |
1da177e4 LT |
347 | Default: 0 for every device. |
348 | ------------------------------------------------------------------------------- | |
349 | Name: clockdiv | |
350 | Type: int array (min = 0, max = 32) | |
351 | Syntax: <-1|n[,...]> | |
352 | Description: Force pixel clock divisor to a specific value (for experts): | |
6e204090 MK |
353 | n may vary from 0 to 127. |
354 | -1 for automatic value. | |
355 | See also the 'double_buffer' module parameter. | |
1da177e4 LT |
356 | Default: -1 for every device. |
357 | ------------------------------------------------------------------------------- | |
358 | Name: backlight | |
359 | Type: bool array (min = 0, max = 32) | |
360 | Syntax: <0|1[,...]> | |
361 | Description: Objects are lit from behind: | |
6e204090 | 362 | 0 = no, 1 = yes |
1da177e4 LT |
363 | Default: 0 for every device. |
364 | ------------------------------------------------------------------------------- | |
365 | Name: mirror | |
366 | Type: bool array (min = 0, max = 32) | |
367 | Syntax: <0|1[,...]> | |
368 | Description: Reverse image horizontally: | |
6e204090 | 369 | 0 = no, 1 = yes |
1da177e4 LT |
370 | Default: 0 for every device. |
371 | ------------------------------------------------------------------------------- | |
372 | Name: monochrome | |
373 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 374 | Syntax: <0|1[,...]> |
1da177e4 | 375 | Description: The image sensor is monochrome: |
6e204090 | 376 | 0 = no, 1 = yes |
1da177e4 LT |
377 | Default: 0 for every device. |
378 | ------------------------------------------------------------------------------- | |
379 | Name: brightness | |
380 | Type: long array (min = 0, max = 32) | |
381 | Syntax: <n[,...]> | |
382 | Description: Set picture brightness (0-65535). | |
6e204090 | 383 | This parameter has no effect if 'autobright' is enabled. |
1da177e4 LT |
384 | Default: 31000 for every device. |
385 | ------------------------------------------------------------------------------- | |
386 | Name: hue | |
387 | Type: long array (min = 0, max = 32) | |
388 | Syntax: <n[,...]> | |
389 | Description: Set picture hue (0-65535). | |
390 | Default: 32768 for every device. | |
391 | ------------------------------------------------------------------------------- | |
392 | Name: colour | |
393 | Type: long array (min = 0, max = 32) | |
394 | Syntax: <n[,...]> | |
395 | Description: Set picture saturation (0-65535). | |
396 | Default: 32768 for every device. | |
397 | ------------------------------------------------------------------------------- | |
398 | Name: contrast | |
399 | Type: long array (min = 0, max = 32) | |
1864cfb1 | 400 | Syntax: <n[,...]> |
1da177e4 LT |
401 | Description: Set picture contrast (0-65535). |
402 | Default: 50000 for every device. | |
403 | ------------------------------------------------------------------------------- | |
404 | Name: whiteness | |
405 | Type: long array (min = 0, max = 32) | |
1864cfb1 | 406 | Syntax: <n[,...]> |
1da177e4 LT |
407 | Description: Set picture whiteness (0-65535). |
408 | Default: 32768 for every device. | |
409 | ------------------------------------------------------------------------------- | |
410 | Name: debug | |
411 | Type: int | |
1864cfb1 | 412 | Syntax: <n> |
1da177e4 | 413 | Description: Debugging information level, from 0 to 6: |
6e204090 MK |
414 | 0 = none (use carefully) |
415 | 1 = critical errors | |
416 | 2 = significant informations | |
417 | 3 = configuration or general messages | |
418 | 4 = warnings | |
419 | 5 = called functions | |
420 | 6 = function internals | |
421 | Level 5 and 6 are useful for testing only, when only one | |
422 | device is used. | |
1da177e4 LT |
423 | Default: 2 |
424 | ------------------------------------------------------------------------------- | |
425 | Name: specific_debug | |
426 | Type: bool | |
427 | Syntax: <0|1> | |
428 | Description: Enable or disable specific debugging messages: | |
6e204090 MK |
429 | 0 = print messages concerning every level <= 'debug' level. |
430 | 1 = print messages concerning the level indicated by 'debug'. | |
1da177e4 LT |
431 | Default: 0 |
432 | ------------------------------------------------------------------------------- | |
433 | ||
434 | ||
435 | 9. Contact information | |
436 | ====================== | |
437 | I may be contacted by e-mail at <luca.risolia@studio.unibo.it>. | |
438 | ||
439 | I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'. | |
440 | My public 1024-bit key should be available at your keyserver; the fingerprint | |
441 | is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. | |
442 | ||
443 | ||
444 | 10. Credits | |
445 | ========== | |
446 | The development would not have proceed much further without having looked at | |
447 | the source code of other drivers and without the help of several persons; in | |
448 | particular: | |
449 | ||
450 | - the I2C interface to kernel and high-level image sensor control routines have | |
451 | been taken from the OV511 driver by Mark McClelland; | |
452 | ||
453 | - memory management code has been copied from the bttv driver by Ralph Metzler, | |
454 | Marcus Metzler and Gerd Knorr; | |
455 | ||
456 | - the low-level I2C read function has been written by Frederic Jouault; | |
457 | ||
458 | - the low-level I2C fast write function has been written by Piotr Czerczak. |