1da177e4c3
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
481 lines
20 KiB
Text
481 lines
20 KiB
Text
|
|
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.
|