| |
| 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. |