Subversion Repositories or1k

                   W996[87]CF JPEG USB Dual Mode Camera Chip

                        Linux 2.4 driver (basic version)

                   =========================================

                               - Documentation -

Index

=====

1. Copyright

2. License

3. Overview

4. Supported devices

5. Module dependencies

6. Module loading

7. Module paramaters

8. Credits

1. Copyright

============

Copyright (C) 2002 2003 by Luca Risolia 

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 full-featured 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://go.lamarinapunto.com/

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.

The driver relies on the Video4Linux, USB and I2C core modules of the official

Linux kernels, 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 "ovcamchip" module is part of the OV511 driver, version 2.27, which can be

downloaded from internet:

http://alpha.dyndns.org/ov511/

To know how to compile it, read the documentation included in the OV511

package.

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 the author's homepage on

this module: http://alpha.dyndns.org/ov511/

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.

5. Module dependencies

======================

The driver needs kernel support for Video4Linux, USB and I2C, and a third-party

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, only 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

And finally:

        # USB Multimedia devices

        #

        CONFIG_USB_W9968CF=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

The last module we need is "ovcamchip.o". To obtain it, you have to download

the OV511, version 2.27 - don't use other versions - and compile it according

to its documentation.

The package is available at http://alpha.dyndns.org/ov511/ .

6. Module loading

=================

To use the driver, it is necessary to load the "w9968cf" module into memory

after every other module required: for the 2.4 series of the kernel, 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:           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 '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:         

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:         

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:         

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

                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:           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):

                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:

                    (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, 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:

                 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:           bool array (min = 0, max = 32)

Syntax:         <0|1[,...]>

Description:    Read RGB video data instead of BGR:

                1 = use RGB 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:    CMOS sensor automatically changes brightness:

Default:        0 for every device.

-------------------------------------------------------------------------------

Name:           autoexp

Type:           bool array (min = 0, max = 32)

Syntax:         <0|1[,...]>

Description:    CMOS sensor automatically changes exposure:

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:

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

Default:        -1 for every device.

-------------------------------------------------------------------------------

Name:           backlight

Type:           bool array (min = 0, max = 32)

Syntax:         <0|1[,...]>

Description:    Objects are lit from behind:

Default:        0 for every device.

-------------------------------------------------------------------------------

Name:           mirror

Type:           bool array (min = 0, max = 32)

Syntax:         <0|1[,...]>

Description:    Reverse image horizontally:

Default:        0 for every device.

-------------------------------------------------------------------------------

Name:           monochrome

Type:           bool array (min = 0, max = 32)

Syntax:         <0|1[,...]>

Description:    The CMOS sensor is monochrome:

Default:        0 for every device.

-------------------------------------------------------------------------------

Name:           brightness

Type:           long array (min = 0, max = 32)

Syntax:         

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:         

Description:    Set picture hue (0-65535).

Default:        32768 for every device.

-------------------------------------------------------------------------------

Name:           colour

Type:           long array (min = 0, max = 32)

Syntax:         

Description:    Set picture saturation (0-65535).

Default:        32768 for every device.

-------------------------------------------------------------------------------

Name:           contrast

Type:           long array (min = 0, max = 32)

Syntax:         

Description:    Set picture contrast (0-65535).

Default:        50000 for every device.

-------------------------------------------------------------------------------

Name:           whiteness

Type:           long array (min = 0, max = 32)

Syntax:         

Description:    Set picture whiteness (0-65535).

Default:        32768 for every device.

-------------------------------------------------------------------------------

Name:           debug

Type:           int

Syntax:         

Description:    Debugging information level, from 0 to 6:

                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:           bool

Syntax:         <0|1>

Description:    Enable or disable specific debugging messages:

                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 Frederic Jouault;

- the low-level I2C fast write function has been written by Piotr Czerczak.