Documentation/usb/w9968cf.txt

   1
   2                    W996[87]CF JPEG USB Dual Mode Camera Chip
   3                         Linux 2.4 driver (basic version)
   4                    =========================================
   5
   6                                - Documentation -
   7
   8
   9 Index
  10 =====
  11 1. Copyright
  12 2. License
  13 3. Overview
  14 4. Supported devices
  15 5. Module dependencies
  16 6. Module loading
  17 7. Module paramaters
  18 8. Credits
  19
  20
  21 1. Copyright
  22 ============
  23 Copyright (C) 2002 2003 by Luca Risolia <luca.risolia@studio.unibo.it>
  24
  25
  26 2. License
  27 ==========
  28 This program is free software; you can redistribute it and/or modify
  29 it under the terms of the GNU General Public License as published by
  30 the Free Software Foundation; either version 2 of the License, or
  31 (at your option) any later version.
  32
  33 This program is distributed in the hope that it will be useful,
  34 but WITHOUT ANY WARRANTY; without even the implied warranty of
  35 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  36 GNU General Public License for more details.
  37
  38 You should have received a copy of the GNU General Public License
  39 along with this program; if not, write to the Free Software
  40 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  41
  42
  43 3. Overview
  44 ===========
  45 This driver supports the video streaming capabilities of the devices mounting
  46 Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips, when they
  47 are being commanded by USB.
  48
  49 The full-featured driver is divided into two modules: the basic one, "w9968cf",
  50 is needed for the supported devices to work; the second one, "w9968cf-vpp",
  51 is an optional module, which provides some useful video post-processing
  52 functions like video decoding, up-scaling and colour conversions. Once the
  53 driver is installed, every time an application tries to open a recognized
  54 device, "w9968cf" checks the presence of the "w9968cf-vpp" module and loads it
  55 automatically by default.
  56
  57 Please keep in mind that official kernels do NOT include the second module for
  58 performance purposes. However it is always recommended to download and install
  59 the latest and complete release of the driver, replacing the existing one, if
  60 present: it will be still even possible not to load the "w9968cf-vpp" module at
  61 all, if you ever want to. Another important missing feature of the version in
  62 the official Linux 2.4 kernels is the writeable /proc filesystem interface.
  63
  64 The latest and full-featured version of the W996[87]CF driver can be found at:
  65 http://go.lamarinapunto.com/
  66
  67 Up to 32 cameras can be handled at the same time. They can be connected and
  68 disconnected from the host many times without turning off the computer, if
  69 your system supports the hotplug facility.
  70
  71 To change the default settings for each camera, many paramaters can be passed
  72 through command line when the module is loaded into memory.
  73
  74 The driver relies on the Video4Linux, USB and I2C core modules of the official
  75 Linux kernels, version 2.4.19 or greater, and is not compatible in any way with
  76 previous versions. It has been designed to run properly on SMP systems as well.
  77 At the moment, an additional module, "ovcamchip", is mandatory; it provides
  78 support for some OmniVision CMOS sensors connected to the W996[87]CF chips.
  79
  80 The "ovcamchip" module is part of the OV511 driver, version 2.27, which can be
  81 downloaded from internet:
  82 http://alpha.dyndns.org/ov511/
  83 To know how to compile it, read the documentation included in the OV511
  84 package.
  85
  86
  87 4. Supported devices
  88 ====================
  89 At 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
  98 If you know any other W996[87]CF based cameras, please contact me.
  99
 100 The list above does NOT imply that all those devices work with this driver: up
 101 until now only webcams that have a CMOS sensor supported by the "ovcamchip"
 102 module work.
 103 For a list of supported CMOS sensors, please visit the the author's homepage on
 104 this module: http://alpha.dyndns.org/ov511/
 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 5. Module dependencies
 115 ======================
 116 The driver needs kernel support for Video4Linux, USB and I2C, and a third-party
 117 module for the CMOS sensor.
 118
 119 The following options of the kernel configuration file must be enabled and
 120 corresponding modules must be compiled:
 121
 122         # Multimedia devices
 123         #
 124         CONFIG_VIDEO_DEV=m
 125
 126         # I2C support
 127         #
 128         CONFIG_I2C=m
 129
 130 The I2C core module can be compiled statically in the kernel as well.
 131
 132         # USB support
 133         #
 134         CONFIG_USB=m
 135
 136 In addition, depending on the hardware being used, only one of the modules
 137 below 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
 146 And finally:
 147
 148         # USB Multimedia devices
 149         #
 150         CONFIG_USB_W9968CF=m
 151
 152 Also, make sure "Enforce bandwidth allocation" is NOT enabled.
 153
 154 The /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
 164 The last module we need is "ovcamchip.o". To obtain it, you have to download
 165 the OV511, version 2.27 - don't use other versions - and compile it according
 166 to its documentation.
 167 The package is available at http://alpha.dyndns.org/ov511/ .
 168
 169
 170 6. Module loading
 171 =================
 172 To use the driver, it is necessary to load the "w9968cf" module into memory
 173 after every other module required: for the 2.4 series of the kernel, they are
 174 named, in order: "videodev", "usbcore", then "ehci-hcd", "usb-uhci", "uhci",
 175 "usb-ohci" (just one), and also "i2c-core" and "ovcamchip".
 176
 177 Loading 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
 183 At this point the devices should be recognized. There are two ways of verifying
 184 that the loading process has gone well: the first is to analyze kernel
 185 messages:
 186
 187         [user@localhost home]$ dmesg
 188
 189 A second way is to retrieve informations from the entries that have just been
 190 created in the /proc/video/w9968cf/ directory; this feature works if and only
 191 if the kernel has been built with the /proc filesystem support.
 192 As an example, the following command will print the list of registered cameras:
 193
 194         [user@localhost home]$ cat /proc/video/w9968cf/global
 195
 196 There are a lot of parameters the module can use to change the default
 197 settings for each device. To list every possible parameter with a brief
 198 explanation 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
 204 7. Module paramaters
 205 ====================
 206 Module paramaters are listed below:
 207 -------------------------------------------------------------------------------
 208 Name:           vppmod_load
 209 Type:           bool
 210 Syntax:         <0|1>
 211 Description:    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.
 218 Default:        1
 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 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 paramater 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 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 loaded, this paramater 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 loaded, forcing decompression is not
 309                 allowed; in this case this paramater 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 paramater will override 'decompression'.
 329 Default:        0 for every device. Initial palette is 9 (UYVY).
 330 Note:           If 'w9968cf-vpp' is not loaded, this paramater 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:    CMOS 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:    CMOS 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 paramater.
 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 CMOS 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 just 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 8. Credits
 459 ==========
 460 The development would not have proceed much further without having looked at
 461 the source code of other drivers and without the help of several persons; in
 462 particular:
 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.