Documentation/usb/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. License
  13 3. Overview
  14 4. Supported devices
  15 5. Module dependencies
  16 6. Module loading
  17 7. Module paramaters
  18 8. Contact information
  19 9. Credits
  20
  21
  22 1. Copyright
  23 ============
  24 Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
  25
  26 Winbond is a trademark of Winbond Electronics Corporation.
  27 This driver is not sponsored or developed by Winbond.
  28
  29
  30 2. License
  31 ==========
  32 This program is free software; you can redistribute it and/or modify
  33 it under the terms of the GNU General Public License as published by
  34 the Free Software Foundation; either version 2 of the License, or
  35 (at your option) any later version.
  36
  37 This program is distributed in the hope that it will be useful,
  38 but WITHOUT ANY WARRANTY; without even the implied warranty of
  39 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  40 GNU General Public License for more details.
  41
  42 You should have received a copy of the GNU General Public License
  43 along with this program; if not, write to the Free Software
  44 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  45
  46
  47 3. Overview
  48 ===========
  49 This driver supports the video streaming capabilities of the devices mounting
  50 Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
  51 based cameras should be supported as well.
  52
  53 The driver is divided into two modules: the basic one, "w9968cf", is needed for
  54 the supported devices to work; the second one, "w9968cf-vpp", is an optional
  55 module, which provides some useful video post-processing functions like video
  56 decoding, up-scaling and colour conversions. Once the driver is installed,
  57 every time an application tries to open a recognized device, "w9968cf" checks
  58 the presence of the "w9968cf-vpp" module and loads it automatically by default.
  59
  60 Please keep in mind that official kernels do NOT include the second module for
  61 performance purposes. However it is always recommended to download and install
  62 the latest and complete release of the driver, replacing the existing one, if
  63 present: it will be still even possible not to load the "w9968cf-vpp" module at
  64 all, if you ever want to. Another important missing feature of the version in
  65 the official Linux 2.4 kernels is the writeable /proc filesystem interface.
  66
  67 The latest and full-featured version of the W996[87]CF driver can be found at:
  68 http://go.lamarinapunto.com/ . 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 4. 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.
 105 For a list of supported image sensors, please visit the author's homepage on
 106 this module: http://alpha.dyndns.org/ov511/
 107
 108 Possible external microcontrollers of those webcams are not supported: this
 109 means that still images cannot be downloaded from the device memory.
 110
 111 Furthermore, it's worth to note that I was only able to run tests on my
 112 "Creative Labs Video Blaster WebCam Go". Donations of other models, for
 113 additional testing and full support, would be much appreciated.
 114
 115
 116 5. Module dependencies
 117 ======================
 118 For it to work properly, the driver needs kernel support for Video4Linux, USB
 119 and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
 120 actually using any external "ovcamchip" module, given that the W996[87]CF
 121 driver depends on the version of the module present in the official kernels.
 122
 123 The following options of the kernel configuration file must be enabled and
 124 corresponding modules must be compiled:
 125
 126         # Multimedia devices
 127         #
 128         CONFIG_VIDEO_DEV=m
 129
 130         # I2C support
 131         #
 132         CONFIG_I2C=m
 133
 134 The I2C core module can be compiled statically in the kernel as well.
 135
 136         # OmniVision Camera Chip support
 137         #
 138         CONFIG_VIDEO_OVCAMCHIP=m
 139
 140         # USB support
 141         #
 142         CONFIG_USB=m
 143
 144 In addition, depending on the hardware being used, only one of the modules
 145 below is necessary:
 146
 147         # USB Host Controller Drivers
 148         #
 149         CONFIG_USB_EHCI_HCD=m
 150         CONFIG_USB_UHCI_HCD=m
 151         CONFIG_USB_OHCI_HCD=m
 152
 153 And finally:
 154
 155         # USB Multimedia devices
 156         #
 157         CONFIG_USB_W9968CF=m
 158
 159
 160 6. Module loading
 161 =================
 162 To use the driver, it is necessary to load the "w9968cf" module into memory
 163 after every other module required.
 164
 165 Loading can be done this way, from root:
 166
 167         [root@localhost home]# modprobe usbcore
 168         [root@localhost home]# modprobe i2c-core
 169         [root@localhost home]# modprobe w9968cf
 170
 171 At this point the pertinent devices should be recognized: "dmesg" can be used
 172 to analyze kernel messages:
 173
 174         [user@localhost home]$ dmesg
 175
 176 There are a lot of parameters the module can use to change the default
 177 settings for each device. To list every possible parameter with a brief
 178 explanation about them and which syntax to use, it is recommended to run the
 179 "modinfo" command:
 180
 181         [root@locahost home]# modinfo w9968cf
 182
 183
 184 7. Module parameters
 185 ====================
 186 Module parameters are listed below:
 187 -------------------------------------------------------------------------------
 188 Name:            ovmod_load
 189 Type:            bool
 190 Syntax:          <0|1>
 191 Description:     Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled.
 192                  If enabled, 'insmod' searches for the required 'ovcamchip'
 193                  module in the system, according to its configuration, and
 194                  loads that module automatically. This action is performed as
 195                  once soon as the 'w9968cf' module is loaded into memory.
 196 Default:         1
 197 Note:            The kernel must be compiled with the CONFIG_KMOD option
 198                  enabled for the 'ovcamchip' module to be loaded and for
 199                  this parameter to be present.
 200 -------------------------------------------------------------------------------
 201 Name:           vppmod_load
 202 Type:           bool
 203 Syntax:         <0|1>
 204 Description:    Automatic 'w9968cf-vpp' module loading: 0 disabled, 1 enabled.
 205                 If enabled, every time an application attempts to open a
 206                 camera, 'insmod' searches for the video post-processing module
 207                 in the system and loads it automatically (if present).
 208                 The optional 'w9968cf-vpp' module adds extra image manipulation
 209                 capabilities to the 'w9968cf' module,like software up-scaling,
 210                 colour conversions and video decompression for very high frame
 211                 rates.
 212 Default:        1
 213 Note:           The kernel must be compiled with the CONFIG_KMOD option
 214                 enabled for the 'w9968cf-vpp' module to be loaded and for
 215                 this parameter to be present.
 216 -------------------------------------------------------------------------------
 217 Name:           simcams
 218 Type:           int
 219 Syntax:         <n>
 220 Description:    Number of cameras allowed to stream simultaneously.
 221                 n may vary from 0 to 32.
 222 Default:        32
 223 -------------------------------------------------------------------------------
 224 Name:           video_nr
 225 Type:           int array (min = 0, max = 32)
 226 Syntax:         <-1|n[,...]>
 227 Description:    Specify V4L minor mode number.
 228                 -1 = use next available
 229                  n = use minor number n
 230                 You can specify up to 32 cameras this way.
 231                 For example:
 232                 video_nr=-1,2,-1 would assign minor number 2 to the second
 233                 recognized camera and use auto for the first one and for every
 234                 other camera.
 235 Default:        -1
 236 -------------------------------------------------------------------------------
 237 Name:           packet_size
 238 Type:           int array (min = 0, max = 32)
 239 Syntax:         <n[,...]>
 240 Description:    Specify the maximum data payload size in bytes for alternate
 241                 settings, for each device. n is scaled between 63 and 1023.
 242 Default:        1023
 243 -------------------------------------------------------------------------------
 244 Name:           max_buffers
 245 Type:           int array (min = 0, max = 32)
 246 Syntax:         <n[,...]>
 247 Description:    For advanced users.
 248                 Specify the maximum number of video frame buffers to allocate
 249                 for each device, from 2 to 32.
 250 Default:        2
 251 -------------------------------------------------------------------------------
 252 Name:           double_buffer
 253 Type:           bool array (min = 0, max = 32)
 254 Syntax:         <0|1[,...]>
 255 Description:    Hardware double buffering: 0 disabled, 1 enabled.
 256                 It should be enabled if you want smooth video output: if you
 257                 obtain out of sync. video, disable it, or try to
 258                 decrease the 'clockdiv' module parameter value.
 259 Default:        1 for every device.
 260 -------------------------------------------------------------------------------
 261 Name:           clamping
 262 Type:           bool array (min = 0, max = 32)
 263 Syntax:         <0|1[,...]>
 264 Description:    Video data clamping: 0 disabled, 1 enabled.
 265 Default:        0 for every device.
 266 -------------------------------------------------------------------------------
 267 Name:           filter_type
 268 Type:           int array (min = 0, max = 32)
 269 Syntax:         <0|1|2[,...]>
 270 Description:    Video filter type.
 271                 0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter.
 272                 The filter is used to reduce noise and aliasing artifacts
 273                 produced by the CCD or CMOS image sensor.
 274 Default:        0 for every device.
 275 -------------------------------------------------------------------------------
 276 Name:           largeview
 277 Type:           bool array (min = 0, max = 32)
 278 Syntax:         <0|1[,...]>
 279 Description:    Large view: 0 disabled, 1 enabled.
 280 Default:        1 for every device.
 281 -------------------------------------------------------------------------------
 282 Name:           upscaling
 283 Type:           bool array (min = 0, max = 32)
 284 Syntax:         <0|1[,...]>
 285 Description:    Software scaling (for non-compressed video only):
 286                 0 disabled, 1 enabled.
 287                 Disable it if you have a slow CPU or you don't have enough
 288                 memory.
 289 Default:        0 for every device.
 290 Note:           If 'w9968cf-vpp' is not present, this parameter is set to 0.
 291 -------------------------------------------------------------------------------
 292 Name:           decompression
 293 Type:           int array (min = 0, max = 32)
 294 Syntax:         <0|1|2[,...]>
 295 Description:    Software video decompression:
 296                 0 = disables decompression
 297                     (doesn't allow formats needing decompression).
 298                 1 = forces decompression
 299                     (allows formats needing decompression only).
 300                 2 = allows any permitted formats.
 301                 Formats supporting (de)compressed video are YUV422P and
 302                 YUV420P/YUV420 in any resolutions where width and height are
 303                 multiples of 16.
 304 Default:        2 for every device.
 305 Note:           If 'w9968cf-vpp' is not present, forcing decompression is not
 306                 allowed; in this case this parameter is set to 2.
 307 -------------------------------------------------------------------------------
 308 Name:           force_palette
 309 Type:           int array (min = 0, max = 32)
 310 Syntax:         <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
 311 Description:    Force picture palette.
 312                 In order:
 313                  0 = Off - allows any of the following formats:
 314                  9 = UYVY    16 bpp - Original video, compression disabled
 315                 10 = YUV420  12 bpp - Original video, compression enabled
 316                 13 = YUV422P 16 bpp - Original video, compression enabled
 317                 15 = YUV420P 12 bpp - Original video, compression enabled
 318                  8 = YUVY    16 bpp - Software conversion from UYVY
 319                  7 = YUV422  16 bpp - Software conversion from UYVY
 320                  1 = GREY     8 bpp - Software conversion from UYVY
 321                  6 = RGB555  16 bpp - Software conversion from UYVY
 322                  3 = RGB565  16 bpp - Software conversion from UYVY
 323                  4 = RGB24   24 bpp - Software conversion from UYVY
 324                  5 = RGB32   32 bpp - Software conversion from UYVY
 325                 When not 0, this parameter will override 'decompression'.
 326 Default:        0 for every device. Initial palette is 9 (UYVY).
 327 Note:           If 'w9968cf-vpp' is not present, this parameter is set to 9.
 328 -------------------------------------------------------------------------------
 329 Name:           force_rgb
 330 Type:           bool array (min = 0, max = 32)
 331 Syntax:         <0|1[,...]>
 332 Description:    Read RGB video data instead of BGR:
 333                 1 = use RGB component ordering.
 334                 0 = use BGR component ordering.
 335                 This parameter has effect when using RGBX palettes only.
 336 Default:        0 for every device.
 337 -------------------------------------------------------------------------------
 338 Name:           autobright
 339 Type:           bool array (min = 0, max = 32)
 340 Syntax:         <0|1[,...]>
 341 Description:    Image sensor automatically changes brightness:
 342                 0 = no, 1 = yes
 343 Default:        0 for every device.
 344 -------------------------------------------------------------------------------
 345 Name:           autoexp
 346 Type:           bool array (min = 0, max = 32)
 347 Syntax:         <0|1[,...]>
 348 Description:    Image sensor automatically changes exposure:
 349                 0 = no, 1 = yes
 350 Default:        1 for every device.
 351 -------------------------------------------------------------------------------
 352 Name:           lightfreq
 353 Type:           int array (min = 0, max = 32)
 354 Syntax:         <50|60[,...]>
 355 Description:    Light frequency in Hz:
 356                 50 for European and Asian lighting, 60 for American lighting.
 357 Default:        50 for every device.
 358 -------------------------------------------------------------------------------
 359 Name:           bandingfilter
 360 Type:           bool array (min = 0, max = 32)
 361 Syntax:         <0|1[,...]>
 362 Description:    Banding filter to reduce effects of fluorescent
 363                 lighting:
 364                 0 disabled, 1 enabled.
 365                 This filter tries to reduce the pattern of horizontal
 366                 light/dark bands caused by some (usually fluorescent) lighting.
 367 Default:        0 for every device.
 368 -------------------------------------------------------------------------------
 369 Name:           clockdiv
 370 Type:           int array (min = 0, max = 32)
 371 Syntax:         <-1|n[,...]>
 372 Description:    Force pixel clock divisor to a specific value (for experts):
 373                 n may vary from 0 to 127.
 374                 -1 for automatic value.
 375                 See also the 'double_buffer' module parameter.
 376 Default:        -1 for every device.
 377 -------------------------------------------------------------------------------
 378 Name:           backlight
 379 Type:           bool array (min = 0, max = 32)
 380 Syntax:         <0|1[,...]>
 381 Description:    Objects are lit from behind:
 382                 0 = no, 1 = yes
 383 Default:        0 for every device.
 384 -------------------------------------------------------------------------------
 385 Name:           mirror
 386 Type:           bool array (min = 0, max = 32)
 387 Syntax:         <0|1[,...]>
 388 Description:    Reverse image horizontally:
 389                 0 = no, 1 = yes
 390 Default:        0 for every device.
 391 -------------------------------------------------------------------------------
 392 Name:           monochrome
 393 Type:           bool array (min = 0, max = 32)
 394 Syntax:         <0|1[,...]>
 395 Description:    The image sensor is monochrome:
 396                 0 = no, 1 = yes
 397 Default:        0 for every device.
 398 -------------------------------------------------------------------------------
 399 Name:           brightness
 400 Type:           long array (min = 0, max = 32)
 401 Syntax:         <n[,...]>
 402 Description:    Set picture brightness (0-65535).
 403                 This parameter has no effect if 'autobright' is enabled.
 404 Default:        31000 for every device.
 405 -------------------------------------------------------------------------------
 406 Name:           hue
 407 Type:           long array (min = 0, max = 32)
 408 Syntax:         <n[,...]>
 409 Description:    Set picture hue (0-65535).
 410 Default:        32768 for every device.
 411 -------------------------------------------------------------------------------
 412 Name:           colour
 413 Type:           long array (min = 0, max = 32)
 414 Syntax:         <n[,...]>
 415 Description:    Set picture saturation (0-65535).
 416 Default:        32768 for every device.
 417 -------------------------------------------------------------------------------
 418 Name:           contrast
 419 Type:           long array (min = 0, max = 32)
 420 Syntax:         <n[,...]>
 421 Description:    Set picture contrast (0-65535).
 422 Default:        50000 for every device.
 423 -------------------------------------------------------------------------------
 424 Name:           whiteness
 425 Type:           long array (min = 0, max = 32)
 426 Syntax:         <n[,...]>
 427 Description:    Set picture whiteness (0-65535).
 428 Default:        32768 for every device.
 429 -------------------------------------------------------------------------------
 430 Name:           debug
 431 Type:           int
 432 Syntax:         <n>
 433 Description:    Debugging information level, from 0 to 6:
 434                 0 = none (use carefully)
 435                 1 = critical errors
 436                 2 = significant informations
 437                 3 = configuration or general messages
 438                 4 = warnings
 439                 5 = called functions
 440                 6 = function internals
 441                 Level 5 and 6 are useful for testing only, when only one
 442                 device is used.
 443 Default:        2
 444 -------------------------------------------------------------------------------
 445 Name:           specific_debug
 446 Type:           bool
 447 Syntax:         <0|1>
 448 Description:    Enable or disable specific debugging messages:
 449                 0 = print messages concerning every level <= 'debug' level.
 450                 1 = print messages concerning the level indicated by 'debug'.
 451 Default:        0
 452 -------------------------------------------------------------------------------
 453
 454
 455 8. Contact information
 456 ======================
 457 I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
 458
 459 I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
 460 My public 1024-bit key should be available at your keyserver; the fingerprint
 461 is: '88E8 F32F 7244 68BA 3958  5D40 99DA 5D2A FCE6 35A4'.
 462
 463
 464 9. Credits
 465 ==========
 466 The development would not have proceed much further without having looked at
 467 the source code of other drivers and without the help of several persons; in
 468 particular:
 469
 470 - the I2C interface to kernel and high-level image sensor control routines have
 471   been taken from the OV511 driver by Mark McClelland;
 472
 473 - memory management code has been copied from the bttv driver by Ralph Metzler,
 474   Marcus Metzler and Gerd Knorr;
 475
 476 - the low-level I2C read function has been written by Frederic Jouault;
 477
 478 - the low-level I2C fast write function has been written by Piotr Czerczak.