README CVS Version: $Id: README,v 1.22 2004/01/10 21:33:30 mxhaard Exp $

What is it?
===========

This is version 0.30 of the spca50x video for linux (v4l) driver, providing
support for webcams and digital cameras based on the spca50x range of chips
manufactured by SunPlus.

Please address all correspondence to <spca50x-devs@lists.sourceforge.net>, or
make use of the bug/support/patch tracking facilities provided by SourceForge,
at <http://sourceforge.net/projects/spca50x/>.


Disclaimer
==========
We believe that this driver will perform correctly in many circumstances.
It is, however, experimental code, running at the kernel level, and may
potentially cause serious data corruption, or worse.

Do not use this driver unless you are prepared for this eventuality.

Use of this driver constitutes an agreement that no-one other than yourself may
be held responsible for any effects caused by the driver, ill or otherwise.


What cameras are supported?
===========================

Currently, the following cameras are supported by this driver:
           
	       Vendor ID  Device ID  Support Summary
               ---------  ---------  ---------------
	{USB_DEVICE (0x0733, 0x0430)},	/* Intel PC Camera Pro */
	{USB_DEVICE (0x0733, 0x0401)},	/* Intel Create and Share */
	{USB_DEVICE (0x99FA, 0x8988)},	/* Grandtec V.cap */
	{USB_DEVICE (0x0733, 0x0402)},	/* ViewQuest M318B */
	{USB_DEVICE (0x0733, 0x0110)},	/* ViewQuest VQ110 */
	{USB_DEVICE (0x040A, 0x0002)},	/* Kodak DVC-325 */
	{USB_DEVICE (0x055f, 0xc420)},	/* Mustek gSmart Mini 2 */
	{USB_DEVICE (0x055f, 0xc520)},	/* Mustek gSmart Mini 3 */
	{USB_DEVICE (0x041E, 0x400A)},	/* Creative PC-CAM 300 */
	{USB_DEVICE (0x084D, 0x0003)},	/* D-Link DSC-350 */
	{USB_DEVICE (0x041E, 0x400B)},	/* Creative PC-CAM 600 */
	{USB_DEVICE (0x8086, 0x0630)},	/* Intel Pocket PC Camera */
	{USB_DEVICE (0x8086, 0x0110)},	/* Intel Easy PC Camera */
	{USB_DEVICE (0x0506, 0x00df)},	/* 3Com HomeConnect Lite */
	{USB_DEVICE (0x040a, 0x0300)},	/* Kodak EZ200 */
	{USB_DEVICE (0x04fc, 0x504b)},	/* Maxell MaxPocket LE 1.3 */
	{USB_DEVICE (0x08ca, 0x2008)},	/* Aiptek Mini PenCam 2 M */
	{USB_DEVICE (0x08ca, 0x0104)},	/* Aiptek PocketDVII 1.3 */
	{USB_DEVICE (0x08ca, 0x2018)},	/* Aiptek Pencam SD 2M */
	{USB_DEVICE (0x04fc, 0x504a)},	/* Aiptek Mini PenCam 1.3 */
	{USB_DEVICE (0x055f, 0xc530)},	/* Mustek Gsmart LCD 3 */
	{USB_DEVICE (0x055f, 0xc650)},	/* Mustek MDC5500Z */
	{USB_DEVICE (0x052b, 0x1513)},	/* Megapix V4 */
	{USB_DEVICE (0x08ca, 0x0103)},	/* Aiptek PocketDV */
	{USB_DEVICE (0x0af9, 0x0010)},	/* Hama USB Sightcam 100 */
	{USB_DEVICE (0x1776, 0x501c)},	/* Arowana 300K CMOS Camera */
	{USB_DEVICE (0x0000, 0x0000)},	/* MystFromOri Unknow Camera */
	{USB_DEVICE (0x08ca, 0x0106)},	/* Aiptek Pocket DV3100+ */
	{USB_DEVICE (0x08ca, 0x2010)},	/* Aiptek PocketCam 3M */
	{USB_DEVICE (0x0458, 0x7004)},	/* Genius VideoCAM Express V2 */
	{USB_DEVICE (0x04fc, 0x0561)},	/* Flexcam 100 */
	{USB_DEVICE (0x055f, 0xc430)},	/* Mustek Gsmart LCD 2 */
	{USB_DEVICE (0x04fc, 0xffff)},	/* Pure DigitalDakota */
	{USB_DEVICE (0xabcd, 0xcdee)},	/* Petcam */
	{USB_DEVICE (0x04a5, 0x3008)},	/* Benq DC 1500 */
	{USB_DEVICE (0x046d, 0x0960)},	/* Logitech Inc. ClickSmart 420 */
	{}			/* Terminating entry */


