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.  Disclaimer
  13 3.  License
  14 4.  Overview
  15 5.  Supported devices
  16 6.  Module dependencies
  17 7.  Module loading
  18 8.  Module paramaters
  19 9.  Contact information
  20 10. Credits
  21
  22
  23 1. Copyright
  24 ============
  25 Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
  26
  27
  28 2. Disclaimer
  29 =============
  30 Winbond is a trademark of Winbond Electronics Corporation.
  31 This software is not sponsored or developed by Winbond.
  32
  33
  34 3. License
  35 ==========
  36 This program is free software; you can redistribute it and/or modify
  37 it under the terms of the GNU General Public License as published by
  38 the Free Software Foundation; either version 2 of the License, or
  39 (at your option) any later version.
  40
  41 This program is distributed in the hope that it will be useful,
  42 but WITHOUT ANY WARRANTY; without even the implied warranty of
  43 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  44 GNU General Public License for more details.
  45
  46 You should have received a copy of the GNU General Public License
  47 along with this program; if not, write to the Free Software
  48 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  49
  50
  51 4. Overview
  52 ===========
  53 This driver supports the video streaming capabilities of the devices mounting
  54 Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
  55 based cameras should be supported as well.
  56
  57 The driver is divided into two modules: the basic one, "w9968cf", is needed for
  58 the supported devices to work; the second one, "w9968cf-vpp", is an optional
  59 module, which provides some useful video post-processing functions like video
  60 decoding, up-scaling and colour conversions.
  61
  62 Note that the official kernels do neither include nor support the second
  63 module for performance purposes. Therefore, it is always recommended to
  64 download and install the latest and complete release of the driver,
  65 replacing the existing one, if present.
  66
  67 The latest and full-featured version of the W996[87]CF driver can be found at:
  68 http://www.linux-projects.org. 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 5. 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. Kernel messages will always tell you whether this is case.
 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 6. Module dependencies
 115 ======================
 116 For it to work properly, the driver needs kernel support for Video4Linux, USB
 117 and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
 118 actually using any external "ovcamchip" module, given that the W996[87]CF
 119 driver depends on the version of the module present in the official kernels.
 120
 121 The following options of the kernel configuration file must be enabled and
 122 corresponding modules must be compiled:
 123
 124         # Multimedia devices
 125         #
 126         CONFIG_VIDEO_DEV=m
 127
 128         # I2C support
 129         #
 130         CONFIG_I2C=m
 131
 132 The 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
 142 In addition, depending on the hardware being used, only one of the modules
 143 below 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
 151 And finally:
 152
 153         # USB Multimedia devices
 154         #
 155         CONFIG_USB_W9968CF=m
 156
 157
 158 7. Module loading
 159 =================
 160 To use the driver, it is necessary to load the "w9968cf" module into memory
 161 after every other module required.
 162
 163 Loading 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
 170 At this point the pertinent devices should be recognized: "dmesg" can be used
 171 to analyze kernel messages:
 172
 173         [user@localhost home]$ dmesg
 174
 175 There are a lot of parameters the module can use to change the default
 176 settings for each device. To list every possible parameter with a brief
 177 explanation 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
 183 8. Module parameters
 184 ====================
 185 Module parameters are listed below:
 186 -------------------------------------------------------------------------------
 187 Name:            ovmod_load
 188 Type:            bool
 189 Syntax:          <0|1>
 190 Description:     Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled.
 191                  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.
 195 Default:         1
 196 Note:            The kernel must be compiled with the CONFIG_KMOD option
 197                  enabled for the 'ovcamchip' module to be loaded and for
 198                  this parameter to be present.
 199 -------------------------------------------------------------------------------
 200 Name:           simcams
 201 Type:           int
 202 Syntax:         <n>
 203 Description:    Number of cameras allowed to stream simultaneously.
 204                 n may vary from 0 to 32.
 205 Default:        32
 206 -------------------------------------------------------------------------------
 207 Name:           video_nr
 208 Type:           int array (min = 0, max = 32)
 209 Syntax:         <-1|n[,...]>
 210 Description:    Specify V4L minor mode number.
 211                 -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.
 218 Default:        -1
 219 -------------------------------------------------------------------------------
 220 Name:           packet_size
 221 Type:           int array (min = 0, max = 32)
 222 Syntax:         <n[,...]>
 223 Description:    Specify the maximum data payload size in bytes for alternate
 224                 settings, for each device. n is scaled between 63 and 1023.
 225 Default:        1023
 226 -------------------------------------------------------------------------------
 227 Name:           max_buffers
 228 Type:           int array (min = 0, max = 32)
 229 Syntax:         <n[,...]>
 230 Description:    For advanced users.
 231                 Specify the maximum number of video frame buffers to allocate
 232                 for each device, from 2 to 32.
 233 Default:        2
 234 -------------------------------------------------------------------------------
 235 Name:           double_buffer
 236 Type:           bool array (min = 0, max = 32)
 237 Syntax:         <0|1[,...]>
 238 Description:    Hardware double buffering: 0 disabled, 1 enabled.
 239                 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.
 242 Default:        1 for every device.
 243 -------------------------------------------------------------------------------
 244 Name:           clamping
 245 Type:           bool array (min = 0, max = 32)
 246 Syntax:         <0|1[,...]>
 247 Description:    Video data clamping: 0 disabled, 1 enabled.
 248 Default:        0 for every device.
 249 -------------------------------------------------------------------------------
 250 Name:           filter_type
 251 Type:           int array (min = 0, max = 32)
 252 Syntax:         <0|1|2[,...]>
 253 Description:    Video filter type.
 254                 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.
 257 Default:        0 for every device.
 258 -------------------------------------------------------------------------------
 259 Name:           largeview
 260 Type:           bool array (min = 0, max = 32)
 261 Syntax:         <0|1[,...]>
 262 Description:    Large view: 0 disabled, 1 enabled.
 263 Default:        1 for every device.
 264 -------------------------------------------------------------------------------
 265 Name:           upscaling
 266 Type:           bool array (min = 0, max = 32)
 267 Syntax:         <0|1[,...]>
 268 Description:    Software scaling (for non-compressed video only):
 269                 0 disabled, 1 enabled.
 270                 Disable it if you have a slow CPU or you don't have enough
 271                 memory.
 272 Default:        0 for every device.
 273 Note:           If 'w9968cf-vpp' is not present, this parameter is set to 0.
 274 -------------------------------------------------------------------------------
 275 Name:           decompression
 276 Type:           int array (min = 0, max = 32)
 277 Syntax:         <0|1|2[,...]>
 278 Description:    Software video decompression:
 279                 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.
 287 Default:        2 for every device.
 288 Note:           If 'w9968cf-vpp' is not present, forcing decompression is not
 289                 allowed; in this case this parameter is set to 2.
 290 -------------------------------------------------------------------------------
 291 Name:           force_palette
 292 Type:           int array (min = 0, max = 32)
 293 Syntax:         <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
 294 Description:    Force picture palette.
 295                 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'.
 309 Default:        0 for every device. Initial palette is 9 (UYVY).
 310 Note:           If 'w9968cf-vpp' is not present, this parameter is set to 9.
 311 -------------------------------------------------------------------------------
 312 Name:           force_rgb
 313 Type:           bool array (min = 0, max = 32)
 314 Syntax:         <0|1[,...]>
 315 Description:    Read RGB video data instead of BGR:
 316                 1 = use RGB component ordering.
 317                 0 = use BGR component ordering.
 318                 This parameter has effect when using RGBX palettes only.
 319 Default:        0 for every device.
 320 -------------------------------------------------------------------------------
 321 Name:           autobright
 322 Type:           bool array (min = 0, max = 32)
 323 Syntax:         <0|1[,...]>
 324 Description:    Image sensor automatically changes brightness:
 325                 0 = no, 1 = yes
 326 Default:        0 for every device.
 327 -------------------------------------------------------------------------------
 328 Name:           autoexp
 329 Type:           bool array (min = 0, max = 32)
 330 Syntax:         <0|1[,...]>
 331 Description:    Image sensor automatically changes exposure:
 332                 0 = no, 1 = yes
 333 Default:        1 for every device.
 334 -------------------------------------------------------------------------------
 335 Name:           lightfreq
 336 Type:           int array (min = 0, max = 32)
 337 Syntax:         <50|60[,...]>
 338 Description:    Light frequency in Hz:
 339                 50 for European and Asian lighting, 60 for American lighting.
 340 Default:        50 for every device.
 341 -------------------------------------------------------------------------------
 342 Name:           bandingfilter
 343 Type:           bool array (min = 0, max = 32)
 344 Syntax:         <0|1[,...]>
 345 Description:    Banding filter to reduce effects of fluorescent
 346                 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.
 350 Default:        0 for every device.
 351 -------------------------------------------------------------------------------
 352 Name:           clockdiv
 353 Type:           int array (min = 0, max = 32)
 354 Syntax:         <-1|n[,...]>
 355 Description:    Force pixel clock divisor to a specific value (for experts):
 356                 n may vary from 0 to 127.
 357                 -1 for automatic value.
 358                 See also the 'double_buffer' module parameter.
 359 Default:        -1 for every device.
 360 -------------------------------------------------------------------------------
 361 Name:           backlight
 362 Type:           bool array (min = 0, max = 32)
 363 Syntax:         <0|1[,...]>
 364 Description:    Objects are lit from behind:
 365                 0 = no, 1 = yes
 366 Default:        0 for every device.
 367 -------------------------------------------------------------------------------
 368 Name:           mirror
 369 Type:           bool array (min = 0, max = 32)
 370 Syntax:         <0|1[,...]>
 371 Description:    Reverse image horizontally:
 372                 0 = no, 1 = yes
 373 Default:        0 for every device.
 374 -------------------------------------------------------------------------------
 375 Name:           monochrome
 376 Type:           bool array (min = 0, max = 32)
 377 Syntax:         <0|1[,...]>
 378 Description:    The image sensor is monochrome:
 379                 0 = no, 1 = yes
 380 Default:        0 for every device.
 381 -------------------------------------------------------------------------------
 382 Name:           brightness
 383 Type:           long array (min = 0, max = 32)
 384 Syntax:         <n[,...]>
 385 Description:    Set picture brightness (0-65535).
 386                 This parameter has no effect if 'autobright' is enabled.
 387 Default:        31000 for every device.
 388 -------------------------------------------------------------------------------
 389 Name:           hue
 390 Type:           long array (min = 0, max = 32)
 391 Syntax:         <n[,...]>
 392 Description:    Set picture hue (0-65535).
 393 Default:        32768 for every device.
 394 -------------------------------------------------------------------------------
 395 Name:           colour
 396 Type:           long array (min = 0, max = 32)
 397 Syntax:         <n[,...]>
 398 Description:    Set picture saturation (0-65535).
 399 Default:        32768 for every device.
 400 -------------------------------------------------------------------------------
 401 Name:           contrast
 402 Type:           long array (min = 0, max = 32)
 403 Syntax:         <n[,...]>
 404 Description:    Set picture contrast (0-65535).
 405 Default:        50000 for every device.
 406 -------------------------------------------------------------------------------
 407 Name:           whiteness
 408 Type:           long array (min = 0, max = 32)
 409 Syntax:         <n[,...]>
 410 Description:    Set picture whiteness (0-65535).
 411 Default:        32768 for every device.
 412 -------------------------------------------------------------------------------
 413 Name:           debug
 414 Type:           int
 415 Syntax:         <n>
 416 Description:    Debugging information level, from 0 to 6:
 417                 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.
 426 Default:        2
 427 -------------------------------------------------------------------------------
 428 Name:           specific_debug
 429 Type:           bool
 430 Syntax:         <0|1>
 431 Description:    Enable or disable specific debugging messages:
 432                 0 = print messages concerning every level <= 'debug' level.
 433                 1 = print messages concerning the level indicated by 'debug'.
 434 Default:        0
 435 -------------------------------------------------------------------------------
 436
 437
 438 9. Contact information
 439 ======================
 440 I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
 441
 442 I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
 443 My public 1024-bit key should be available at your keyserver; the fingerprint
 444 is: '88E8 F32F 7244 68BA 3958  5D40 99DA 5D2A FCE6 35A4'.
 445
 446
 447 10. Credits
 448 ==========
 449 The development would not have proceed much further without having looked at
 450 the source code of other drivers and without the help of several persons; in
 451 particular:
 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.