readme

cpia usb摄像头的驱动程序源码。需要video4linux和i2c-core支持

CONFIG_PARPORT=y
CONFIG_PARPORT_PC=y
CONFIG_PARPORT_PC_FIFO=y
CONFIG_PARPORT_1284=y

and/or

CONFIG_USB=y
CONFIG_USB_[OHCI/UHCI/UHCI_ALT/EHCI_HCD]=y


The cpia-stuff is in the section 'Character devices -> Video For Linux'.

CONFIG_VIDEO_DEV=y
CONFIG_VIDEO_CPIA=y
and (as needed):
CONFIG_VIDEO_CPIA_PP=y
CONFIG_VIDEO_CPIA_USB=y

For camera control using /proc/cpia/video<n>,
CONFIG_PROC_FS=y


The kernel-linked cpia_pp driver supports boot-parameter options for 
selecting parallel ports:   You can give these at the LILO-prompt,
or specify them in lilo.conf, with an append-line:

   append="cpia_pp=<...>",

where <...> is one of: [ none, auto, parport <n>], where
<n> is the desired parport number.

To use fast DMA/irq ECP parallel port modes, you will need to tell the kernel 
upon boot time the hardware configuration of the parport. You can give the 
boot-parameter at the LILO-prompt or specify it in lilo.conf. 
I use the following
append-line in lilo.conf:

        append="parport=0x378,7,3"

See Documentation/parport.txt for more information about the
configuration of the parport and the values given above. Do not simply
use the values given above.


Sharing the port with lp.
================================.
By default, the driver lp will register itself for all available
parallel ports.  Presumably, no printer is sharing a port with the
CPiA camera.   (The CPiA does have provision for a "pass-through" mode,
but none of the parallel-port CPiA webcams appear to have a pass-through
port, so the driver does not implement this feature; if it is in
fact needed, the CPiA datasheet and the GPL'd Windows driver available
at the website have the information on how to do it.)    In principle
it doesn't matter that lp also is registered on the port, but if it
is causing difficulties, or stopping the cpia_pp driver from
claiming the port, use lp's boot-time or module-load-time
options to prevent it from using the same port as the CPiA.
(For example, "options lp parport=auto" in the modules.conf file)

Using/controlling  CPiA cameras.
=================================
The camera is mainly controlled by a V4L application
using the Video4Linux interface, but extra driver settings
not accessible this way can be set by writing to /proc/cpia/video*.

A camera attached as /dev/video0 is controlled by /proc/cpia/video0,
which also gives information about the camera state:

Only the user owning the V4L process that "owns" the camera
can write to the corresponding /proc/cpia/video* file.
The variables listed as "read-only" are informational and cannot be
changed by the user. The "read-write" variables can be changed:

For example "compression_mode" has an entry

read-write
-----------------------  current       min       max   default  comment

compression_mode:           auto    none,auto,manual      auto

This means the current setting is the default (startup) value of
"auto", but the ranges of possible values is "none,auto,manual".

In "auto" mode, the camera adjusts the compression automatically,
in "none" mode it is disabled.  In "manual" mode the user can set
the compression parameters using the /proc/cpia/video* interface. 

To change the compression mode of a camera attached to /dev/video0,
mode, type at a command line:

"echo compression_mode: manual > /proc/cpia/video0"

A convenient gtk-python-based graphical application for controlling
the camera in this way is "cpia-control", by Peter Pregler, available
at http://sourveforge.net/projects/webcam.

The camera parameters controllable via the /proc interface,
and their ranges, are given below.   Only a limited subset of these are
controllable by the latest cpia-control (v0.41) at this time; these are
marked by "X" in the last column.  Other parameters are unlikely to be
changed by regular users.  See the cpia Developer's Guide [4] for more
details.