This list represents those cameras that are specifically supported by the
driver, and should work to some degree 'out of the box'. A full list of the
cameras known to the project maintainers can be found on the project website
(see below for details).


How do I use it?
================

Well, first you need to compile the driver (see below), then you need to make
sure that the v4l infrastructure is set up and then load the driver. After
you've done that, any v4l enabled application, such as gqcam, xawtv,
gnomemeeting, camE etc should work.


Supported kernel versions
=========================
The driver should compile and run successfully against most stable versions of
the official Linux kernel (from <http://www.kernel.org/>), within the range
2.2.18 to 2.4.20 inclusive. Unstable version 2.3 is broken, and unsupported.

Specifically, it has been tested against:
 2.2.18 - 2.2.24 Compiles ok, with some (harmless) warnings.
 2.3.0           USB support broken/missing, so doesn't compile.
 2.3.51          Doesn't compile (incomplete types - USB broken?)
 2.4.0           Compiles ok, with some (harmless) warnings.
 2.4.18 - 2.4.19 Compiles ok, with no warnings.
 2.4.20          Compiles ok, with no warnings. Loads successfully.
 2.4.21pre5      Compiles ok, with no warnings.


Compiling it
============
The driver module can be built without modifying your kernel source tree.

Before trying to compile the driver, ensure that you've configured your
kernel, and updated the dependencies:
'make [config|menuconfig|xconfig]; make dep'.

Make sure, when compiling the driver, you use the same version of compiler as
was used to compile your kernel. Not doing so can create incompatible binaries.

If you wish to compile the driver against a kernel other than the currently
installed one, build the driver with
'make KINCLUDE=/usr/src/linux-<version>/include', or similar.

Please note, the default location for the kernel, according to the driver, is
/usr/src/linux.

To build just the driver, simply use 'make'.
Compiling against the linux kernel 2.4 source tree, there should be no
warnings at all.
If you compile against the linux kernel 2.2 source tree, you may see:

{standard input}: Assembler messages:
{standard input}: Warning: ignoring changed section attributes for .modinfo

This is OK. It's caused by a small bug in the 2.2 series kernel, whereby it
outputs two modinfo sections. It doesn't affect the running of the module,
however.

This version of the driver offers an automatic installation facility.
Use 'make install' to have the driver installed into your kernel modules
directory, which is assumed to be /lib/modules/<version>/kernel/drivers/usb.
<version> is picked up from the currently running kernel, so if that's not
the right place, then don't use 'make install'!


Making sure the usb and v4l stuff is there
==========================================
For the module to function correctly, the video for linux subsystem needs to
be loaded. As root, check the output of lsmod for videodev. If its not there,
do: modprobe videodev.
Also, you need to make sure that the usbcore module is loaded (or compiled
into your kernel) and similarly the module appropriate for your usb controller
(uhci or ohci).


Loading it
==========
If you have compiled the module, but haven't done 'make install' you can load
the module in the top build directory by doing as root: insmod spca50x.o

If you have made install, do as root: modprobe spca50x

There are several parameter that can be passed in:

  bright=25   <-- Set camera initial brightness (25 for greyscale,
                  ~90 for colour)
  contrast=16 <-- Set camera initial contrast (16 for greyscale,
                  ~32-64 for colour)
  dumppix=4   <-- return raw camera data for use with raw.c
  dumppix=6   <-- return greyscale video from the YUV decoder
                  [use with internal CCD]
  debug=<n>   <-- set debug level 
  ccd=0       <-- SPCA505 only. Switch between the internal CCD (zero) and
                  the external video input (non-zero)
  osd=1       <-- Enable on-screen display if kernel patches applied
                  (see below)


Trying a v4l app
================
The canonical app to try is gqcam, but it has some problems. First, you need
to make sure that you switch it to a resolution that the driver and cam are
actually capable of. It supports the resolutions "full", "half" and "quarter"
or somesuch, which equate to 640x480, 320x240, and 160x120. The middle
resolution should be supported by all cameras, so try that. It starts up with
the smallest resolution active, so that might not work. Also, gqcam expects
the r, g, and b values of the data stream in a different order than the rest
of the world, but it provides a switch to change that, which can be found
under preferences. If your picture has a blue tint, that is likely to be the
cause.

You can also try gnomemeeting, or any other v4l program, they should
Just Work (TM).


How about downloading pictures from it, or videos?
==================================================
This driver is a v4l driver, whose scope is only streaming video. Support for
downloading images and movies for a lot of spca50x cameras is provided as part
of the gphoto2 project, which can be found at: <http://www.gphoto.org>.


Limitations and known problems
==============================
Support for some bridges is not complete yet. 
Not all resolutions work. 
The driver as a whole is experimental. 


What to do if your cam doesn't work
==================================
Scenario 1 - bridge not supported yet:
  If your cam sports a sunplus spca5something chip which we do not support
  yet, you are in for some quality entertainment. :) In order to add support
  for your chip we will need snoops of the windows driver in operation. You
  can get these using a tool called usbsnoopy, or SnoopyPro, which is free
  software and can be found here: <http://sourceforge.net/projects/usbsnoop/>.
  Once you have acquired these, send an email to the mailing list at
  <spca50x-devs@lists.sourceforge.net>, detailing where/how people can
  download the snoops (eg. website/ftp/email) and if time permits, we'll take
  a look at them and try to implement support.
  If you are a developer yourself and want to help, we very much appreciate
  your contribution and will be happy to explain and answer questions about
  how the driver works.

