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