-----------------------   min       max   default  comment        cpia-control?
usb_alt_setting:            1         3         3   (usb only)           X
ecp_timing               slow    normal    normal   (parport only*)      X
brightness:                 0       100        50                        X
contrast:                   0        96        48    steps of 8          X
saturation:                 0       100        50                        X
sensor_fps:                 3        30        15                        X
stream_start_line:          0       288       240
sub_sample:               420       422       422                        X
yuv_order:               YUYV      UYVY      YUYV                        X
color_balance_mode:    manual      auto      auto                        X
red_gain:                   0       212        32                        X
green_gain:                 0       212         6                        X
blue_gain:                  0       212        92                        X
max_gain:                   1         8         2  1,2,4 or 8 **          X
exposure_mode:         manual      auto      auto                        X
centre_weight:            off        on        on                        X
gain:                       1  max_gain         1  1,2,4,8 possible      X
fine_exp:                   0       510         0                        X
coarse_exp:                 0       302       185                        X
red_comp:                 220       255       220
green1_comp:              214       255       214
green2_comp:              214       255       214
blue_comp:                230       255       230
apcor_gain1:              0x0      0xff      0x1c
apcor_gain2:              0x0      0xff      0x1a
apcor_gain4:              0x0      0xff      0x2d
apcor_gain8:              0x0      0xff      0x2a
vl_offset_gain1:            0       255        24
vl_offset_gain2:            0       255        28
vl_offset_gain4:            0       255        30
vl_offset_gain8:            0       255        30
flicker_control:          off        on       off                        X
mains_frequency:           50        60        50 only 50/60             X
allowable_overexposure:  auto       255      auto
compression_mode:        none,auto,manual      auto                      X
decimation_enable:        off       off        on       off              X
compression_target: framerate   quality   quality                        X
target_framerate:           1        30        15                        X
target_quality:             1        64         5                        X
y_threshold:                0        31         6                        X
uv_threshold:               0        31         6                        X
hysteresis:                 0       255         3
threshold_max:              0       255        11
small_step:                 0       255         1
large_step:                 0       255         3
decimation_hysteresis:      0       255         2
fr_diff_step_thresh:        0       255         5
q_diff_step_thresh:         0       255         3
decimation_thresh_mod:      0       255         2
toplight:                 off        on       off  (QX3 microscope only) X
bottomlight:              off        on       off  (QX3 microscope only) X


* The "ecp timing" setting switches between a "normal" and a "slow" mode for
ECP image streams from the camera.   Use the slow mode if too many frames
are being lost.    This setting will not appear unless either hardware
ECP or software ECP (TRISTATE) parallel port modes are available.


** An early version of the CPiA chip (v1.02) has a bug in its firmware; the 
driver works around this by imposing lower limits on max_gain and other 
settings when this version of the CPiA chip is detected. 




Multiple USB cameras on the same hub, and the "usb_alt_setting".
===============================================================

The "usb_alt setting" controls USB bandwidth use by USB cameras by setting
the maximum USB Packet Size for transmission of streamed images.   The
three "alternate interface settings" and the corresponding Max PacketSize are
alt 1: 448
alt 2: 704
alt 3: 960  (default)

If two or more cameras are attached to the _same_ USB hub, they can only
work if both are running with reduced USB PacketSize.  There is no problem
if they are on different hubs, but if a camera is started at alt setting 3,
the hub interference will cause another cpia device attached to the same hub 
to get unregistered, as if its cable had been brutally yanked out! 

Until this problem is fixed, here are three possible workarounds:

(1) If you are using the module form of the driver, load the cpia
module with module option "usb_alt=2" or "usb_alt=1". (see above).

(2) If you compile the module into the kernel, edit cpia.h, and
change the line "#define DEFAULT_USB_ALT_SETTING 3" to a lower value,
and rebuild the kernel.

(3) If you can't use either of these strategies, don't despair!  

Just open the first camera (say, on /dev/video0) with a 
Video4Linux application, so you become the temporary owner of 
/proc/cpia/video0.  Now change the alt setting with cpia-control v0.4.1 or
later, or by typing "echo usb_alt_setting: 2 > /proc/cpia/video0".  
Now close the V4L application; you will no longer be able to write to 
/proc/cpia/video0 until you restart the application, but the new alt=2 
setting will be remembered as long as the camera remains attached.    

Now start the second camera (which will correspond to a different video 
device, say /dev/video1).   Next reduce its alt setting to alt=2.   Now 
you can safely reopen the first camera (/dev/video0) which will now start 
with the remembered alt=2 setting.   Two USB cameras coexist happily
when both are using alt=2.   More than two on the same hub may require
alt=1 settings.    Non-cpia webcams may have similar ways to reduce the
USB Packet size: e.g., the ov511 driver has a "cams=n" module parameter
which selects among the possible "alt" settings of those USB devices.

The usb alt setting has no effect on parallel-port cameras.

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

DRIVER FEATURES:

- mmap/read v4l-interface (but no overlay)
- image formats: CIF/QCIF, SIF/QSIF, various others used by isabel;
  note: all sizes except CIF/QCIF are implemented by clipping, i.e.
  pixels are not uploaded from the camera