Scenario 2 - bridge supported, but your cam isn't detected
  It might just work, but it also might not :). You can try exchanging your
  usb vendor and product id for those of a camera with the same chip in the
  source, or ask one of us to do it for you on the list or on irc. If the cam
  is like the others with the same chip, it might work and your ids can be
  permanently added. If it doesn't, see scenario one for what to do.

Scenario 3 - bridge supported, ids there, but still no luck
  random list of things to check:
    - make sure videodev is there;
    - make sure the usb stuff is working;
    - make sure the usb subsystem detects your cam;
    - check syslog, if the driver claims the device;
    - load the module with debug=4 and check syslog for some extremely verbose
      debug information;
    - write to the list or drop into #spca50x on freenode (IRC) and we'll see
      if we can get you up and running. :)


This is a mighty fine project, how can I learn more about it?
=============================================================
<http://spca50x.sourceforge.net/> (nuff said)


I want to whine regularly, where can I?
=======================================
Please address all support requests to <spca50x-devs@lists.sourceforge.net>,
or use the support/patch/bug tracking features provided by sourceforge on our
project page <http://sourceforge.net/projects/spca50x/>.


Who can I blame?
================
Current maintainer and project lead: Miah Gregory <mace@darksilence.net>

Recent contributions (support for spca504a, spca504b and spca500,spca533 jpeg decoding):
Francois Beerten <feber@users.sourceforge.net>
Miah Gregory <mace@darksilence.net>
Till Adam <till@hubbahubba.de>
Michel Xhaard <mxhaard@users.sourceforge.net>

The jpeg decoder was originally written by Michael Schroeder <mls@suse.de>
and adjusted to our purposes. All bugs are ours, all features his.

Original authors:
Joel Crisp <jcrisp@blueyonder.co.uk>

Credits (quoting Joel):
Thanks to all the authors of the ov511 driver and its ancestors.
Thanks to Darrell Scott for debug assistance and suggestions.
Thanks to Razvan Surdulescu for kicking me back into action.
Thanks to Bill Roehl for traces on the Create and Share (id 0x401). I WILL
            make this work... or die trying...
Thanks to everyone who has tested this driver and given me feedback on it.


A note on Sunplus and our interaction with them so far
======================================================
Several of us have tried, at various times, to obtain information on the
spca50x chips from SunPlus, but have failed, seemingly due to a lack of
interest to cooperate on their part. Therefore, this driver is the result of
reverse engineering the protocols and functionality provided by these chips.
This limits what we can do, and it limits the quality of the driver. We would
much prefer to fully support all the features the chips provide, but without
Sunplus supplying us with the needed specifications and technical
documentation, this is unlikely to happen.

Both the free software community and Sunplus could only benefit from improved
cooperation in the future.


=========================
*** On-Screen Display ***
=========================

