$Id: README,v 1.6 2002/01/26 00:07:17 mjarvis Exp $

1. Introduction

	This is a driver for STMicroelectronics's CPiA2 (second generation 
Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG
stream at up to vga size. It implements the Video4Linux interface as much as
possible.  Since the V4L interface does not support compressed formats, only 
an mjpeg enabled application can be used with the camera. We have modified the 
gqcam application to view this stream.

	The driver is implemented as two kernel modules. The cpia2 module
contains the camera functions and the V4L interface.  The cpia2_usb module
contains usb specific functions.  The main reason for this was the size of the
module was getting out of hand, so I separted them.  It is not likely that
there will be a parallel port version.

FEATURES:
   - Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos 
     sensors. I only have the vga sensor, so can't test the other.
   - Image formats: VGA, QVGA, CIF, QCIF, and a number of smaller sizes down 
     to 48 x x48.  Only VGA, QVGA, CIF, and QCIF have been tested at this 
     point, mainly because I haven't modified gqcam enough to check them.  
     VGA and QVGA are the native image sizes for the VGA camera. CIF is done 
     in the coprocessor by scaling QVGA.  All other sizes are done by clipping.
   - Palette: YCrCb, compressed with MJPEG.
   - Some compression parameters are settable.
   - Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA).
   - Adjust brightness, color, contrast while streaming.
   - Flicker control settable for 50 or 60 Hz mains frequency.

2. Making and installing the stv672 driver modules:

	Requirements:
	-------------
	I have only tested this driver with a 2.4.3 kernel. It should work on 
anything later.  It may work with 2.4.2.  It will NOT work with any 2.2 kernel.
The 2.2 usb code has a bug which causes some of the usb packets sent during 
initialization to fail.  Video4Linux must be either compiled into the kernel or
available as a module.

	Compiling:
	----------
	As root, do a make install.  This will compile and install the modules
into the media/video directory in the module tree.

	Note that doing a depmod -a with the modules installed results in two 
warnings about undefined symbols. This is because without patching the kernel,
depmod does not really know about these two modules, and doesn't export a 
couple of V4L symbols. The warnings can be ignored, as the modules do link
properly when loaded.

	Setup:
	------
	You will need to add aliases to your /etc/modules.conf file.  Add
these two lines:
	alias video cpia2
	before cpia2 videodev

	Now you can use modprobe to load and unload the drivers.  Use
	'modprobe cpia2' to load and 'modprobe -r cpia2_usb' to unload.

3. Driver options
	
	Option		Description
	------		-----------
	video_nr	video device to register (0=/dev/video0, etc)
			range -1 to 64.  default is -1 (first available)
			If you have more than 1 camera, this MUST be -1.
	buffer_size	Size for each frame buffer in bytes (default 68k)
	num_buffers	Number of frame buffers (1-32, default 3)
	alternate	USB Alternate (2-7, default 4)
	
	Setting the options:
	--------------------
	If you are using modules, edit /etc/modules.conf and add an options
line like this:
	options cpia2 num_buffers=3 buffer_size=65535
	
	If the driver is compiled into the kernel, at boot time specify them
like this:
	cpia2=num_buffers:3,buffer_size:65535
	
	What buffer size should I use?
	------------------------------
	The maximum image size depends on the alternate you choose, and the
frame rate achieved by the camera.  If the compression engine is able to
keep up with the frame rate, the maximum image size is given by the table
below.
	The compression engine starts out at maximum compression, and will
increase image quality until it is close to the size in the table.  As long
as the compression engine can keep up with the frame rate, after a short time
the images will all be about the size in the table, regardless of resolution.
	At low alternate settings, the compression engine may not be able to
compress the image enough and will reduce the frame rate by producing larger
images.
	The default of 68k should be good for most users.  This will handle
any alternate at frame rates down to 15fps.  For lower frame rates, it may
be necessary to increase the buffer size to avoid having frames dropped due
to insufficient space.

                	     Image size(bytes)
	Alternate  bytes/ms   15fps    30fps
	    2         128      8533     4267
	    3         384     25600    12800
	    4         640     42667    21333
	    5         768     51200    25600
	    6         896     59733    29867
	    7        1023     68200    34100

	Note: There is currently no way to specify the frame rate.  If you
have a CIF sensor, your frame rate is 30fps.  If you have a VGA sensor it
is 15fps unless you have the stv0676 coprocessor, then it is 30fps.
	
	How many buffers should I use?
	------------------------------
	For normal streaming, 3 should give the best results.  With only 2,
it is possible for the camera to finish sending one image just after a
program has started reading the other.  If this happens, the driver must drop
a frame.  The exception to this is if you have a heavily loaded machine.  In
this case use 2 buffers.  You are probably not reading at the full frame rate.
If the camera can send multiple images before a read finishes, it could
overwrite the third buffer before the read finishes, leading to a corrupt
image.  Single and double buffering have extra checks to avoid overwriting.

4. Using the camera

	We are providing a modified gqcam application to view the output. In
order to avoid confusion, here it is called mview.  I don't know of anything 
else that will work.

5. Known problems and things to do:

   - The driver seems to get very confused when 2 cameras are plugged in.
   - Although the camera outputs up to advertised frame rates, the current
     implementation of libjpeg is very slow. On my PIII-933, I get 15-17 fps
     for CIF size stream. A video (and possibly mmx) optimized version is
     needed.
   - There is currently no proc interface.  I'll get to it when I can.
   - Figure out a V4L compliant way to change framerate and usb bandwidth.

6. Notes to developers:
   - Do not modify the videodev_mjpeg.h header.  This comes directly from
     the MJPEG tools and is needed for compatibility with their extensions
     to the V4L API.

7. Thanks:

   - Peter Pregler <Peter_Pregler@email.com>,
     Scott J. Bertin <sbertin@securenym.net>, and 
     Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
     this one was modelled from.
