Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/roland...
[linux-2.6] / Documentation / video4linux / 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 parameters
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.
61
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.
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
118 actually using any external "ovcamchip" module, given that the W996[87]CF
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.
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.
195 Default:         1
196 -------------------------------------------------------------------------------
197 Name:           simcams
198 Type:           int
199 Syntax:         <n>
200 Description:    Number of cameras allowed to stream simultaneously.
201                 n may vary from 0 to 32.
202 Default:        32
203 -------------------------------------------------------------------------------
204 Name:           video_nr
205 Type:           int array (min = 0, max = 32)
206 Syntax:         <-1|n[,...]>
207 Description:    Specify V4L minor mode number.
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.
215 Default:        -1
216 -------------------------------------------------------------------------------
217 Name:           packet_size
218 Type:           int array (min = 0, max = 32)
219 Syntax:         <n[,...]>
220 Description:    Specify the maximum data payload size in bytes for alternate
221                 settings, for each device. n is scaled between 63 and 1023.
222 Default:        1023
223 -------------------------------------------------------------------------------
224 Name:           max_buffers
225 Type:           int array (min = 0, max = 32)
226 Syntax:         <n[,...]>
227 Description:    For advanced users.
228                 Specify the maximum number of video frame buffers to allocate
229                 for each device, from 2 to 32.
230 Default:        2
231 -------------------------------------------------------------------------------
232 Name:           double_buffer
233 Type:           bool array (min = 0, max = 32)
234 Syntax:         <0|1[,...]>
235 Description:    Hardware double buffering: 0 disabled, 1 enabled.
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.
239 Default:        1 for every device.
240 -------------------------------------------------------------------------------
241 Name:           clamping
242 Type:           bool array (min = 0, max = 32)
243 Syntax:         <0|1[,...]>
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)
249 Syntax:         <0|1|2[,...]>
250 Description:    Video filter type.
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.
254 Default:        0 for every device.
255 -------------------------------------------------------------------------------
256 Name:           largeview
257 Type:           bool array (min = 0, max = 32)
258 Syntax:         <0|1[,...]>
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)
264 Syntax:         <0|1[,...]>
265 Description:    Software scaling (for non-compressed video only):
266                 0 disabled, 1 enabled.
267                 Disable it if you have a slow CPU or you don't have enough
268                 memory.
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:
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.
284 Default:        2 for every device.
285 Note:           If 'w9968cf-vpp' is not present, forcing decompression is not
286                 allowed; in this case this parameter is set to 2.
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.
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'.
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:
313                 1 = use RGB component ordering.
314                 0 = use BGR component ordering.
315                 This parameter has effect when using RGBX palettes only.
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:
322                 0 = no, 1 = yes
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:
329                 0 = no, 1 = yes
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:
336                 50 for European and Asian lighting, 60 for American lighting.
337 Default:        50 for every device.
338 -------------------------------------------------------------------------------
339 Name:           bandingfilter
340 Type:           bool array (min = 0, max = 32)
341 Syntax:         <0|1[,...]>
342 Description:    Banding filter to reduce effects of fluorescent
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.
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):
353                 n may vary from 0 to 127.
354                 -1 for automatic value.
355                 See also the 'double_buffer' module parameter.
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:
362                 0 = no, 1 = yes
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:
369                 0 = no, 1 = yes
370 Default:        0 for every device.
371 -------------------------------------------------------------------------------
372 Name:           monochrome
373 Type:           bool array (min = 0, max = 32)
374 Syntax:         <0|1[,...]>
375 Description:    The image sensor is monochrome:
376                 0 = no, 1 = yes
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).
383                 This parameter has no effect if 'autobright' is enabled.
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)
400 Syntax:         <n[,...]>
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)
406 Syntax:         <n[,...]>
407 Description:    Set picture whiteness (0-65535).
408 Default:        32768 for every device.
409 -------------------------------------------------------------------------------
410 Name:           debug
411 Type:           int
412 Syntax:         <n>
413 Description:    Debugging information level, from 0 to 6:
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.
423 Default:        2
424 -------------------------------------------------------------------------------
425 Name:           specific_debug
426 Type:           bool
427 Syntax:         <0|1>
428 Description:    Enable or disable specific debugging messages:
429                 0 = print messages concerning every level <= 'debug' level.
430                 1 = print messages concerning the level indicated by 'debug'.
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.