There is some functionality for debug purposes which can be enabled by the
compile-time option SPCA50X_ENABLE_OSD. This option displays the current
frame number, along with other data, in the resultant image. To use this, you
need to make some patches to the kernel and re-compile the kernel with the
VGA(VESA) frame buffer on (we don't use the frame buffer, but we need it
compiled in to get the fonts). The options you need are VESA frame buffer,
and 8 pixel fonts, and font VGA 8x8. These are the patches (they export the
methods needed to lookup font tables) :

/drivers/video/fonts.c:
22a23
> #include <linux/module.h>
131a133,135
>
> EXPORT_SYMBOL(fbcon_find_font);
> EXPORT_SYMBOL(fbcon_get_default_font);

/drivers/video/Makefile:
18c18
< 		  cyber2000fb.o fbcon-hga.o
---
> 		  cyber2000fb.o fbcon-hga.o fonts.o

After applying these patches, check /usr/include/linux/linux/autoconf.h and
ensure that the following symbols are defined:

CONFIG_FB 1
CONFIG_FBCON_FONTWIDTH8_ONLY 1 <--- this may not be necessary
CONFIG_FBCON_FONTS 1
CONFIG_FONT_8x8 1

Re-build the kernel from scratch (make clean && make dep && make bzImage).
Once you have installed it and rebooted then you can check for the existence
of fbcon_find_font in the /proc/ksyms file.

You can now use the additional module parameter osd=1 to enable the on-screen
display.


======================================================================
*** Notes on spca505/506 support from the old README ***
=======================================================================

Status:

      * SPCA505-partial support (Intel PC Camera Pro, ID=0x430)
        Initialises the camera and begins streaming colour or greyscale data
        You can take still shots with it, and see moving video.
        Brightness and contrast and some mode switching on external input.
        External input support is stable enough for experimental use.
        Internal brightness/contrast and mode switch coming when I get
        the chance to run and interpret some more traces.
        Experimental brightness and colour on internal CCD (need compile
        flag to enable)

      * SPCA506-started support
        Otherwise untested. Please try only if you are developer and
        prepared to suffer crashes and lost data. I need the vendor
        and product ID's for a camera with this IC - if you have one
        please send me your boot log. The GrandTec V.cap is one AFAIK

      * SPCA50?-started support (Intel Create and Share, ID=0x401)
        Otherwise untested. Please try only if you are developer and
        prepared to suffer crashes and lost data. This one seems to
        be closer to the SPCA501 not the SPCA506. The 0.10 release
        significantly improves support for this device.

I'm releasing in the hope that it is useful to someone, and for other
interested developers.


***********************************************************************
Remember to use
   insmod spca50x.o ccd=0 dumppix=6
for the internal CCD on the SPCA506 (Intel PC Camera Pro) if you
want to see bright mono video, otherwise you will need a bright external
light source to see something resembling colour.
***********************************************************************

You will now have colour video ! I use gqcam to see it.  If the picture looks
strange, the brightness and contrast are probably incorrect. If you use the
internal CCD, aren't using dumppix=6 and see a black image, this is a colour
image which is too dark to show anything. I'm working on brightness control
for the CCD, in the meantime use an external camera with a very bright light.

Caveats:
   * Works with either the internal CCD or an external video device with an
        SPCA505
   * Camera must be connected and live before opening video device
   * Sometimes fails to start streaming - suspect a sync/lock problem with the
        SAA7113
        If you don't get a picture, unload and re-load the module, then try again
   * To take still shots, use vgrabber to grab a frame as a PNM format image
   * Limited colour support. You may find that this works now with the
        internal CCD
   * Only supports 160x120 [Some limited support for larger sizes on external
        input and CCD on 505]
   * No compression support
   * Some instability, particularly on SMP machines.
   * Brightness and contrast controls are fixed for external inputs, and may
        now work for CCD
        Enable this support with the DANGER_WILL_ROBINSON define on the
        compile line
   * Only tested with the SPCA505 and SAA7113. Work in progress for
        SPCA506/SPCA501 (ish) support
   * Some limited image size changing is supported for the external input
         only. (Expect some image corruption when switching size, I know what
         causes this and I'm working on fixing it).
         Supported resolutions are 160x120, 176x144, 352x288, but the driver
         will accept other sizes and map to the closest smaller size it
         supports.
   * Only tested on X86 - maybe byte ordering problems on other systems.
   * GQCam throttles frames at 10 frames per second - the driver supports up
         to about 25 if you change the gcqam command line parameter.
   * Some support for on-screen display of frame index and size. See below.
