[PATCH] Updates for W99[87]CF and new SN9C10[12] driver

This single patch contains some updates and cleanups for
the W996[87]CF driver and a new experimental V4L2 driver
for SONiX SN9C10[12] PC Camera Controllers connected to various
image sensors. I have not divided the patch in two logical
sub-patches becouse of two independent changes in one common
file, KConfigure.

More informations about the SN9C10[12] can be found below in the
documentation. The driver is marked as "EXPERIMENTAL", meaning
that there are no known bugs, but further testing is necessary
before considering it stable. This the first driver using the new
SBGGR8 video format, which has been recently added to the mainline
kernel, so there are no available user application at the moment:
this is one more reason why it should be in the kernel now.

Changes in W996[87]CF:
- remove w9968cf_externaldef.h now that ovcamchip.h is in the kernel;
- mark user pointers with __user in a cleaner way to avoid sparse
  warnings;
- use appropriate exclusive wait macro during open();
- replace info(), err(), warn() with dev_info(), dev_err(), dev_warn(),
  pr_debug(), pr_info();
- replace usb_unlink_urb() + wait_for_completion() with usb_kill_urb();
- fix memory offsets for buffers in the chip to be used with generic
  image sensors;
- 'vppmod_load', 'debug', 'specific_debug' and 'simcams' module
  parameters are now writeable by default;
- fix possible race conditions between disconnect() and open();
- add automatic 'ovcamchip' module loading option with 'ovmod_load'
  module parameter;
- get rid of deprecated intermodule communication routines and use the
  correct module registration/unregistration approach;
- remove period at the end of kernel messages;
- fix several typos;
- use MODULE_VERSION() macro;
- other small internal cleanups;
- documentation updates.

Signed-off-by: Luca Risolia <luca.risolia@studio.unibo.it>
Signed-off-by: Greg Kroah-Hartman <greg@kroah.com>

2 files changed, 346 insertions, 52 deletions

