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