1 files changed, 481 insertions, 0 deletions

diff --git a/Documentation/usb/w9968cf.txt b/Documentation/usb/w9968cf.txt
new file mode 100644
index 000000000000..18a47738d56c
--- /dev/null
+++ b/Documentation/usb/w9968cf.txt
@@ -0,0 +1,481 @@
+
+                   W996[87]CF JPEG USB Dual Mode Camera Chip 
+                     Driver for Linux 2.6 (basic version)
+                   =========================================
+
+                               - Documentation -
+
+
+Index
+=====
+1.  Copyright
+2.  Disclaimer
+3.  License
+4.  Overview
+5.  Supported devices
+6.  Module dependencies
+7.  Module loading
+8.  Module paramaters
+9.  Contact information
+10. Credits
+
+
+1. Copyright
+============
+Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
+
+
+2. Disclaimer
+=============
+Winbond is a trademark of Winbond Electronics Corporation.
+This software is not sponsored or developed by Winbond.
+
+
+3. License
+==========
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+
+4. Overview
+===========
+This driver supports the video streaming capabilities of the devices mounting
+Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
+based cameras should be supported as well.
+
+The driver is divided into two modules: the basic one, "w9968cf", is needed for
+the supported devices to work; the second one, "w9968cf-vpp", is an optional
+module, which provides some useful video post-processing functions like video
+decoding, up-scaling and colour conversions. Once the driver is installed,
+every time an application tries to open a recognized device, "w9968cf" checks
+the presence of the "w9968cf-vpp" module and loads it automatically by default.
+
+Please keep in mind that official kernels do not include the second module for
+performance purposes. However it is always recommended to download and install
+the latest and complete release of the driver, replacing the existing one, if
+present: it will be still even possible not to load the "w9968cf-vpp" module at
+all, if you ever want to. Another important missing feature of the version in
+the official Linux 2.4 kernels is the writeable /proc filesystem interface.
+
+The latest and full-featured version of the W996[87]CF driver can be found at:
+http://www.linux-projects.org. Please refer to the documentation included in
+that package, if you are going to use it.
+
+Up to 32 cameras can be handled at the same time. They can be connected and
+disconnected from the host many times without turning off the computer, if
+your system supports the hotplug facility.
+
+To change the default settings for each camera, many parameters can be passed
+through command line when the module is loaded into memory.
+
+The driver relies on the Video4Linux, USB and I2C core modules. It has been
+designed to run properly on SMP systems as well. An additional module,
+"ovcamchip", is mandatory; it provides support for some OmniVision image
+sensors connected to the W996[87]CF chips; if found in the system, the module
+will be automatically loaded by default (provided that the kernel has been
+compiled with the automatic module loading option).
+
+
+5. Supported devices
+====================
+At the moment, known W996[87]CF and OV681 based devices are:
+- Aroma Digi Pen VGA Dual Mode ADG-5000 (unknown image sensor)
+- AVerMedia AVerTV USB (SAA7111A, Philips FI1216Mk2 tuner, PT2313L audio chip)
+- Creative Labs Video Blaster WebCam Go (OmniVision OV7610 sensor)
+- Creative Labs Video Blaster WebCam Go Plus (OmniVision OV7620 sensor)
+- Lebon LDC-035A (unknown image sensor)
+- Ezonics EZ-802 EZMega Cam (OmniVision OV8610C sensor)
+- OmniVision OV8610-EDE (OmniVision OV8610 sensor)
+- OPCOM Digi Pen VGA Dual Mode Pen Camera (unknown image sensor)
+- Pretec Digi Pen-II (OmniVision OV7620 sensor)
+- Pretec DigiPen-480 (OmniVision OV8610 sensor)
+
+If you know any other W996[87]CF or OV681 based cameras, please contact me.
+
+The list above does not imply that all those devices work with this driver: up
+until now only webcams that have an image sensor supported by the "ovcamchip"
+module work. Kernel messages will always tell you whether this is case.
+
+Possible external microcontrollers of those webcams are not supported: this
+means that still images cannot be downloaded from the device memory.
+
+Furthermore, it's worth to note that I was only able to run tests on my
+"Creative Labs Video Blaster WebCam Go". Donations of other models, for
+additional testing and full support, would be much appreciated.
+
+
+6. Module dependencies
+======================
+For it to work properly, the driver needs kernel support for Video4Linux, USB
+and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
+actually using any external "ovcamchip" module, given that the W996[87]CF 
+driver depends on the version of the module present in the official kernels.
+
+The following options of the kernel configuration file must be enabled and
+corresponding modules must be compiled:
+
+        # Multimedia devices
+        #
+        CONFIG_VIDEO_DEV=m
+
+        # I2C support
+        #
+        CONFIG_I2C=m
+
+The I2C core module can be compiled statically in the kernel as well.
+
+        # OmniVision Camera Chip support
+        #
+        CONFIG_VIDEO_OVCAMCHIP=m
+
+        # USB support
+        #
+        CONFIG_USB=m
+
+In addition, depending on the hardware being used, only one of the modules
+below is necessary:
+
+        # USB Host Controller Drivers
+        #
+        CONFIG_USB_EHCI_HCD=m
+        CONFIG_USB_UHCI_HCD=m
+        CONFIG_USB_OHCI_HCD=m
+
+And finally:
+
+        # USB Multimedia devices
+        #
+        CONFIG_USB_W9968CF=m
+
+
+7. Module loading
+=================
+To use the driver, it is necessary to load the "w9968cf" module into memory
+after every other module required.
+
+Loading can be done this way, from root:
+
+        [root@localhost home]# modprobe usbcore
+        [root@localhost home]# modprobe i2c-core
+        [root@localhost home]# modprobe videodev
+        [root@localhost home]# modprobe w9968cf
+
+At this point the pertinent devices should be recognized: "dmesg" can be used
+to analyze kernel messages:
+
+        [user@localhost home]$ dmesg
+
+There are a lot of parameters the module can use to change the default
+settings for each device. To list every possible parameter with a brief
+explanation about them and which syntax to use, it is recommended to run the
+"modinfo" command:
+
+        [root@locahost home]# modinfo w9968cf
+
+
+8. Module parameters
+====================
+Module parameters are listed below:
+-------------------------------------------------------------------------------
+Name:            ovmod_load
+Type:            bool
+Syntax:          <0|1>
+Description:     Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled.
+                 If enabled, 'insmod' searches for the required 'ovcamchip'
+                 module in the system, according to its configuration, and
+                 loads that module automatically. This action is performed as
+                 once soon as the 'w9968cf' module is loaded into memory.
+Default:         1
+Note:            The kernel must be compiled with the CONFIG_KMOD option
+                 enabled for the 'ovcamchip' module to be loaded and for
+                 this parameter to be present.
+-------------------------------------------------------------------------------
+Name:           vppmod_load
+Type:           bool
+Syntax:         <0|1>
+Description:    Automatic 'w9968cf-vpp' module loading: 0 disabled, 1 enabled.
+                If enabled, every time an application attempts to open a
+                camera, 'insmod' searches for the video post-processing module
+                in the system and loads it automatically (if present).
+                The optional 'w9968cf-vpp' module adds extra image manipulation
+                capabilities to the 'w9968cf' module,like software up-scaling,
+                colour conversions and video decompression for very high frame
+                rates.
+Default:        1
+Note:           The kernel must be compiled with the CONFIG_KMOD option
+                enabled for the 'w9968cf-vpp' module to be loaded and for
+                this parameter to be present.
+-------------------------------------------------------------------------------
+Name:           simcams 
+Type:           int 
+Syntax:         <n> 
+Description:    Number of cameras allowed to stream simultaneously.
+                n may vary from 0 to 32.
+Default:        32
+-------------------------------------------------------------------------------
+Name:           video_nr
+Type:           int array (min = 0, max = 32)
+Syntax:         <-1|n[,...]> 
+Description:    Specify V4L minor mode number.
+                -1 = use next available
+                 n = use minor number n
+                You can specify up to 32 cameras this way.
+                For example:
+                video_nr=-1,2,-1 would assign minor number 2 to the second
+                recognized camera and use auto for the first one and for every
+                other camera.
+Default:        -1
+-------------------------------------------------------------------------------
+Name:           packet_size
+Type:           int array (min = 0, max = 32)
+Syntax:         <n[,...]> 
+Description:    Specify the maximum data payload size in bytes for alternate
+                settings, for each device. n is scaled between 63 and 1023.
+Default:        1023
+-------------------------------------------------------------------------------
+Name:           max_buffers
+Type:           int array (min = 0, max = 32)
+Syntax:         <n[,...]>
+Description:    For advanced users.
+                Specify the maximum number of video frame buffers to allocate
+                for each device, from 2 to 32.
+Default:        2
+-------------------------------------------------------------------------------
+Name:           double_buffer
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]> 
+Description:    Hardware double buffering: 0 disabled, 1 enabled.
+                It should be enabled if you want smooth video output: if you
+                obtain out of sync. video, disable it, or try to
+                decrease the 'clockdiv' module parameter value.
+Default:        1 for every device.
+-------------------------------------------------------------------------------
+Name:           clamping
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]> 
+Description:    Video data clamping: 0 disabled, 1 enabled.
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           filter_type
+Type:           int array (min = 0, max = 32)
+Syntax:         <0|1|2[,...]> 
+Description:    Video filter type.
+                0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter.
+                The filter is used to reduce noise and aliasing artifacts
+                produced by the CCD or CMOS image sensor.
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           largeview
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]> 
+Description:    Large view: 0 disabled, 1 enabled.
+Default:        1 for every device.
+-------------------------------------------------------------------------------
+Name:           upscaling
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]> 
+Description:    Software scaling (for non-compressed video only):
+                0 disabled, 1 enabled.
+                Disable it if you have a slow CPU or you don't have enough
+                memory.
+Default:        0 for every device.
+Note:           If 'w9968cf-vpp' is not present, this parameter is set to 0.
+-------------------------------------------------------------------------------
+Name:           decompression
+Type:           int array (min = 0, max = 32)
+Syntax:         <0|1|2[,...]>
+Description:    Software video decompression:
+                0 = disables decompression
+                    (doesn't allow formats needing decompression).
+                1 = forces decompression
+                    (allows formats needing decompression only).
+                2 = allows any permitted formats.
+                Formats supporting (de)compressed video are YUV422P and
+                YUV420P/YUV420 in any resolutions where width and height are
+                multiples of 16.
+Default:        2 for every device.
+Note:           If 'w9968cf-vpp' is not present, forcing decompression is not
+                allowed; in this case this parameter is set to 2.
+-------------------------------------------------------------------------------
+Name:           force_palette
+Type:           int array (min = 0, max = 32)
+Syntax:         <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
+Description:    Force picture palette.
+                In order:
+                 0 = Off - allows any of the following formats:
+                 9 = UYVY    16 bpp - Original video, compression disabled
+                10 = YUV420  12 bpp - Original video, compression enabled
+                13 = YUV422P 16 bpp - Original video, compression enabled
+                15 = YUV420P 12 bpp - Original video, compression enabled
+                 8 = YUVY    16 bpp - Software conversion from UYVY
+                 7 = YUV422  16 bpp - Software conversion from UYVY
+                 1 = GREY     8 bpp - Software conversion from UYVY
+                 6 = RGB555  16 bpp - Software conversion from UYVY
+                 3 = RGB565  16 bpp - Software conversion from UYVY
+                 4 = RGB24   24 bpp - Software conversion from UYVY
+                 5 = RGB32   32 bpp - Software conversion from UYVY
+                When not 0, this parameter will override 'decompression'.
+Default:        0 for every device. Initial palette is 9 (UYVY).
+Note:           If 'w9968cf-vpp' is not present, this parameter is set to 9.
+-------------------------------------------------------------------------------
+Name:           force_rgb
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]>
+Description:    Read RGB video data instead of BGR:
+                1 = use RGB component ordering.
+                0 = use BGR component ordering.
+                This parameter has effect when using RGBX palettes only.
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           autobright
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]>
+Description:    Image sensor automatically changes brightness:
+                0 = no, 1 = yes
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           autoexp
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]>
+Description:    Image sensor automatically changes exposure:
+                0 = no, 1 = yes
+Default:        1 for every device.
+-------------------------------------------------------------------------------
+Name:           lightfreq
+Type:           int array (min = 0, max = 32)
+Syntax:         <50|60[,...]>
+Description:    Light frequency in Hz:
+                50 for European and Asian lighting, 60 for American lighting.
+Default:        50 for every device.
+-------------------------------------------------------------------------------
+Name:           bandingfilter
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]> 
+Description:    Banding filter to reduce effects of fluorescent 
+                lighting:
+                0 disabled, 1 enabled.
+                This filter tries to reduce the pattern of horizontal
+                light/dark bands caused by some (usually fluorescent) lighting.
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           clockdiv
+Type:           int array (min = 0, max = 32)
+Syntax:         <-1|n[,...]>
+Description:    Force pixel clock divisor to a specific value (for experts):
+                n may vary from 0 to 127.
+                -1 for automatic value.
+                See also the 'double_buffer' module parameter.
+Default:        -1 for every device.
+-------------------------------------------------------------------------------
+Name:           backlight
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]>
+Description:    Objects are lit from behind:
+                0 = no, 1 = yes
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           mirror
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]>
+Description:    Reverse image horizontally:
+                0 = no, 1 = yes
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           monochrome
+Type:           bool array (min = 0, max = 32)
+Syntax:         <0|1[,...]> 
+Description:    The image sensor is monochrome:
+                0 = no, 1 = yes
+Default:        0 for every device.
+-------------------------------------------------------------------------------
+Name:           brightness
+Type:           long array (min = 0, max = 32)
+Syntax:         <n[,...]>
+Description:    Set picture brightness (0-65535).
+                This parameter has no effect if 'autobright' is enabled.
+Default:        31000 for every device.
+-------------------------------------------------------------------------------
+Name:           hue
+Type:           long array (min = 0, max = 32)
+Syntax:         <n[,...]>
+Description:    Set picture hue (0-65535).
+Default:        32768 for every device.
+-------------------------------------------------------------------------------
+Name:           colour
+Type:           long array (min = 0, max = 32)
+Syntax:         <n[,...]>
+Description:    Set picture saturation (0-65535).
+Default:        32768 for every device.
+-------------------------------------------------------------------------------
+Name:           contrast
+Type:           long array (min = 0, max = 32)
+Syntax:         <n[,...]> 
+Description:    Set picture contrast (0-65535).
+Default:        50000 for every device.
+-------------------------------------------------------------------------------
+Name:           whiteness
+Type:           long array (min = 0, max = 32)
+Syntax:         <n[,...]> 
+Description:    Set picture whiteness (0-65535).
+Default:        32768 for every device.
+-------------------------------------------------------------------------------
+Name:           debug
+Type:           int
+Syntax:         <n> 
+Description:    Debugging information level, from 0 to 6:
+                0 = none (use carefully)
+                1 = critical errors
+                2 = significant informations
+                3 = configuration or general messages
+                4 = warnings
+                5 = called functions
+                6 = function internals
+                Level 5 and 6 are useful for testing only, when only one
+                device is used.
+Default:        2
+-------------------------------------------------------------------------------
+Name:           specific_debug
+Type:           bool
+Syntax:         <0|1>
+Description:    Enable or disable specific debugging messages:
+                0 = print messages concerning every level <= 'debug' level.
+                1 = print messages concerning the level indicated by 'debug'.
+Default:        0
+-------------------------------------------------------------------------------
+
+
+9. Contact information
+======================
+I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
+
+I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
+My public 1024-bit key should be available at your keyserver; the fingerprint
+is: '88E8 F32F 7244 68BA 3958  5D40 99DA 5D2A FCE6 35A4'.
+
+
+10. Credits
+==========
+The development would not have proceed much further without having looked at
+the source code of other drivers and without the help of several persons; in
+particular:
+
+- the I2C interface to kernel and high-level image sensor control routines have
+  been taken from the OV511 driver by Mark McClelland;
+
+- memory management code has been copied from the bttv driver by Ralph Metzler,
+  Marcus Metzler and Gerd Knorr;
+
+- the low-level I2C read function has been written by Frederic Jouault;
+
+- the low-level I2C fast write function has been written by Piotr Czerczak.