patch-2.4.23 linux-2.4.23/Documentation/usb/w9968cf.txt
Next file: linux-2.4.23/Documentation/video4linux/bttv/CARDLIST
Previous file: linux-2.4.23/Documentation/usb/usb-serial.txt
Back to the patch index
Back to the overall index
- Lines: 487
- Date:
2003-11-28 10:26:19.000000000 -0800
- Orig file:
linux-2.4.22/Documentation/usb/w9968cf.txt
- Orig date:
1969-12-31 16:00:00.000000000 -0800
diff -urN linux-2.4.22/Documentation/usb/w9968cf.txt linux-2.4.23/Documentation/usb/w9968cf.txt
@@ -0,0 +1,486 @@
+
+ W996[87]CF JPEG USB Dual Mode Camera Chip driver for Linux 2.4
+ ==============================================================
+
+ - Documentation -
+
+
+Index
+=====
+1. Copyright
+2. License
+3. Overview
+4. Supported devices
+5. Kernel configuration and third-part module compilation
+6. Module loading
+7. Module paramaters
+8. Credits
+
+
+1. Copyright
+============
+Copyright (C) 2002 2003 by Luca Risolia <luca_ing@libero.it>
+
+
+2. 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.
+
+
+3. Overview
+===========
+This driver supports the video streaming capabilities of the devices mounting
+Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips, when they
+are being commanded by USB.
+
+The driver relies on the Video4Linux, USB and I2C core modules of the Linux
+kernel, version 2.4.19 or greater, and is not compatible in any way with
+previous versions. It has been designed to run properly on SMP systems
+as well. At the moment, an additional module, "ovcamchip", is mandatory; it
+provides support for some OmniVision CMOS sensors connected to the W996[87]CF
+chips.
+
+The driver is split 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 (these routines can't be included
+into official kernels). 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.
+
+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 paramaters can be passed
+through command line when the module is loaded into memory.
+
+It is recommended to install the latest and full featured version of the
+W996[87]CF driver, which can be found at:
+http://go.lamarinapunto.com/
+
+The "ovcamchip" module is part of the OV511 driver, version 2.25, which can be
+downloaded from internet:
+http://alpha.dyndns.org/ov511/
+To know how to patch, compile and load it, read the "Kernel configuration"
+paragraph.
+
+
+4. Supported devices
+====================
+At the moment, known W996[87]CF based devices are:
+- Aroma Digi Pen ADG-5000 Refurbished
+- AVerTV USB
+- Creative Labs Video Blaster WebCam Go
+- Creative Labs Video Blaster WebCam Go Plus
+- Die Lebon LDC-D35A Digital Kamera
+- Ezonics EZ-802 EZMega Cam
+- OPCOM Digi Pen VGA Dual Mode Pen Camera
+
+If you know any other W996[87]CF 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 a CMOS sensor supported by the "ovcamchip"
+module work.
+For a list of supported CMOS sensors, please visit the module author homepage:
+http://alpha.dyndns.org/ov511/
+
+Possible external microcontrollers of those webcams are not supported: this
+means that still images can't 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.
+
+
+5. Kernel configuration and third-part module compilation
+=========================================================
+As noted above, kernel 2.4.19 is the minimum for this driver; for it to work
+properly, the driver needs kernel support for Video4Linux, USB and I2C, and a
+third-part module for the CMOS sensor.
+
+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.
+
+ # USB support
+ #
+ CONFIG_USB=m
+
+In addition, depending on the hardware being used, just one of the modules
+below is necessary:
+
+ # USB Host Controller Drivers
+ #
+ CONFIG_USB_EHCI_HCD=m
+ CONFIG_USB_UHCI=m
+ CONFIG_USB_UHCI_ALT=m
+ CONFIG_USB_OHCI=m
+
+Also, make sure "Enforce bandwidth allocation" is NOT enabled.
+
+The /proc filesystem can be optionally built into the kernel:
+
+ # File systems
+ #
+ CONFIG_PROC_FS=y
+
+ # Video For Linux
+ #
+ CONFIG_VIDEO_PROC_FS=y
+
+ # USB Multimedia devices
+ #
+ CONFIG_USB_W9968CF=m
+
+The last module we need is "ovcamchip.o". To obtain it, you have to download
+the OV511 driver, version 2.25 - don't use other versions - which is available
+at http://alpha.dyndns.org/ov511/ . Then you have to download the latest
+version of the full featured W996[87]CF driver, which contains a patch for the
+"ovcamchip" module; it is available at http://go.lamarinapunto.com .
+Once you have obtained the packages, decompress, patch and compile the
+"ovcamchip" module. In other words:
+
+ [user@localhost home]$ tar xvzf w9968cf-x.x.tar.gz
+ [user@localhost home]$ tar xvjf ov511-2.25.tar.bz2
+ [user@localhost home]$ cd ov511-2.25
+ [user@localhost ov511-2.25]$ patch -p1 < \
+ /path/to/w9968cf-x.x/ov511-2.25.patch
+ [user@localhost ov511-2.25]$ make
+
+It's worth to note that the full featured version of the W996[87]CF driver
+can also be installed overwriting the one in the kernel; in this case, read the
+documentation included in the package.
+
+If everything went well, the W996[87]CF driver can be immediatly used (see next
+paragraph).
+
+
+6. Module loading
+=================
+To use the driver, it is necessary to load the "w9968cf" module into memory
+after every other module required; they are named, in order: "videodev",
+"usbcore", then "ehci-hcd", "usb-uhci", "uhci", "usb-ohci" (just one), and also
+"i2c-core" and "ovcamchip".
+
+Loading can be done this way, from root:
+
+ [root@localhost home]# modprobe i2c-core
+ [root@localhost ov511-x.xx]# insmod ./ovcamchip.o
+ [root@localhost home]# modprobe w9968cf
+
+At this point the devices should be recognized. There are two ways of verifying
+that the loading process has gone well: the first is to analyze kernel
+messages:
+
+ [user@localhost home]$ dmesg
+
+A second way is to retrieve informations from the entries that have just been
+created in the /proc/video/w9968cf/ directory; this feature works if and only
+if the kernel has been built with the /proc filesystem support.
+As an example, the following command will print the list of registered cameras:
+
+ [user@localhost home]$ cat /proc/video/w9968cf/global
+
+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
+
+
+7. Module paramaters
+====================
+
+Module paramaters are listed below:
+-------------------------------------------------------------------------------
+Name: vppmod_load
+Type: int
+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 'w9968cf-vpp' module adds extra image manipulation
+ capabilities to the 'w9968cf' module,like software up-scaling,
+ colour conversions and video decoding.
+Default: 1
+-------------------------------------------------------------------------------
+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 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: Only 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: int 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 at all, or try to
+ decrease the 'clockdiv' module paramater value.
+Default: 1 for every device.
+-------------------------------------------------------------------------------
+Name: clamping
+Type: int 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 sensor.
+Default: 0 for every device.
+-------------------------------------------------------------------------------
+Name: largeview
+Type: int array (min = 0, max = 32)
+Syntax: <0|1[,...]>
+Description: Large view: 0 disabled, 1 enabled.
+Default: 1 for every device.
+-------------------------------------------------------------------------------
+Name: upscaling
+Type: int 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 loaded, this paramater 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 loaded, this paramater is set to,
+ forcing decompression is not allowed; in this case this
+ paramater 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 paramater will override 'decompression'.
+Default: 0 for every device. Initial palette is 9 (UYVY).
+Note: If 'w9968cf-vpp' is not loaded, this paramater is set to 9.
+-------------------------------------------------------------------------------
+Name: force_rgb
+Type: int 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: long array (min = 0, max = 32)
+Syntax: <0|1[,...]>
+Description: CMOS sensor automatically changes brightness:
+ 0 = no, 1 = yes
+Default: 0 for every device.
+-------------------------------------------------------------------------------
+Name: autoexp
+Type: long array (min = 0, max = 32)
+Syntax: <0|1[,...]>
+Description: CMOS sensor automatically changes exposure:
+ 0 = no, 1 = yes
+Default: 1 for every device.
+-------------------------------------------------------------------------------
+Name: lightfreq
+Type: long 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: long 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: long 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 paramater.
+Default: -1 for every device.
+-------------------------------------------------------------------------------
+Name: backlight
+Type: long 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: long array (min = 0, max = 32)
+Syntax: <0|1[,...]>
+Description: Reverse image horizontally:
+ 0 = no, 1 = yes
+Default: 0 for every device.
+-------------------------------------------------------------------------------
+Name: sensor_mono
+Type: long array (min = 0, max = 32)
+Syntax: <0|1[,...]>
+Description: The CMOS 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 (be cautious)
+ 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 just one
+ device is used.
+Default: 2
+-------------------------------------------------------------------------------
+Name: specific_debug
+Type: int
+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
+-------------------------------------------------------------------------------
+
+
+8. 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 CMOS 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 Frédéric Jouault, who
+ also gave me commented logs about sniffed USB traffic taken from another
+ driver for another system;
+
+- the low-level I2C fast write function has been written by Piotr Czerczak;
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen (who was at: slshen@lbl.gov)