aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/usb/w9968cf.txt
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
committerLinus Torvalds <torvalds@ppc970.osdl.org>2005-04-16 18:20:36 -0400
commit1da177e4c3f41524e886b7f1b8a0c1fc7321cac2 (patch)
tree0bba044c4ce775e45a88a51686b5d9f90697ea9d /Documentation/usb/w9968cf.txt
Linux-2.6.12-rc2v2.6.12-rc2
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
Diffstat (limited to 'Documentation/usb/w9968cf.txt')
-rw-r--r--Documentation/usb/w9968cf.txt481
1 files changed, 481 insertions, 0 deletions
diff --git a/Documentation/usb/w9968cf.txt b/Documentation/usb/w9968cf.txt
new file mode 100644
index 000000000000..18a47738d56c
--- /dev/null
+++ b/Documentation/usb/w9968cf.txt
@@ -0,0 +1,481 @@
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
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
60decoding, up-scaling and colour conversions. Once the driver is installed,
61every time an application tries to open a recognized device, "w9968cf" checks
62the presence of the "w9968cf-vpp" module and loads it automatically by default.
63
64Please keep in mind that official kernels do not include the second module for
65performance purposes. However it is always recommended to download and install
66the latest and complete release of the driver, replacing the existing one, if
67present: it will be still even possible not to load the "w9968cf-vpp" module at
68all, if you ever want to. Another important missing feature of the version in
69the official Linux 2.4 kernels is the writeable /proc filesystem interface.
70
71The latest and full-featured version of the W996[87]CF driver can be found at:
72http://www.linux-projects.org. Please refer to the documentation included in
73that package, if you are going to use it.
74
75Up to 32 cameras can be handled at the same time. They can be connected and
76disconnected from the host many times without turning off the computer, if
77your system supports the hotplug facility.
78
79To change the default settings for each camera, many parameters can be passed
80through command line when the module is loaded into memory.
81
82The driver relies on the Video4Linux, USB and I2C core modules. It has been
83designed to run properly on SMP systems as well. An additional module,
84"ovcamchip", is mandatory; it provides support for some OmniVision image
85sensors connected to the W996[87]CF chips; if found in the system, the module
86will be automatically loaded by default (provided that the kernel has been
87compiled with the automatic module loading option).
88
89
905. Supported devices
91====================
92At 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
104If you know any other W996[87]CF or OV681 based cameras, please contact me.
105
106The list above does not imply that all those devices work with this driver: up
107until now only webcams that have an image sensor supported by the "ovcamchip"
108module work. Kernel messages will always tell you whether this is case.
109
110Possible external microcontrollers of those webcams are not supported: this
111means that still images cannot be downloaded from the device memory.
112
113Furthermore, 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
115additional testing and full support, would be much appreciated.
116
117
1186. Module dependencies
119======================
120For it to work properly, the driver needs kernel support for Video4Linux, USB
121and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
122actually using any external "ovcamchip" module, given that the W996[87]CF
123driver depends on the version of the module present in the official kernels.
124
125The following options of the kernel configuration file must be enabled and
126corresponding modules must be compiled:
127
128 # Multimedia devices
129 #
130 CONFIG_VIDEO_DEV=m
131
132 # I2C support
133 #
134 CONFIG_I2C=m
135
136The 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
146In addition, depending on the hardware being used, only one of the modules
147below 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
155And finally:
156
157 # USB Multimedia devices
158 #
159 CONFIG_USB_W9968CF=m
160
161
1627. Module loading
163=================
164To use the driver, it is necessary to load the "w9968cf" module into memory
165after every other module required.
166
167Loading 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
174At this point the pertinent devices should be recognized: "dmesg" can be used
175to analyze kernel messages:
176
177 [user@localhost home]$ dmesg
178
179There are a lot of parameters the module can use to change the default
180settings for each device. To list every possible parameter with a brief
181explanation 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
1878. Module parameters
188====================
189Module parameters are listed below:
190-------------------------------------------------------------------------------
191Name: ovmod_load
192Type: bool
193Syntax: <0|1>
194Description: 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.
199Default: 1
200Note: 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-------------------------------------------------------------------------------
204Name: vppmod_load
205Type: bool
206Syntax: <0|1>
207Description: 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.
215Default: 1
216Note: 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-------------------------------------------------------------------------------
220Name: simcams
221Type: int
222Syntax: <n>
223Description: Number of cameras allowed to stream simultaneously.
224 n may vary from 0 to 32.
225Default: 32
226-------------------------------------------------------------------------------
227Name: video_nr
228Type: int array (min = 0, max = 32)
229Syntax: <-1|n[,...]>
230Description: 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.
238Default: -1
239-------------------------------------------------------------------------------
240Name: packet_size
241Type: int array (min = 0, max = 32)
242Syntax: <n[,...]>
243Description: Specify the maximum data payload size in bytes for alternate
244 settings, for each device. n is scaled between 63 and 1023.
245Default: 1023
246-------------------------------------------------------------------------------
247Name: max_buffers
248Type: int array (min = 0, max = 32)
249Syntax: <n[,...]>
250Description: For advanced users.
251 Specify the maximum number of video frame buffers to allocate
252 for each device, from 2 to 32.
253Default: 2
254-------------------------------------------------------------------------------
255Name: double_buffer
256Type: bool array (min = 0, max = 32)
257Syntax: <0|1[,...]>
258Description: 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.
262Default: 1 for every device.
263-------------------------------------------------------------------------------
264Name: clamping
265Type: bool array (min = 0, max = 32)
266Syntax: <0|1[,...]>
267Description: Video data clamping: 0 disabled, 1 enabled.
268Default: 0 for every device.
269-------------------------------------------------------------------------------
270Name: filter_type
271Type: int array (min = 0, max = 32)
272Syntax: <0|1|2[,...]>
273Description: 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.
277Default: 0 for every device.
278-------------------------------------------------------------------------------
279Name: largeview
280Type: bool array (min = 0, max = 32)
281Syntax: <0|1[,...]>
282Description: Large view: 0 disabled, 1 enabled.
283Default: 1 for every device.
284-------------------------------------------------------------------------------
285Name: upscaling
286Type: bool array (min = 0, max = 32)
287Syntax: <0|1[,...]>
288Description: 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.
292Default: 0 for every device.
293Note: If 'w9968cf-vpp' is not present, this parameter is set to 0.
294-------------------------------------------------------------------------------
295Name: decompression
296Type: int array (min = 0, max = 32)
297Syntax: <0|1|2[,...]>
298Description: 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.
307Default: 2 for every device.
308Note: If 'w9968cf-vpp' is not present, forcing decompression is not
309 allowed; in this case this parameter is set to 2.
310-------------------------------------------------------------------------------
311Name: force_palette
312Type: int array (min = 0, max = 32)
313Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
314Description: 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'.
329Default: 0 for every device. Initial palette is 9 (UYVY).
330Note: If 'w9968cf-vpp' is not present, this parameter is set to 9.
331-------------------------------------------------------------------------------
332Name: force_rgb
333Type: bool array (min = 0, max = 32)
334Syntax: <0|1[,...]>
335Description: 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.
339Default: 0 for every device.
340-------------------------------------------------------------------------------
341Name: autobright
342Type: bool array (min = 0, max = 32)
343Syntax: <0|1[,...]>
344Description: Image sensor automatically changes brightness:
345 0 = no, 1 = yes
346Default: 0 for every device.
347-------------------------------------------------------------------------------
348Name: autoexp
349Type: bool array (min = 0, max = 32)
350Syntax: <0|1[,...]>
351Description: Image sensor automatically changes exposure:
352 0 = no, 1 = yes
353Default: 1 for every device.
354-------------------------------------------------------------------------------
355Name: lightfreq
356Type: int array (min = 0, max = 32)
357Syntax: <50|60[,...]>
358Description: Light frequency in Hz:
359 50 for European and Asian lighting, 60 for American lighting.
360Default: 50 for every device.
361-------------------------------------------------------------------------------
362Name: bandingfilter
363Type: bool array (min = 0, max = 32)
364Syntax: <0|1[,...]>
365Description: 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.
370Default: 0 for every device.
371-------------------------------------------------------------------------------
372Name: clockdiv
373Type: int array (min = 0, max = 32)
374Syntax: <-1|n[,...]>
375Description: 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.
379Default: -1 for every device.
380-------------------------------------------------------------------------------
381Name: backlight
382Type: bool array (min = 0, max = 32)
383Syntax: <0|1[,...]>
384Description: Objects are lit from behind:
385 0 = no, 1 = yes
386Default: 0 for every device.
387-------------------------------------------------------------------------------
388Name: mirror
389Type: bool array (min = 0, max = 32)
390Syntax: <0|1[,...]>
391Description: Reverse image horizontally:
392 0 = no, 1 = yes
393Default: 0 for every device.
394-------------------------------------------------------------------------------
395Name: monochrome
396Type: bool array (min = 0, max = 32)
397Syntax: <0|1[,...]>
398Description: The image sensor is monochrome:
399 0 = no, 1 = yes
400Default: 0 for every device.
401-------------------------------------------------------------------------------
402Name: brightness
403Type: long array (min = 0, max = 32)
404Syntax: <n[,...]>
405Description: Set picture brightness (0-65535).
406 This parameter has no effect if 'autobright' is enabled.
407Default: 31000 for every device.
408-------------------------------------------------------------------------------
409Name: hue
410Type: long array (min = 0, max = 32)
411Syntax: <n[,...]>
412Description: Set picture hue (0-65535).
413Default: 32768 for every device.
414-------------------------------------------------------------------------------
415Name: colour
416Type: long array (min = 0, max = 32)
417Syntax: <n[,...]>
418Description: Set picture saturation (0-65535).
419Default: 32768 for every device.
420-------------------------------------------------------------------------------
421Name: contrast
422Type: long array (min = 0, max = 32)
423Syntax: <n[,...]>
424Description: Set picture contrast (0-65535).
425Default: 50000 for every device.
426-------------------------------------------------------------------------------
427Name: whiteness
428Type: long array (min = 0, max = 32)
429Syntax: <n[,...]>
430Description: Set picture whiteness (0-65535).
431Default: 32768 for every device.
432-------------------------------------------------------------------------------
433Name: debug
434Type: int
435Syntax: <n>
436Description: 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.
446Default: 2
447-------------------------------------------------------------------------------
448Name: specific_debug
449Type: bool
450Syntax: <0|1>
451Description: 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'.
454Default: 0
455-------------------------------------------------------------------------------
456
457
4589. Contact information
459======================
460I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
461
462I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
463My public 1024-bit key should be available at your keyserver; the fingerprint
464is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
465
466
46710. Credits
468==========
469The development would not have proceed much further without having looked at
470the source code of other drivers and without the help of several persons; in
471particular:
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.