blob: 0d53ce774b01c75b26d5fb2aff1ce1e9098071de [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
Michael Krufky6e204092006-05-23 17:41:31 -03002 W996[87]CF JPEG USB Dual Mode Camera Chip
3 Driver for Linux 2.6 (basic version)
4 =========================================
Linus Torvalds1da177e2005-04-16 15:20:36 -07005
Michael Krufky6e204092006-05-23 17:41:31 -03006 - Documentation -
Linus Torvalds1da177e2005-04-16 15:20:36 -07007
8
9Index
10=====
111. Copyright
122. Disclaimer
133. License
144. Overview
155. Supported devices
166. Module dependencies
177. Module loading
188. Module paramaters
199. Contact information
2010. Credits
21
22
231. Copyright
24============
25Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
26
27
282. Disclaimer
29=============
30Winbond is a trademark of Winbond Electronics Corporation.
31This software is not sponsored or developed by Winbond.
32
33
343. License
35==========
36This program is free software; you can redistribute it and/or modify
37it under the terms of the GNU General Public License as published by
38the Free Software Foundation; either version 2 of the License, or
39(at your option) any later version.
40
41This program is distributed in the hope that it will be useful,
42but WITHOUT ANY WARRANTY; without even the implied warranty of
43MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
44GNU General Public License for more details.
45
46You should have received a copy of the GNU General Public License
47along with this program; if not, write to the Free Software
48Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
49
50
514. Overview
52===========
53This driver supports the video streaming capabilities of the devices mounting
54Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
55based cameras should be supported as well.
56
57The driver is divided into two modules: the basic one, "w9968cf", is needed for
58the supported devices to work; the second one, "w9968cf-vpp", is an optional
59module, which provides some useful video post-processing functions like video
Adrian Bunk7f2c01a2006-01-09 00:43:39 +010060decoding, up-scaling and colour conversions.
Linus Torvalds1da177e2005-04-16 15:20:36 -070061
Adrian Bunk7f2c01a2006-01-09 00:43:39 +010062Note that the official kernels do neither include nor support the second
63module for performance purposes. Therefore, it is always recommended to
64download and install the latest and complete release of the driver,
65replacing the existing one, if present.
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
67The latest and full-featured version of the W996[87]CF driver can be found at:
68http://www.linux-projects.org. Please refer to the documentation included in
69that package, if you are going to use it.
70
71Up to 32 cameras can be handled at the same time. They can be connected and
72disconnected from the host many times without turning off the computer, if
73your system supports the hotplug facility.
74
75To change the default settings for each camera, many parameters can be passed
76through command line when the module is loaded into memory.
77
78The driver relies on the Video4Linux, USB and I2C core modules. It has been
79designed to run properly on SMP systems as well. An additional module,
80"ovcamchip", is mandatory; it provides support for some OmniVision image
81sensors connected to the W996[87]CF chips; if found in the system, the module
82will be automatically loaded by default (provided that the kernel has been
83compiled with the automatic module loading option).
84
85
865. Supported devices
87====================
88At 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
100If you know any other W996[87]CF or OV681 based cameras, please contact me.
101
102The list above does not imply that all those devices work with this driver: up
103until now only webcams that have an image sensor supported by the "ovcamchip"
104module work. Kernel messages will always tell you whether this is case.
105
106Possible external microcontrollers of those webcams are not supported: this
107means that still images cannot be downloaded from the device memory.
108
109Furthermore, 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
111additional testing and full support, would be much appreciated.
112
113
1146. Module dependencies
115======================
116For it to work properly, the driver needs kernel support for Video4Linux, USB
117and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
Michael Krufky1864cfb2006-04-02 03:14:11 -0300118actually using any external "ovcamchip" module, given that the W996[87]CF
Linus Torvalds1da177e2005-04-16 15:20:36 -0700119driver depends on the version of the module present in the official kernels.
120
121The following options of the kernel configuration file must be enabled and
122corresponding modules must be compiled:
123
124 # Multimedia devices
125 #
126 CONFIG_VIDEO_DEV=m
127
128 # I2C support
129 #
130 CONFIG_I2C=m
131
132The 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
142In addition, depending on the hardware being used, only one of the modules
143below 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
151And finally:
152
153 # USB Multimedia devices
154 #
155 CONFIG_USB_W9968CF=m
156
157
1587. Module loading
159=================
160To use the driver, it is necessary to load the "w9968cf" module into memory
161after every other module required.
162
163Loading 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
170At this point the pertinent devices should be recognized: "dmesg" can be used
171to analyze kernel messages:
172
173 [user@localhost home]$ dmesg
174
175There are a lot of parameters the module can use to change the default
176settings for each device. To list every possible parameter with a brief
177explanation 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
1838. Module parameters
184====================
185Module parameters are listed below:
186-------------------------------------------------------------------------------
187Name: ovmod_load
188Type: bool
189Syntax: <0|1>
190Description: Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled.
Michael Krufky6e204092006-05-23 17:41:31 -0300191 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700195Default: 1
196Note: The kernel must be compiled with the CONFIG_KMOD option
Michael Krufky6e204092006-05-23 17:41:31 -0300197 enabled for the 'ovcamchip' module to be loaded and for
198 this parameter to be present.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700199-------------------------------------------------------------------------------
Michael Krufky1864cfb2006-04-02 03:14:11 -0300200Name: simcams
201Type: int
202Syntax: <n>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700203Description: Number of cameras allowed to stream simultaneously.
Michael Krufky6e204092006-05-23 17:41:31 -0300204 n may vary from 0 to 32.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700205Default: 32
206-------------------------------------------------------------------------------
207Name: video_nr
208Type: int array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300209Syntax: <-1|n[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700210Description: Specify V4L minor mode number.
Michael Krufky6e204092006-05-23 17:41:31 -0300211 -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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700218Default: -1
219-------------------------------------------------------------------------------
220Name: packet_size
221Type: int array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300222Syntax: <n[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700223Description: Specify the maximum data payload size in bytes for alternate
Michael Krufky6e204092006-05-23 17:41:31 -0300224 settings, for each device. n is scaled between 63 and 1023.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700225Default: 1023
226-------------------------------------------------------------------------------
227Name: max_buffers
228Type: int array (min = 0, max = 32)
229Syntax: <n[,...]>
230Description: For advanced users.
Michael Krufky6e204092006-05-23 17:41:31 -0300231 Specify the maximum number of video frame buffers to allocate
232 for each device, from 2 to 32.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700233Default: 2
234-------------------------------------------------------------------------------
235Name: double_buffer
236Type: bool array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300237Syntax: <0|1[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700238Description: Hardware double buffering: 0 disabled, 1 enabled.
Michael Krufky6e204092006-05-23 17:41:31 -0300239 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700242Default: 1 for every device.
243-------------------------------------------------------------------------------
244Name: clamping
245Type: bool array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300246Syntax: <0|1[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700247Description: Video data clamping: 0 disabled, 1 enabled.
248Default: 0 for every device.
249-------------------------------------------------------------------------------
250Name: filter_type
251Type: int array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300252Syntax: <0|1|2[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700253Description: Video filter type.
Michael Krufky6e204092006-05-23 17:41:31 -0300254 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700257Default: 0 for every device.
258-------------------------------------------------------------------------------
259Name: largeview
260Type: bool array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300261Syntax: <0|1[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700262Description: Large view: 0 disabled, 1 enabled.
263Default: 1 for every device.
264-------------------------------------------------------------------------------
265Name: upscaling
266Type: bool array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300267Syntax: <0|1[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700268Description: Software scaling (for non-compressed video only):
Michael Krufky6e204092006-05-23 17:41:31 -0300269 0 disabled, 1 enabled.
270 Disable it if you have a slow CPU or you don't have enough
271 memory.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700272Default: 0 for every device.
273Note: If 'w9968cf-vpp' is not present, this parameter is set to 0.
274-------------------------------------------------------------------------------
275Name: decompression
276Type: int array (min = 0, max = 32)
277Syntax: <0|1|2[,...]>
278Description: Software video decompression:
Michael Krufky6e204092006-05-23 17:41:31 -0300279 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700287Default: 2 for every device.
288Note: If 'w9968cf-vpp' is not present, forcing decompression is not
Michael Krufky6e204092006-05-23 17:41:31 -0300289 allowed; in this case this parameter is set to 2.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700290-------------------------------------------------------------------------------
291Name: force_palette
292Type: int array (min = 0, max = 32)
293Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
294Description: Force picture palette.
Michael Krufky6e204092006-05-23 17:41:31 -0300295 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'.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700309Default: 0 for every device. Initial palette is 9 (UYVY).
310Note: If 'w9968cf-vpp' is not present, this parameter is set to 9.
311-------------------------------------------------------------------------------
312Name: force_rgb
313Type: bool array (min = 0, max = 32)
314Syntax: <0|1[,...]>
315Description: Read RGB video data instead of BGR:
Michael Krufky6e204092006-05-23 17:41:31 -0300316 1 = use RGB component ordering.
317 0 = use BGR component ordering.
318 This parameter has effect when using RGBX palettes only.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700319Default: 0 for every device.
320-------------------------------------------------------------------------------
321Name: autobright
322Type: bool array (min = 0, max = 32)
323Syntax: <0|1[,...]>
324Description: Image sensor automatically changes brightness:
Michael Krufky6e204092006-05-23 17:41:31 -0300325 0 = no, 1 = yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700326Default: 0 for every device.
327-------------------------------------------------------------------------------
328Name: autoexp
329Type: bool array (min = 0, max = 32)
330Syntax: <0|1[,...]>
331Description: Image sensor automatically changes exposure:
Michael Krufky6e204092006-05-23 17:41:31 -0300332 0 = no, 1 = yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700333Default: 1 for every device.
334-------------------------------------------------------------------------------
335Name: lightfreq
336Type: int array (min = 0, max = 32)
337Syntax: <50|60[,...]>
338Description: Light frequency in Hz:
Michael Krufky6e204092006-05-23 17:41:31 -0300339 50 for European and Asian lighting, 60 for American lighting.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700340Default: 50 for every device.
341-------------------------------------------------------------------------------
342Name: bandingfilter
343Type: bool array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300344Syntax: <0|1[,...]>
345Description: Banding filter to reduce effects of fluorescent
Michael Krufky6e204092006-05-23 17:41:31 -0300346 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700350Default: 0 for every device.
351-------------------------------------------------------------------------------
352Name: clockdiv
353Type: int array (min = 0, max = 32)
354Syntax: <-1|n[,...]>
355Description: Force pixel clock divisor to a specific value (for experts):
Michael Krufky6e204092006-05-23 17:41:31 -0300356 n may vary from 0 to 127.
357 -1 for automatic value.
358 See also the 'double_buffer' module parameter.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700359Default: -1 for every device.
360-------------------------------------------------------------------------------
361Name: backlight
362Type: bool array (min = 0, max = 32)
363Syntax: <0|1[,...]>
364Description: Objects are lit from behind:
Michael Krufky6e204092006-05-23 17:41:31 -0300365 0 = no, 1 = yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700366Default: 0 for every device.
367-------------------------------------------------------------------------------
368Name: mirror
369Type: bool array (min = 0, max = 32)
370Syntax: <0|1[,...]>
371Description: Reverse image horizontally:
Michael Krufky6e204092006-05-23 17:41:31 -0300372 0 = no, 1 = yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700373Default: 0 for every device.
374-------------------------------------------------------------------------------
375Name: monochrome
376Type: bool array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300377Syntax: <0|1[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700378Description: The image sensor is monochrome:
Michael Krufky6e204092006-05-23 17:41:31 -0300379 0 = no, 1 = yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700380Default: 0 for every device.
381-------------------------------------------------------------------------------
382Name: brightness
383Type: long array (min = 0, max = 32)
384Syntax: <n[,...]>
385Description: Set picture brightness (0-65535).
Michael Krufky6e204092006-05-23 17:41:31 -0300386 This parameter has no effect if 'autobright' is enabled.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700387Default: 31000 for every device.
388-------------------------------------------------------------------------------
389Name: hue
390Type: long array (min = 0, max = 32)
391Syntax: <n[,...]>
392Description: Set picture hue (0-65535).
393Default: 32768 for every device.
394-------------------------------------------------------------------------------
395Name: colour
396Type: long array (min = 0, max = 32)
397Syntax: <n[,...]>
398Description: Set picture saturation (0-65535).
399Default: 32768 for every device.
400-------------------------------------------------------------------------------
401Name: contrast
402Type: long array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300403Syntax: <n[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700404Description: Set picture contrast (0-65535).
405Default: 50000 for every device.
406-------------------------------------------------------------------------------
407Name: whiteness
408Type: long array (min = 0, max = 32)
Michael Krufky1864cfb2006-04-02 03:14:11 -0300409Syntax: <n[,...]>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700410Description: Set picture whiteness (0-65535).
411Default: 32768 for every device.
412-------------------------------------------------------------------------------
413Name: debug
414Type: int
Michael Krufky1864cfb2006-04-02 03:14:11 -0300415Syntax: <n>
Linus Torvalds1da177e2005-04-16 15:20:36 -0700416Description: Debugging information level, from 0 to 6:
Michael Krufky6e204092006-05-23 17:41:31 -0300417 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.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700426Default: 2
427-------------------------------------------------------------------------------
428Name: specific_debug
429Type: bool
430Syntax: <0|1>
431Description: Enable or disable specific debugging messages:
Michael Krufky6e204092006-05-23 17:41:31 -0300432 0 = print messages concerning every level <= 'debug' level.
433 1 = print messages concerning the level indicated by 'debug'.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700434Default: 0
435-------------------------------------------------------------------------------
436
437
4389. Contact information
439======================
440I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
441
442I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
443My public 1024-bit key should be available at your keyserver; the fingerprint
444is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
445
446
44710. Credits
448==========
449The development would not have proceed much further without having looked at
450the source code of other drivers and without the help of several persons; in
451particular:
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.