linux/Documentation/video4linux/w9968cf.txt
<<
>>
Prefs
   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
   9Index
  10=====
  111.  Copyright
  122.  Disclaimer
  133.  License
  144.  Overview
  155.  Supported devices
  166.  Module dependencies
  177.  Module loading
  188.  Module parameters
  199.  Contact information
  2010. Credits
  21
  22
  231. Copyright
  24============
  25Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
  26
  27
  282. Disclaimer
  29=============
  30Winbond is a trademark of Winbond Electronics Corporation.
  31This software is not sponsored or developed by Winbond.
  32
  33
  343. License
  35==========
  36This program is free software; you can redistribute it and/or modify
  37it under the terms of the GNU General Public License as published by
  38the Free Software Foundation; either version 2 of the License, or
  39(at your option) any later version.
  40
  41This program is distributed in the hope that it will be useful,
  42but WITHOUT ANY WARRANTY; without even the implied warranty of
  43MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  44GNU General Public License for more details.
  45
  46You should have received a copy of the GNU General Public License
  47along with this program; if not, write to the Free Software
  48Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  49
  50
  514. Overview
  52===========
  53This driver supports the video streaming capabilities of the devices mounting
  54Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
  55based cameras should be supported as well.
  56
  57The driver is divided into two modules: the basic one, "w9968cf", is needed for
  58the supported devices to work; the second one, "w9968cf-vpp", is an optional
  59module, which provides some useful video post-processing functions like video
  60decoding, up-scaling and colour conversions.
  61
  62Note that the official kernels do neither include nor support the second
  63module for performance purposes. Therefore, it is always recommended to
  64download and install the latest and complete release of the driver,
  65replacing the existing one, if present.
  66
  67The latest and full-featured version of the W996[87]CF driver can be found at:
  68http://www.linux-projects.org. Please refer to the documentation included in
  69that package, if you are going to use it.
  70
  71Up to 32 cameras can be handled at the same time. They can be connected and
  72disconnected from the host many times without turning off the computer, if
  73your system supports the hotplug facility.
  74
  75To change the default settings for each camera, many parameters can be passed
  76through command line when the module is loaded into memory.
  77
  78The driver relies on the Video4Linux, USB and I2C core modules. It has been
  79designed to run properly on SMP systems as well. An additional module,
  80"ovcamchip", is mandatory; it provides support for some OmniVision image
  81sensors connected to the W996[87]CF chips; if found in the system, the module
  82will be automatically loaded by default (provided that the kernel has been
  83compiled with the automatic module loading option).
  84
  85
  865. Supported devices
  87====================
  88At 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
 100If you know any other W996[87]CF or OV681 based cameras, please contact me.
 101
 102The list above does not imply that all those devices work with this driver: up
 103until now only webcams that have an image sensor supported by the "ovcamchip"
 104module work. Kernel messages will always tell you whether this is case.
 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
 1146. Module dependencies
 115======================
 116For it to work properly, the driver needs kernel support for Video4Linux, USB
 117and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
 118actually using any external "ovcamchip" module, given that the W996[87]CF
 119driver depends on the version of the module present in the official kernels.
 120
 121The following options of the kernel configuration file must be enabled and
 122corresponding modules must be compiled:
 123
 124        # Multimedia devices
 125        #
 126        CONFIG_VIDEO_DEV=m
 127
 128        # I2C support
 129        #
 130        CONFIG_I2C=m
 131
 132The 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
 142In addition, depending on the hardware being used, only one of the modules
 143below 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
 151And finally:
 152
 153        # USB Multimedia devices
 154        #
 155        CONFIG_USB_W9968CF=m
 156
 157
 1587. Module loading
 159=================
 160To use the driver, it is necessary to load the "w9968cf" module into memory
 161after every other module required.
 162
 163Loading 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
 170At this point the pertinent devices should be recognized: "dmesg" can be used
 171to analyze kernel messages:
 172
 173        [user@localhost home]$ dmesg
 174
 175There are a lot of parameters the module can use to change the default
 176settings for each device. To list every possible parameter with a brief
 177explanation 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
 1838. Module parameters
 184====================
 185Module parameters are listed below:
 186-------------------------------------------------------------------------------
 187Name:            ovmod_load
 188Type:            bool
 189Syntax:          <0|1>
 190Description:     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.
 195Default:         1
 196-------------------------------------------------------------------------------
 197Name:           simcams
 198Type:           int
 199Syntax:         <n>
 200Description:    Number of cameras allowed to stream simultaneously.
 201                n may vary from 0 to 32.
 202Default:        32
 203-------------------------------------------------------------------------------
 204Name:           video_nr
 205Type:           int array (min = 0, max = 32)
 206Syntax:         <-1|n[,...]>
 207Description:    Specify V4L minor mode number.
 208                -1 = use next available
 209                 n = use minor number n
 210                You can specify up to 32 cameras this way.
 211                For example:
 212                video_nr=-1,2,-1 would assign minor number 2 to the second
 213                recognized camera and use auto for the first one and for every
 214                other camera.
 215Default:        -1
 216-------------------------------------------------------------------------------
 217Name:           packet_size
 218Type:           int array (min = 0, max = 32)
 219Syntax:         <n[,...]>
 220Description:    Specify the maximum data payload size in bytes for alternate
 221                settings, for each device. n is scaled between 63 and 1023.
 222Default:        1023
 223-------------------------------------------------------------------------------
 224Name:           max_buffers
 225Type:           int array (min = 0, max = 32)
 226Syntax:         <n[,...]>
 227Description:    For advanced users.
 228                Specify the maximum number of video frame buffers to allocate
 229                for each device, from 2 to 32.
 230Default:        2
 231-------------------------------------------------------------------------------
 232Name:           double_buffer
 233Type:           bool array (min = 0, max = 32)
 234Syntax:         <0|1[,...]>
 235Description:    Hardware double buffering: 0 disabled, 1 enabled.
 236                It should be enabled if you want smooth video output: if you
 237                obtain out of sync. video, disable it, or try to
 238                decrease the 'clockdiv' module parameter value.
 239Default:        1 for every device.
 240-------------------------------------------------------------------------------
 241Name:           clamping
 242Type:           bool array (min = 0, max = 32)
 243Syntax:         <0|1[,...]>
 244Description:    Video data clamping: 0 disabled, 1 enabled.
 245Default:        0 for every device.
 246-------------------------------------------------------------------------------
 247Name:           filter_type
 248Type:           int array (min = 0, max = 32)
 249Syntax:         <0|1|2[,...]>
 250Description:    Video filter type.
 251                0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter.
 252                The filter is used to reduce noise and aliasing artifacts
 253                produced by the CCD or CMOS image sensor.
 254Default:        0 for every device.
 255-------------------------------------------------------------------------------
 256Name:           largeview
 257Type:           bool array (min = 0, max = 32)
 258Syntax:         <0|1[,...]>
 259Description:    Large view: 0 disabled, 1 enabled.
 260Default:        1 for every device.
 261-------------------------------------------------------------------------------
 262Name:           upscaling
 263Type:           bool array (min = 0, max = 32)
 264Syntax:         <0|1[,...]>
 265Description:    Software scaling (for non-compressed video only):
 266                0 disabled, 1 enabled.
 267                Disable it if you have a slow CPU or you don't have enough
 268                memory.
 269Default:        0 for every device.
 270Note:           If 'w9968cf-vpp' is not present, this parameter is set to 0.
 271-------------------------------------------------------------------------------
 272Name:           decompression
 273Type:           int array (min = 0, max = 32)
 274Syntax:         <0|1|2[,...]>
 275Description:    Software video decompression:
 276                0 = disables decompression
 277                    (doesn't allow formats needing decompression).
 278                1 = forces decompression
 279                    (allows formats needing decompression only).
 280                2 = allows any permitted formats.
 281                Formats supporting (de)compressed video are YUV422P and
 282                YUV420P/YUV420 in any resolutions where width and height are
 283                multiples of 16.
 284Default:        2 for every device.
 285Note:           If 'w9968cf-vpp' is not present, forcing decompression is not
 286                allowed; in this case this parameter is set to 2.
 287-------------------------------------------------------------------------------
 288Name:           force_palette
 289Type:           int array (min = 0, max = 32)
 290Syntax:         <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
 291Description:    Force picture palette.
 292                In order:
 293                 0 = Off - allows any of the following formats:
 294                 9 = UYVY    16 bpp - Original video, compression disabled
 295                10 = YUV420  12 bpp - Original video, compression enabled
 296                13 = YUV422P 16 bpp - Original video, compression enabled
 297                15 = YUV420P 12 bpp - Original video, compression enabled
 298                 8 = YUVY    16 bpp - Software conversion from UYVY
 299                 7 = YUV422  16 bpp - Software conversion from UYVY
 300                 1 = GREY     8 bpp - Software conversion from UYVY
 301                 6 = RGB555  16 bpp - Software conversion from UYVY
 302                 3 = RGB565  16 bpp - Software conversion from UYVY
 303                 4 = RGB24   24 bpp - Software conversion from UYVY
 304                 5 = RGB32   32 bpp - Software conversion from UYVY
 305                When not 0, this parameter will override 'decompression'.
 306Default:        0 for every device. Initial palette is 9 (UYVY).
 307Note:           If 'w9968cf-vpp' is not present, this parameter is set to 9.
 308-------------------------------------------------------------------------------
 309Name:           force_rgb
 310Type:           bool array (min = 0, max = 32)
 311Syntax:         <0|1[,...]>
 312Description:    Read RGB video data instead of BGR:
 313                1 = use RGB component ordering.
 314                0 = use BGR component ordering.
 315                This parameter has effect when using RGBX palettes only.
 316Default:        0 for every device.
 317-------------------------------------------------------------------------------
 318Name:           autobright
 319Type:           bool array (min = 0, max = 32)
 320Syntax:         <0|1[,...]>
 321Description:    Image sensor automatically changes brightness:
 322                0 = no, 1 = yes
 323Default:        0 for every device.
 324-------------------------------------------------------------------------------
 325Name:           autoexp
 326Type:           bool array (min = 0, max = 32)
 327Syntax:         <0|1[,...]>
 328Description:    Image sensor automatically changes exposure:
 329                0 = no, 1 = yes
 330Default:        1 for every device.
 331-------------------------------------------------------------------------------
 332Name:           lightfreq
 333Type:           int array (min = 0, max = 32)
 334Syntax:         <50|60[,...]>
 335Description:    Light frequency in Hz:
 336                50 for European and Asian lighting, 60 for American lighting.
 337Default:        50 for every device.
 338-------------------------------------------------------------------------------
 339Name:           bandingfilter
 340Type:           bool array (min = 0, max = 32)
 341Syntax:         <0|1[,...]>
 342Description:    Banding filter to reduce effects of fluorescent
 343                lighting:
 344                0 disabled, 1 enabled.
 345                This filter tries to reduce the pattern of horizontal
 346                light/dark bands caused by some (usually fluorescent) lighting.
 347Default:        0 for every device.
 348-------------------------------------------------------------------------------
 349Name:           clockdiv
 350Type:           int array (min = 0, max = 32)
 351Syntax:         <-1|n[,...]>
 352Description:    Force pixel clock divisor to a specific value (for experts):
 353                n may vary from 0 to 127.
 354                -1 for automatic value.
 355                See also the 'double_buffer' module parameter.
 356Default:        -1 for every device.
 357-------------------------------------------------------------------------------
 358Name:           backlight
 359Type:           bool array (min = 0, max = 32)
 360Syntax:         <0|1[,...]>
 361Description:    Objects are lit from behind:
 362                0 = no, 1 = yes
 363Default:        0 for every device.
 364-------------------------------------------------------------------------------
 365Name:           mirror
 366Type:           bool array (min = 0, max = 32)
 367Syntax:         <0|1[,...]>
 368Description:    Reverse image horizontally:
 369                0 = no, 1 = yes
 370Default:        0 for every device.
 371-------------------------------------------------------------------------------
 372Name:           monochrome
 373Type:           bool array (min = 0, max = 32)
 374Syntax:         <0|1[,...]>
 375Description:    The image sensor is monochrome:
 376                0 = no, 1 = yes
 377Default:        0 for every device.
 378-------------------------------------------------------------------------------
 379Name:           brightness
 380Type:           long array (min = 0, max = 32)
 381Syntax:         <n[,...]>
 382Description:    Set picture brightness (0-65535).
 383                This parameter has no effect if 'autobright' is enabled.
 384Default:        31000 for every device.
 385-------------------------------------------------------------------------------
 386Name:           hue
 387Type:           long array (min = 0, max = 32)
 388Syntax:         <n[,...]>
 389Description:    Set picture hue (0-65535).
 390Default:        32768 for every device.
 391-------------------------------------------------------------------------------
 392Name:           colour
 393Type:           long array (min = 0, max = 32)
 394Syntax:         <n[,...]>
 395Description:    Set picture saturation (0-65535).
 396Default:        32768 for every device.
 397-------------------------------------------------------------------------------
 398Name:           contrast
 399Type:           long array (min = 0, max = 32)
 400Syntax:         <n[,...]>
 401Description:    Set picture contrast (0-65535).
 402Default:        50000 for every device.
 403-------------------------------------------------------------------------------
 404Name:           whiteness
 405Type:           long array (min = 0, max = 32)
 406Syntax:         <n[,...]>
 407Description:    Set picture whiteness (0-65535).
 408Default:        32768 for every device.
 409-------------------------------------------------------------------------------
 410Name:           debug
 411Type:           int
 412Syntax:         <n>
 413Description:    Debugging information level, from 0 to 6:
 414                0 = none (use carefully)
 415                1 = critical errors
 416                2 = significant information
 417                3 = configuration or general messages
 418                4 = warnings
 419                5 = called functions
 420                6 = function internals
 421                Level 5 and 6 are useful for testing only, when only one
 422                device is used.
 423Default:        2
 424-------------------------------------------------------------------------------
 425Name:           specific_debug
 426Type:           bool
 427Syntax:         <0|1>
 428Description:    Enable or disable specific debugging messages:
 429                0 = print messages concerning every level <= 'debug' level.
 430                1 = print messages concerning the level indicated by 'debug'.
 431Default:        0
 432-------------------------------------------------------------------------------
 433
 434
 4359. Contact information
 436======================
 437I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
 438
 439I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
 440My public 1024-bit key should be available at your keyserver; the fingerprint
 441is: '88E8 F32F 7244 68BA 3958  5D40 99DA 5D2A FCE6 35A4'.
 442
 443
 44410. Credits
 445==========
 446The development would not have proceed much further without having looked at
 447the source code of other drivers and without the help of several persons; in
 448particular:
 449
 450- the I2C interface to kernel and high-level image sensor control routines have
 451  been taken from the OV511 driver by Mark McClelland;
 452
 453- memory management code has been copied from the bttv driver by Ralph Metzler,
 454  Marcus Metzler and Gerd Knorr;
 455
 456- the low-level I2C read function has been written by Frederic Jouault;
 457
 458- the low-level I2C fast write function has been written by Piotr Czerczak.
 459
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.