1 2 W996[87]CF JPEG USB Dual Mode Camera Chip 3 Linux 2.4 driver (basic version) 4 ========================================= 5 6 - Documentation - 7 8 9Index 10===== 111. Copyright 122. License 133. Overview 144. Supported devices 155. Module dependencies 166. Module loading 177. Module paramaters 188. Credits 19 20 211. Copyright 22============ 23Copyright (C) 2002 2003 by Luca Risolia <luca.risolia@studio.unibo.it> 24 25 262. License 27========== 28This program is free software; you can redistribute it and/or modify 29it under the terms of the GNU General Public License as published by 30the Free Software Foundation; either version 2 of the License, or 31(at your option) any later version. 32 33This program is distributed in the hope that it will be useful, 34but WITHOUT ANY WARRANTY; without even the implied warranty of 35MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 36GNU General Public License for more details. 37 38You should have received a copy of the GNU General Public License 39along with this program; if not, write to the Free Software 40Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 41 42 433. Overview 44=========== 45This driver supports the video streaming capabilities of the devices mounting 46Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips, when they 47are being commanded by USB. 48 49The full-featured driver is divided into two modules: the basic one, "w9968cf", 50is needed for the supported devices to work; the second one, "w9968cf-vpp", 51is an optional module, which provides some useful video post-processing 52functions like video decoding, up-scaling and colour conversions. Once the 53driver is installed, every time an application tries to open a recognized 54device, "w9968cf" checks the presence of the "w9968cf-vpp" module and loads it 55automatically by default. 56 57Please keep in mind that official kernels do NOT include the second module for 58performance purposes. However it is always recommended to download and install 59the latest and complete release of the driver, replacing the existing one, if 60present: it will be still even possible not to load the "w9968cf-vpp" module at 61all, if you ever want to. Another important missing feature of the version in 62the official Linux 2.4 kernels is the writeable /proc filesystem interface. 63 64The latest and full-featured version of the W996[87]CF driver can be found at: 65http://go.lamarinapunto.com/ 66 67Up to 32 cameras can be handled at the same time. They can be connected and 68disconnected from the host many times without turning off the computer, if 69your system supports the hotplug facility. 70 71To change the default settings for each camera, many paramaters can be passed 72through command line when the module is loaded into memory. 73 74The driver relies on the Video4Linux, USB and I2C core modules of the official 75Linux kernels, version 2.4.19 or greater, and is not compatible in any way with 76previous versions. It has been designed to run properly on SMP systems as well. 77At the moment, an additional module, "ovcamchip", is mandatory; it provides 78support for some OmniVision CMOS sensors connected to the W996[87]CF chips. 79 80The "ovcamchip" module is part of the OV511 driver, version 2.27, which can be 81downloaded from internet: 82http://alpha.dyndns.org/ov511/ 83To know how to compile it, read the documentation included in the OV511 84package. 85 86 874. Supported devices 88==================== 89At the moment, known W996[87]CF based devices are: 90- Aroma Digi Pen ADG-5000 Refurbished 91- AVerTV USB 92- Creative Labs Video Blaster WebCam Go 93- Creative Labs Video Blaster WebCam Go Plus 94- Die Lebon LDC-D35A Digital Kamera 95- Ezonics EZ-802 EZMega Cam 96- OPCOM Digi Pen VGA Dual Mode Pen Camera 97 98If you know any other W996[87]CF based cameras, please contact me. 99 100The list above does NOT imply that all those devices work with this driver: up 101until now only webcams that have a CMOS sensor supported by the "ovcamchip" 102module work. 103For a list of supported CMOS sensors, please visit the the author's homepage on 104this module: http://alpha.dyndns.org/ov511/ 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 1145. Module dependencies 115====================== 116The driver needs kernel support for Video4Linux, USB and I2C, and a third-party 117module for the CMOS sensor. 118 119The following options of the kernel configuration file must be enabled and 120corresponding modules must be compiled: 121 122 # Multimedia devices 123 # 124 CONFIG_VIDEO_DEV=m 125 126 # I2C support 127 # 128 CONFIG_I2C=m 129 130The I2C core module can be compiled statically in the kernel as well. 131 132 # USB support 133 # 134 CONFIG_USB=m 135 136In addition, depending on the hardware being used, only one of the modules 137below is necessary: 138 139 # USB Host Controller Drivers 140 # 141 CONFIG_USB_EHCI_HCD=m 142 CONFIG_USB_UHCI=m 143 CONFIG_USB_UHCI_ALT=m 144 CONFIG_USB_OHCI=m 145 146And finally: 147 148 # USB Multimedia devices 149 # 150 CONFIG_USB_W9968CF=m 151 152Also, make sure "Enforce bandwidth allocation" is NOT enabled. 153 154The /proc filesystem can be optionally built into the kernel: 155 156 # File systems 157 # 158 CONFIG_PROC_FS=y 159 160 # Video For Linux 161 # 162 CONFIG_VIDEO_PROC_FS=y 163 164The last module we need is "ovcamchip.o". To obtain it, you have to download 165the OV511, version 2.27 - don't use other versions - and compile it according 166to its documentation. 167The package is available at http://alpha.dyndns.org/ov511/ . 168 169 1706. Module loading 171================= 172To use the driver, it is necessary to load the "w9968cf" module into memory 173after every other module required: for the 2.4 series of the kernel, they are 174named, in order: "videodev", "usbcore", then "ehci-hcd", "usb-uhci", "uhci", 175"usb-ohci" (just one), and also "i2c-core" and "ovcamchip". 176 177Loading can be done this way, from root: 178 179 [root@localhost home]# modprobe i2c-core 180 [root@localhost ov511-x.xx]# insmod ./ovcamchip.o 181 [root@localhost home]# modprobe w9968cf 182 183At this point the devices should be recognized. There are two ways of verifying 184that the loading process has gone well: the first is to analyze kernel 185messages: 186 187 [user@localhost home]$ dmesg 188 189A second way is to retrieve informations from the entries that have just been 190created in the /proc/video/w9968cf/ directory; this feature works if and only 191if the kernel has been built with the /proc filesystem support. 192As an example, the following command will print the list of registered cameras: 193 194 [user@localhost home]$ cat /proc/video/w9968cf/global 195 196There are a lot of parameters the module can use to change the default 197settings for each device. To list every possible parameter with a brief 198explanation about them and which syntax to use, it is recommended to run the 199"modinfo" command: 200 201 [root@locahost home]# modinfo w9968cf 202 203 2047. Module paramaters 205==================== 206Module paramaters are listed below: 207------------------------------------------------------------------------------- 208Name: vppmod_load 209Type: bool 210Syntax: <0|1> 211Description: Automatic 'w9968cf-vpp' module loading: 0 disabled, 1 enabled. 212 If enabled, every time an application attempts to open a 213 camera, 'insmod' searches for the video post-processing module 214 in the system and loads it automatically (if present). 215 The 'w9968cf-vpp' module adds extra image manipulation 216 capabilities to the 'w9968cf' module,like software up-scaling, 217 colour conversions and video decoding. 218Default: 1 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 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 paramater 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 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 loaded, this paramater 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 loaded, forcing decompression is not 309 allowed; in this case this paramater 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 paramater will override 'decompression'. 329Default: 0 for every device. Initial palette is 9 (UYVY). 330Note: If 'w9968cf-vpp' is not loaded, this paramater 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: CMOS 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: CMOS 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 paramater. 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 CMOS 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 just 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 4588. Credits 459========== 460The development would not have proceed much further without having looked at 461the source code of other drivers and without the help of several persons; in 462particular: 463 464- the I2C interface to kernel and high-level CMOS sensor control routines have 465 been taken from the OV511 driver by Mark McClelland; 466 467- memory management code has been copied from the bttv driver by Ralph Metzler, 468 Marcus Metzler and Gerd Knorr; 469 470- the low-level I2C read function has been written by Frederic Jouault; 471 472- the low-level I2C fast write function has been written by Piotr Czerczak. 473