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 LT |
195 | Default: 1 |
196 | Note: The kernel must be compiled with the CONFIG_KMOD option | |
6e204090 MK |
197 | enabled for the 'ovcamchip' module to be loaded and for |
198 | this parameter to be present. | |
1da177e4 | 199 | ------------------------------------------------------------------------------- |
1864cfb1 MK |
200 | Name: simcams |
201 | Type: int | |
202 | Syntax: <n> | |
1da177e4 | 203 | Description: Number of cameras allowed to stream simultaneously. |
6e204090 | 204 | n may vary from 0 to 32. |
1da177e4 LT |
205 | Default: 32 |
206 | ------------------------------------------------------------------------------- | |
207 | Name: video_nr | |
208 | Type: int array (min = 0, max = 32) | |
1864cfb1 | 209 | Syntax: <-1|n[,...]> |
1da177e4 | 210 | Description: Specify V4L minor mode number. |
6e204090 MK |
211 | -1 = use next available |
212 | n = use minor number n | |
213 | You can specify up to 32 cameras this way. | |
214 | For example: | |
215 | video_nr=-1,2,-1 would assign minor number 2 to the second | |
216 | recognized camera and use auto for the first one and for every | |
217 | other camera. | |
1da177e4 LT |
218 | Default: -1 |
219 | ------------------------------------------------------------------------------- | |
220 | Name: packet_size | |
221 | Type: int array (min = 0, max = 32) | |
1864cfb1 | 222 | Syntax: <n[,...]> |
1da177e4 | 223 | Description: Specify the maximum data payload size in bytes for alternate |
6e204090 | 224 | settings, for each device. n is scaled between 63 and 1023. |
1da177e4 LT |
225 | Default: 1023 |
226 | ------------------------------------------------------------------------------- | |
227 | Name: max_buffers | |
228 | Type: int array (min = 0, max = 32) | |
229 | Syntax: <n[,...]> | |
230 | Description: For advanced users. | |
6e204090 MK |
231 | Specify the maximum number of video frame buffers to allocate |
232 | for each device, from 2 to 32. | |
1da177e4 LT |
233 | Default: 2 |
234 | ------------------------------------------------------------------------------- | |
235 | Name: double_buffer | |
236 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 237 | Syntax: <0|1[,...]> |
1da177e4 | 238 | Description: Hardware double buffering: 0 disabled, 1 enabled. |
6e204090 MK |
239 | It should be enabled if you want smooth video output: if you |
240 | obtain out of sync. video, disable it, or try to | |
241 | decrease the 'clockdiv' module parameter value. | |
1da177e4 LT |
242 | Default: 1 for every device. |
243 | ------------------------------------------------------------------------------- | |
244 | Name: clamping | |
245 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 246 | Syntax: <0|1[,...]> |
1da177e4 LT |
247 | Description: Video data clamping: 0 disabled, 1 enabled. |
248 | Default: 0 for every device. | |
249 | ------------------------------------------------------------------------------- | |
250 | Name: filter_type | |
251 | Type: int array (min = 0, max = 32) | |
1864cfb1 | 252 | Syntax: <0|1|2[,...]> |
1da177e4 | 253 | Description: Video filter type. |
6e204090 MK |
254 | 0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter. |
255 | The filter is used to reduce noise and aliasing artifacts | |
256 | produced by the CCD or CMOS image sensor. | |
1da177e4 LT |
257 | Default: 0 for every device. |
258 | ------------------------------------------------------------------------------- | |
259 | Name: largeview | |
260 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 261 | Syntax: <0|1[,...]> |
1da177e4 LT |
262 | Description: Large view: 0 disabled, 1 enabled. |
263 | Default: 1 for every device. | |
264 | ------------------------------------------------------------------------------- | |
265 | Name: upscaling | |
266 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 267 | Syntax: <0|1[,...]> |
1da177e4 | 268 | Description: Software scaling (for non-compressed video only): |
6e204090 MK |
269 | 0 disabled, 1 enabled. |
270 | Disable it if you have a slow CPU or you don't have enough | |
271 | memory. | |
1da177e4 LT |
272 | Default: 0 for every device. |
273 | Note: If 'w9968cf-vpp' is not present, this parameter is set to 0. | |
274 | ------------------------------------------------------------------------------- | |
275 | Name: decompression | |
276 | Type: int array (min = 0, max = 32) | |
277 | Syntax: <0|1|2[,...]> | |
278 | Description: Software video decompression: | |
6e204090 MK |
279 | 0 = disables decompression |
280 | (doesn't allow formats needing decompression). | |
281 | 1 = forces decompression | |
282 | (allows formats needing decompression only). | |
283 | 2 = allows any permitted formats. | |
284 | Formats supporting (de)compressed video are YUV422P and | |
285 | YUV420P/YUV420 in any resolutions where width and height are | |
286 | multiples of 16. | |
1da177e4 LT |
287 | Default: 2 for every device. |
288 | Note: If 'w9968cf-vpp' is not present, forcing decompression is not | |
6e204090 | 289 | allowed; in this case this parameter is set to 2. |
1da177e4 LT |
290 | ------------------------------------------------------------------------------- |
291 | Name: force_palette | |
292 | Type: int array (min = 0, max = 32) | |
293 | Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]> | |
294 | Description: Force picture palette. | |
6e204090 MK |
295 | In order: |
296 | 0 = Off - allows any of the following formats: | |
297 | 9 = UYVY 16 bpp - Original video, compression disabled | |
298 | 10 = YUV420 12 bpp - Original video, compression enabled | |
299 | 13 = YUV422P 16 bpp - Original video, compression enabled | |
300 | 15 = YUV420P 12 bpp - Original video, compression enabled | |
301 | 8 = YUVY 16 bpp - Software conversion from UYVY | |
302 | 7 = YUV422 16 bpp - Software conversion from UYVY | |
303 | 1 = GREY 8 bpp - Software conversion from UYVY | |
304 | 6 = RGB555 16 bpp - Software conversion from UYVY | |
305 | 3 = RGB565 16 bpp - Software conversion from UYVY | |
306 | 4 = RGB24 24 bpp - Software conversion from UYVY | |
307 | 5 = RGB32 32 bpp - Software conversion from UYVY | |
308 | When not 0, this parameter will override 'decompression'. | |
1da177e4 LT |
309 | Default: 0 for every device. Initial palette is 9 (UYVY). |
310 | Note: If 'w9968cf-vpp' is not present, this parameter is set to 9. | |
311 | ------------------------------------------------------------------------------- | |
312 | Name: force_rgb | |
313 | Type: bool array (min = 0, max = 32) | |
314 | Syntax: <0|1[,...]> | |
315 | Description: Read RGB video data instead of BGR: | |
6e204090 MK |
316 | 1 = use RGB component ordering. |
317 | 0 = use BGR component ordering. | |
318 | This parameter has effect when using RGBX palettes only. | |
1da177e4 LT |
319 | Default: 0 for every device. |
320 | ------------------------------------------------------------------------------- | |
321 | Name: autobright | |
322 | Type: bool array (min = 0, max = 32) | |
323 | Syntax: <0|1[,...]> | |
324 | Description: Image sensor automatically changes brightness: | |
6e204090 | 325 | 0 = no, 1 = yes |
1da177e4 LT |
326 | Default: 0 for every device. |
327 | ------------------------------------------------------------------------------- | |
328 | Name: autoexp | |
329 | Type: bool array (min = 0, max = 32) | |
330 | Syntax: <0|1[,...]> | |
331 | Description: Image sensor automatically changes exposure: | |
6e204090 | 332 | 0 = no, 1 = yes |
1da177e4 LT |
333 | Default: 1 for every device. |
334 | ------------------------------------------------------------------------------- | |
335 | Name: lightfreq | |
336 | Type: int array (min = 0, max = 32) | |
337 | Syntax: <50|60[,...]> | |
338 | Description: Light frequency in Hz: | |
6e204090 | 339 | 50 for European and Asian lighting, 60 for American lighting. |
1da177e4 LT |
340 | Default: 50 for every device. |
341 | ------------------------------------------------------------------------------- | |
342 | Name: bandingfilter | |
343 | Type: bool array (min = 0, max = 32) | |
1864cfb1 MK |
344 | Syntax: <0|1[,...]> |
345 | Description: Banding filter to reduce effects of fluorescent | |
6e204090 MK |
346 | lighting: |
347 | 0 disabled, 1 enabled. | |
348 | This filter tries to reduce the pattern of horizontal | |
349 | light/dark bands caused by some (usually fluorescent) lighting. | |
1da177e4 LT |
350 | Default: 0 for every device. |
351 | ------------------------------------------------------------------------------- | |
352 | Name: clockdiv | |
353 | Type: int array (min = 0, max = 32) | |
354 | Syntax: <-1|n[,...]> | |
355 | Description: Force pixel clock divisor to a specific value (for experts): | |
6e204090 MK |
356 | n may vary from 0 to 127. |
357 | -1 for automatic value. | |
358 | See also the 'double_buffer' module parameter. | |
1da177e4 LT |
359 | Default: -1 for every device. |
360 | ------------------------------------------------------------------------------- | |
361 | Name: backlight | |
362 | Type: bool array (min = 0, max = 32) | |
363 | Syntax: <0|1[,...]> | |
364 | Description: Objects are lit from behind: | |
6e204090 | 365 | 0 = no, 1 = yes |
1da177e4 LT |
366 | Default: 0 for every device. |
367 | ------------------------------------------------------------------------------- | |
368 | Name: mirror | |
369 | Type: bool array (min = 0, max = 32) | |
370 | Syntax: <0|1[,...]> | |
371 | Description: Reverse image horizontally: | |
6e204090 | 372 | 0 = no, 1 = yes |
1da177e4 LT |
373 | Default: 0 for every device. |
374 | ------------------------------------------------------------------------------- | |
375 | Name: monochrome | |
376 | Type: bool array (min = 0, max = 32) | |
1864cfb1 | 377 | Syntax: <0|1[,...]> |
1da177e4 | 378 | Description: The image sensor is monochrome: |
6e204090 | 379 | 0 = no, 1 = yes |
1da177e4 LT |
380 | Default: 0 for every device. |
381 | ------------------------------------------------------------------------------- | |
382 | Name: brightness | |
383 | Type: long array (min = 0, max = 32) | |
384 | Syntax: <n[,...]> | |
385 | Description: Set picture brightness (0-65535). | |
6e204090 | 386 | This parameter has no effect if 'autobright' is enabled. |
1da177e4 LT |
387 | Default: 31000 for every device. |
388 | ------------------------------------------------------------------------------- | |
389 | Name: hue | |
390 | Type: long array (min = 0, max = 32) | |
391 | Syntax: <n[,...]> | |
392 | Description: Set picture hue (0-65535). | |
393 | Default: 32768 for every device. | |
394 | ------------------------------------------------------------------------------- | |
395 | Name: colour | |
396 | Type: long array (min = 0, max = 32) | |
397 | Syntax: <n[,...]> | |
398 | Description: Set picture saturation (0-65535). | |
399 | Default: 32768 for every device. | |
400 | ------------------------------------------------------------------------------- | |
401 | Name: contrast | |
402 | Type: long array (min = 0, max = 32) | |
1864cfb1 | 403 | Syntax: <n[,...]> |
1da177e4 LT |
404 | Description: Set picture contrast (0-65535). |
405 | Default: 50000 for every device. | |
406 | ------------------------------------------------------------------------------- | |
407 | Name: whiteness | |
408 | Type: long array (min = 0, max = 32) | |
1864cfb1 | 409 | Syntax: <n[,...]> |
1da177e4 LT |
410 | Description: Set picture whiteness (0-65535). |
411 | Default: 32768 for every device. | |
412 | ------------------------------------------------------------------------------- | |
413 | Name: debug | |
414 | Type: int | |
1864cfb1 | 415 | Syntax: <n> |
1da177e4 | 416 | Description: Debugging information level, from 0 to 6: |
6e204090 MK |
417 | 0 = none (use carefully) |
418 | 1 = critical errors | |
419 | 2 = significant informations | |
420 | 3 = configuration or general messages | |
421 | 4 = warnings | |
422 | 5 = called functions | |
423 | 6 = function internals | |
424 | Level 5 and 6 are useful for testing only, when only one | |
425 | device is used. | |
1da177e4 LT |
426 | Default: 2 |
427 | ------------------------------------------------------------------------------- | |
428 | Name: specific_debug | |
429 | Type: bool | |
430 | Syntax: <0|1> | |
431 | Description: Enable or disable specific debugging messages: | |
6e204090 MK |
432 | 0 = print messages concerning every level <= 'debug' level. |
433 | 1 = print messages concerning the level indicated by 'debug'. | |
1da177e4 LT |
434 | Default: 0 |
435 | ------------------------------------------------------------------------------- | |
436 | ||
437 | ||
438 | 9. Contact information | |
439 | ====================== | |
440 | I may be contacted by e-mail at <luca.risolia@studio.unibo.it>. | |
441 | ||
442 | I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'. | |
443 | My public 1024-bit key should be available at your keyserver; the fingerprint | |
444 | is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. | |
445 | ||
446 | ||
447 | 10. Credits | |
448 | ========== | |
449 | The development would not have proceed much further without having looked at | |
450 | the source code of other drivers and without the help of several persons; in | |
451 | particular: | |
452 | ||
453 | - the I2C interface to kernel and high-level image sensor control routines have | |
454 | been taken from the OV511 driver by Mark McClelland; | |
455 | ||
456 | - memory management code has been copied from the bttv driver by Ralph Metzler, | |
457 | Marcus Metzler and Gerd Knorr; | |
458 | ||
459 | - the low-level I2C read function has been written by Frederic Jouault; | |
460 | ||
461 | - the low-level I2C fast write function has been written by Piotr Czerczak. |