[media] doc-rst: add documentation for cpia2 driver

$Id: README,v 1.7 2005/08/29 23:39:57 sbertin Exp $

The cpia2 driver

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

1. Introduction

Authors: Peter Pregler <Peter_Pregler@email.com>,

Scott J. Bertin <scottbertin@yahoo.com>, and

Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which

this one was modelled from.

Introduction

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

This is a driver for STMicroelectronics's CPiA2 (second generation

Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG

module was getting out of hand, so I separated them.  It is not likely that

there will be a parallel port version.

FEATURES:

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 sizes in between.

- Adjust brightness, color, contrast while streaming.

- Flicker control settable for 50 or 60 Hz mains frequency.

2. Making and installing the stv672 driver modules:

Making and installing the stv672 driver modules

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

Requirements

~~~~~~~~~~~~

	Requirements:

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

	This should work with 2.4 (2.4.23 and later) and 2.6 kernels, but has

only been tested on 2.6.  Video4Linux must be either compiled into the kernel or

Video4Linux must be either compiled into the kernel or

available as a module.  Video4Linux2 is automatically detected and made

available at compile time.

	Compiling:

	----------

	As root, do a make install.  This will compile and install the modules

into the media/video directory in the module tree. For 2.4 kernels, use

Makefile_2.4 (aka do make -f Makefile_2.4 install).

Setup

~~~~~

	Setup:

	------

Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This

may be done automatically by your distribution.

3. Driver options

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.

flicker_mode	0 to disable, or 1 to enable flicker reduction.

		(default 0). This is only effective if the camera

		uses a stv0672 coprocessor.

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

Setting the options

~~~~~~~~~~~~~~~~~~~

	Setting the options:

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

If you are using modules, edit /etc/modules.conf and add an options

line like this:

.. code-block:: none

	options cpia2 num_buffers=3 buffer_size=65535

If the driver is compiled into the kernel, at boot time specify them

like this:

.. code-block:: none

	cpia2.num_buffers=3 cpia2.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

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

Table: Image size(bytes)

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

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

Using the camera

~~~~~~~~~~~~~~~~

We are providing a modified gqcam application to view the output. In

order to avoid confusion, here it is called mview.  There is also the qx5view

program which can also control the lights on the qx5 microscope. MJPEG Tools

(http://mjpeg.sourceforge.net) can also be used to record from the camera.

5. Notes to developers:

Notes to developers

~~~~~~~~~~~~~~~~~~~

   - This is a driver version stripped of the 2.4 back compatibility

     and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.

6. Thanks:

   - Peter Pregler <Peter_Pregler@email.com>,

     Scott J. Bertin <scottbertin@yahoo.com>, and

     Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which

     this one was modelled from.

Programmer's overview of cpia2 driver

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a

division of ST Microelectronics).  There are two versions.  The first is the

STV0672, which is capable of up to 30 frames per second (fps) in frame sizes

up to CIF, and 15 fps for VGA frames.  The STV0676 is an improved version,

which can handle up to 30 fps VGA.  Both coprocessors can be attached to two

CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor.  These will

be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors.

The two chipsets operate almost identically.  The core is an 8051 processor,

running two different versions of firmware.  The 672 runs the VP4 video

processor code, the 676 runs VP5.  There are a few differences in register

mappings for the two chips.  In these cases, the symbols defined in the

header files are marked with VP4 or VP5 as part of the symbol name.

The cameras appear externally as three sets of registers. Setting register

values is the only way to control the camera.  Some settings are

interdependant, such as the sequence required to power up the camera. I will

try to make note of all of these cases.

The register sets are called blocks.  Block 0 is the system block.  This

section is always powered on when the camera is plugged in.  It contains

registers that control housekeeping functions such as powering up the video

processor.  The video processor is the VP block.  These registers control

how the video from the sensor is processed.  Examples are timing registers,

user mode (vga, qvga), scaling, cropping, framerates, and so on.  The last

block is the video compressor (VC).  The video stream sent from the camera is

compressed as Motion JPEG (JPEGA).  The VC controls all of the compression

parameters.  Looking at the file cpia2_registers.h, you can get a full view

of these registers and the possible values for most of them.

One or more registers can be set or read by sending a usb control message to

the camera.  There are three modes for this.  Block mode requests a number

of contiguous registers.  Random mode reads or writes random registers with

a tuple structure containing address/value pairs.  The repeat mode is only

used by VP4 to load a firmware patch.  It contains a starting address and

a sequence of bytes to be written into a gpio port.

			Programmer's View of Cpia2

Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a

division of ST Microelectronics).  There are two versions.  The first is the

STV0672, which is capable of up to 30 frames per second (fps) in frame sizes

up to CIF, and 15 fps for VGA frames.  The STV0676 is an improved version,

which can handle up to 30 fps VGA.  Both coprocessors can be attached to two

CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor.  These will

be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors.

The two chipsets operate almost identically.  The core is an 8051 processor,

running two different versions of firmware.  The 672 runs the VP4 video

processor code, the 676 runs VP5.  There are a few differences in register

mappings for the two chips.  In these cases, the symbols defined in the

header files are marked with VP4 or VP5 as part of the symbol name.

The cameras appear externally as three sets of registers. Setting register

values is the only way to control the camera.  Some settings are

interdependant, such as the sequence required to power up the camera. I will

try to make note of all of these cases.

The register sets are called blocks.  Block 0 is the system block.  This

section is always powered on when the camera is plugged in.  It contains

registers that control housekeeping functions such as powering up the video

processor.  The video processor is the VP block.  These registers control

how the video from the sensor is processed.  Examples are timing registers,

user mode (vga, qvga), scaling, cropping, framerates, and so on.  The last

block is the video compressor (VC).  The video stream sent from the camera is

compressed as Motion JPEG (JPEGA).  The VC controls all of the compression

parameters.  Looking at the file cpia2_registers.h, you can get a full view

of these registers and the possible values for most of them.

One or more registers can be set or read by sending a usb control message to

the camera.  There are three modes for this.  Block mode requests a number

of contiguous registers.  Random mode reads or writes random registers with

a tuple structure containing address/value pairs.  The repeat mode is only

used by VP4 to load a firmware patch.  It contains a starting address and

a sequence of bytes to be written into a gpio port.

The cx18 driver

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

.. note::

   This documentation is outdated.

Some notes regarding the cx18 driver for the Conexant CX23418 MPEG

encoder chip:

	fourcc

	cardlist

	cafe_ccic

	cpia2

	cx18

	zr364xx