- palettes: VIDEO_PALETTE_GRAY, VIDEO_PALETTE_RGB565, VIDEO_PALETTE_RGB555,
  VIDEO_PALETTE_RGB24, VIDEO_PALETTE_RGB32, VIDEO_PALETTE_YUYV,
  VIDEO_PALETTE_UYVY, VIDEO_PALETTE_YUV422
- state information (color balance, exposure, ...) is preserved between
  device opens
- complete control over camera via proc-interface (_all_ camera settings are
  supported), there is also a python-gtk application available for this [3]
- works under SMP (but the driver is completely serialized and synchronous)
  so you get no benefit from SMP, but at least it does not crash your box
- might work for non-Intel architecture, let us know about this

---------------------------------------------------------------------------
TESTED APPLICATIONS:  (TODO: versions referred to here need updating) 

- a simple test application based on Xt is available at [3]
- another test-application based on gqcam-0.4 (uses GTK)
- gqcam-0.6 should work   (also gqcam-0.9, with a patch available from
  http://sourceforge.net/projects/webcam.)
- xawtv-3.x (also the webcam software)
- xawtv-2.46
- w3cam (cgi-interface and vidcat, e.g. you may try out 'vidcat  |xv
  -maxpect -root -quit +noresetroot -rmode 5 -')
- vic, the MBONE video conferencing tool (version 2.8ucl4-1)
- isabel 3R4beta (barely working, but AFAICT all the problems are on
  their side)
- camserv-0.40

See [3] for pointers to v4l-applications.

---------------------------------------------------------------------------
KNOWN PROBLEMS:

- some applications do not handle the image format correctly, you will
  see strange horizontal stripes instead of a nice picture -> make sure
  your application does use a supported image size or queries the driver
  for the actually used size (reason behind this: the camera cannot
  provide any image format, so if size NxM is requested the driver will
  use a format to the closest fitting N1xM1, the application should now
  query for this granted size, most applications do not).
- all the todo ;)
- if there is not enough light and the picture is too dark try to
  adjust the SetSensorFPS setting, automatic frame rate adjustment
  has its price
- do not try out isabel 3R4beta (built 135), you will be disappointed

---------------------------------------------------------------------------
TODO:  (but driver development is not currently active...). 

- multiple camera support (struct camera or something) - This should work,
  but hasn't been tested yet  (OK, it works, but if a USB camera is streaming
  video, and another USB camera is attached to the same hub and run at
  alt=3, it causes the first camera to get deregistered.....) (Now done).
- architecture independence?
- SMP-safe asynchronous mmap interface (Done ?)
- nibble mode for old parport interfaces  (Done)
- streaming capture, this should give a performance gain
- DMA parport access in 2.4 and later kernels (Done)
- conversion to video4linux-2 
---------------------------------------------------------------------------
IMPLEMENTATION NOTES:

The camera can act in two modes, streaming or grabbing. Right now a
polling grab-scheme is used. Maybe interrupt driven streaming will be
used for a asynchronous mmap interface in the next major release of the
driver. This might give a better frame rate.

---------------------------------------------------------------------------
THANKS (in no particular order):

- Scott J. Bertin <[e-mail]> for cleanups, the proc-filesystem
  and much more
- Henry Bruce <[e-mail]> for providing developers information about
  the CPiA chip, I wish all companies would treat Linux as seriously
- Karoly Erdei <[e-mail]> and RISC-Linz for being
  my boss ;) resp. my employer and for providing me the hardware and
  allow me to devote some working time to this project
- Manuel J. Petit de Gabriel <[e-mail]> for providing help
  with Isabel (http://isabel.dit.upm.es/)
- Bas Huisman <[e-mail]> for writing the initial parport code
- Jarl Totland <[e-mail]> for setting up the mailing list 
  and maintaining the web-server[3]
- Chris Whiteford <[e-mail]> for fixes related to the
  1.02 firmware
- special kudos to all the tester whose machines crashed and/or
  will crash. :)

---------------------------------------------------------------------------
REFERENCES

   1. http://www.risc.uni-linz.ac.at/people/ppregler
      mailto:[e-mail]
   2. see the file COPYING in the top directory of the kernel tree
   3. http://webcam.sourceforge.net/
   4. CPiA documentation is avaliable at [3].
   5. In December 2002 [e-mail] was
      maintaining the driver. The original authors do not appear to
      be active.