diff --git a/Documentation/usb/sn9c102.txt b/Documentation/usb/sn9c102.txt
new file mode 100644
index 00000000000000..65018c8c992042
--- /dev/null
+++ b/Documentation/usb/sn9c102.txt
@@ -0,0 +1,276 @@
+
+                        SN9C10[12] PC Camera Controllers
+                                Driver for Linux
+                        ================================
+
+                               - Documentation -
+
+
+Index
+=====
+1.  Copyright
+2.  License
+3.  Overview
+4.  Module dependencies
+5.  Module loading
+6.  Module parameters
+7.  Device control through "sysfs"
+8.  Supported devices
+9.  How to add support for new image sensors
+10. Note for V4L2 developers
+11. Contact information
+12. Credits
+
+
+1. Copyright
+============
+Copyright (C) 2004 by Luca Risolia <luca.risolia@studio.unibo.it>
+
+SONiX is a trademark of SONiX Technology Company Limited, inc.
+This driver is not sponsored or developed by SONiX.
+
+
+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 attempts to support the video streaming capabilities of the devices
+mounting the SONiX SN9C101 or SONiX SN9C102 PC Camera Controllers.
+
+- It's worth to note that SONiX has never collaborated with me during the
+development of this project, despite of several requests for enough detailed
+specifications of the register tables, compression engine and video data format
+of the above chips -
+
+Up to 64 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.
+
+The driver relies on the Video4Linux2 and USB core modules. It has been
+designed to run properly on SMP systems as well.
+
+The latest version of the SN9C10[12] driver can be found at the following URL:
+http://go.lamarinapunto.com/
+
+
+4. Module dependencies
+======================
+For it to work properly, the driver needs kernel support for Video4Linux and
+USB.
+
+The following options of the kernel configuration file must be enabled and
+corresponding modules must be compiled:
+
+	# Multimedia devices
+	#
+	CONFIG_VIDEO_DEV=m
+
+	# USB support
+	#
+	CONFIG_USB=m
+
+In addition, depending on the hardware being used, the modules below are
+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_SN9C102=m
+
+
+5. Module loading
+=================
+To use the driver, it is necessary to load the "sn9c102" module into memory
+after every other module required: "videodev", "usbcore" and, depending on
+the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd".
+
+Loading can be done as shown below:
+
+	[root@localhost home]# modprobe usbcore
+	[root@localhost home]# modprobe sn9c102
+
+At this point the devices should be recognized. You can invoke "dmesg" to
+analyze kernel messages and verify that the loading process has gone well:
+
+	[user@localhost home]$ dmesg
+
+
+6. Module parameters
+====================
+Module parameters are listed below:
+-------------------------------------------------------------------------------
+Name:           video_nr
+Type:           int array (min = 0, max = 32)
+Syntax:         <-1|n[,...]> 
+Description:    Specify V4L2 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:           debug
+Type:           int
+Syntax:         <n> 
+Description:    Debugging information level, from 0 to 3:
+                0 = none (use carefully)
+                1 = critical errors
+                2 = significant informations
+                3 = more verbose messages
+                Level 3 is useful for testing only, when just one device
+                is used.
+Default:        2
+-------------------------------------------------------------------------------
+
+
+7. Device control through "sysfs"
+=================================
+It is possible to read and write both the SN9C10[12] and the image sensor
+registers by using the "sysfs" filesystem interface.
+
+Every time a supported device is recognized, read-only files named "redblue"
+and "green" are created in the /sys/class/video4linux/videoX directory. You can
+set the red, blue and green channel's gain by writing the desired value to
+them. The value may range from 0 to 15 for each channel; this means that
+"redblue" accepts 8-bit values, where the low 4 bits are reserved for red and
+the others for blue.
+
+There are other four entries in the directory above for each registered camera:
+"reg", "val", "i2c_reg" and "i2c_val". The first two files control the
+SN9C10[12] bridge, while the other two control the sensor chip. "reg" and
+"i2c_reg" hold the values of the current register index where the following
+reading/writing operations are addressed at through "val" and "i2c_val". Their
+use is not intended for end-users, unless you know what you are doing. Note
+that "i2c_reg" and "i2c_val" won't be created if the sensor does not actually
+support the standard I2C protocol. Also, remember that you must be logged in as
+root before writing to them.
+
+As an example, suppose we were to want to read the value contained in the
+register number 1 of the sensor register table - which usually is the product
+identifier - of the camera registered as "/dev/video0":
+
+	[root@localhost #] cd /sys/class/video4linux/video0
+	[root@localhost #] echo 1 > i2c_reg
+	[root@localhost #] cat i2c_val
+
+Now let's set the green gain's register of the SN9C10[12] chip to 2:
+
+	[root@localhost #] echo 0x11 > reg
+	[root@localhost #] echo 2 > val
+
+Note that the SN9C10[12] always returns 0 when some of its registers are read.
+To avoid race conditions, all the I/O accesses to the files are serialized.
+
+
+8. Supported devices
+====================
+- I won't mention any of the names of the companies as well as their products
+here. They have never collaborated with me, so no advertising -
+
+From the point of view of a driver, what unambiguously identify a device are
+its vendor and product USB identifiers. Below is a list of known identifiers of
+devices mounting the SN9C10[12] PC camera controllers:
+
+Vendor ID  Product ID
+---------  ----------
+0xc45      0x6001
+0xc45      0x6005
+0xc45      0x6009
+0xc45      0x600d
+0xc45      0x6024
+0xc45      0x6025
+0xc45      0x6028
+0xc45      0x6029
+0xc45      0x602a
+0xc45      0x602c
+0xc45      0x8001
+
+The list above does NOT imply that all those devices work with this driver: up
+until now only the ones that mount the following image sensors are supported.
+Kernel messages will always tell you whether this is the case:
+
+Model       Manufacturer
+-----       ------------
+PAS106B     PixArt Imaging Inc.
+TAS5110C1B  Taiwan Advanced Sensor Corporation
+TAS5130D1B  Taiwan Advanced Sensor Corporation
+
+If you think your camera is based on the above hardware and is not actually
+listed in the above table, you may try to add the specific USB VendorID and
+ProductID identifiers to the sn9c102_id_table[] in the file "sn9c102_sensor.h";
+then compile, load the module again and look at the kernel output.
+If this works, please send an email to me reporting the kernel messages, so
+that I will add a new entry in the list of supported devices.
+
+Donations of new models for further testing and support would be much
+appreciated. I won't add official support for hardware that I don't actually
+have.
+
+
+9. How to add support for new image sensors
+===========================================
+It should be easy to write code for new sensors by using the small API that I
+have created for this purpose, which is present in "sn9c102_sensor.h"
+(documentation is included there). As an example, have a look at the code in
+"sn9c102_pas106b.c", which uses the mentioned interface.
+
+At the moment, not yet supported image sensors are: PAS202B (VGA),
+HV7131[D|E1] (VGA), MI03 (VGA), OV7620 (VGA).
+
+
+10. Note for V4L2 developers
+============================
+This driver follows the V4L2 API specifications. In particular, it enforces two
+rules:
+
+1) Exactly one I/O method, either "mmap" or "read", is associated with each
+file descriptor. Once it is selected, the application must close and reopen the
+device to switch to the other I/O method.
+
+2) Previously mapped buffer memory must always be unmapped before calling any
+of the "VIDIOC_S_CROP", "VIDIOC_TRY_FMT" and "VIDIOC_S_FMT" ioctl's. In case,
+the same number of buffers as before will be allocated again to match the size
+of the new video frames, so you have to map them again before any I/O attempts.
+
+
+11. 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 any keyserver; the fingerprint
+is: '88E8 F32F 7244 68BA 3958  5D40 99DA 5D2A FCE6 35A4'.
+
+
+12. Credits
+===========
+I would thank the following persons:
+
+- Stefano Mozzi, who donated 45 EU;
+- Luca Capello for the donation of a webcam;
+- Mizuno Takafumi for the donation of a webcam.
diff --git a/Documentation/usb/w9968cf.txt b/Documentation/usb/w9968cf.txt
index 65775f0676bc88..f52d65e553c9a0 100644
--- a/Documentation/usb/w9968cf.txt
+++ b/Documentation/usb/w9968cf.txt
@@ -23,6 +23,9 @@ Index
 ============
 Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
 
+Winbond is a trademark of Winbond Electronics Corporation.
+This driver is not sponsored or developed by Winbond.
+
 
 2. License
 ==========
@@ -44,8 +47,8 @@ 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. OV681 based cameras should be supported as well.
+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
@@ -58,7 +61,8 @@ 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.
+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/ . Please refer to the documentation included in
@@ -68,38 +72,37 @@ 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
+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 of the official
-Linux kernels. 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.
+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).
 
 
 4. Supported devices
 ====================
 At the moment, known W996[87]CF and OV681 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
+- 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 a CMOS sensor supported by the "ovcamchip"
+until now only webcams that have an image sensor supported by the "ovcamchip"
 module work. 
-For a list of supported CMOS sensors, please visit the author's homepage on
+For a list of supported image sensors, please visit the author's homepage on
 this module: http://alpha.dyndns.org/ov511/
 
 Possible external microcontrollers of those webcams are not supported: this
@@ -112,8 +115,10 @@ additional testing and full support, would be much appreciated.
 
 5. Module dependencies
 ======================
-For it to work properly, the driver needs kernel support for Video4Linux, 
-USB and I2C, and a third-party module for the CMOS sensor.
+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:
@@ -128,6 +133,10 @@ corresponding modules must be compiled:
 
 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
@@ -141,19 +150,12 @@ below is necessary:
 	CONFIG_USB_UHCI_HCD=m
 	CONFIG_USB_OHCI_HCD=m
 
-Also, make sure "Enforce bandwidth allocation" is NOT enabled.
-
 And finally:
 
 	# USB Multimedia devices
 	#
 	CONFIG_USB_W9968CF=m
 
-The last module we need is "ovcamchip.o". To obtain it, you have to download
-the OV511 package, 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
 =================
@@ -164,11 +166,10 @@ Loading can be done this way, from root:
 
 	[root@localhost home]# modprobe usbcore
 	[root@localhost home]# modprobe i2c-core
-	[root@localhost ov511-x.xx]# insmod ./ovcamchip.ko
 	[root@localhost home]# modprobe w9968cf
 
-At this point the devices should be recognized: "dmesg" can be used to analyze
-kernel messages:
+At this point the pertinent devices should be recognized: "dmesg" can be used
+to analyze kernel messages:
 
 	[user@localhost home]$ dmesg
 
@@ -180,9 +181,22 @@ explanation about them and which syntax to use, it is recommended to run the
 	[root@locahost home]# modinfo w9968cf
 
 
-7. Module paramaters
+7. Module parameters
 ====================
-Module paramaters are listed below:
+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
@@ -191,10 +205,14 @@ 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 
+                The optional 'w9968cf-vpp' module adds extra image manipulation
                 capabilities to the 'w9968cf' module,like software up-scaling,
-                colour conversions and video decoding.
+                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 
@@ -237,7 +255,7 @@ 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.
+                decrease the 'clockdiv' module parameter value.
 Default:        1 for every device.
 -------------------------------------------------------------------------------
 Name:           clamping
@@ -252,7 +270,7 @@ 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.
+                produced by the CCD or CMOS image sensor.
 Default:        0 for every device.
 -------------------------------------------------------------------------------
 Name:           largeview
@@ -269,7 +287,7 @@ 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.
+Note:           If 'w9968cf-vpp' is not present, this parameter is set to 0.
 -------------------------------------------------------------------------------
 Name:           decompression
 Type:           int array (min = 0, max = 32)
@@ -284,8 +302,8 @@ Description:    Software video decompression:
                 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.
+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)
@@ -304,9 +322,9 @@ Description:    Force picture palette.
                  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'.
+                When not 0, this parameter 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.
+Note:           If 'w9968cf-vpp' is not present, this parameter is set to 9.
 -------------------------------------------------------------------------------
 Name:           force_rgb
 Type:           bool array (min = 0, max = 32)
@@ -320,14 +338,14 @@ Default:        0 for every device.
 Name:           autobright
 Type:           bool array (min = 0, max = 32)
 Syntax:         <0|1[,...]>
-Description:    CMOS sensor automatically changes brightness:
+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:    CMOS sensor automatically changes exposure:
+Description:    Image sensor automatically changes exposure:
                 0 = no, 1 = yes
 Default:        1 for every device.
 -------------------------------------------------------------------------------
@@ -354,7 +372,7 @@ 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.
+                See also the 'double_buffer' module parameter.
 Default:        -1 for every device.
 -------------------------------------------------------------------------------
 Name:           backlight
@@ -374,7 +392,7 @@ Default:        0 for every device.
 Name:           monochrome
 Type:           bool array (min = 0, max = 32)
 Syntax:         <0|1[,...]> 
-Description:    The CMOS sensor is monochrome:
+Description:    The image sensor is monochrome:
                 0 = no, 1 = yes
 Default:        0 for every device.
 -------------------------------------------------------------------------------
@@ -420,7 +438,7 @@ Description:    Debugging information level, from 0 to 6:
                 4 = warnings
                 5 = called functions
                 6 = function internals
-                Level 5 and 6 are useful for testing only, when just one
+                Level 5 and 6 are useful for testing only, when only one
                 device is used.
 Default:        2
 -------------------------------------------------------------------------------
@@ -449,7 +467,7 @@ 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
+- 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,