1.. SPDX-License-Identifier: GPL-2.0
2
3The cpia2 driver
4================
5
6Authors: Peter Pregler <Peter_Pregler@email.com>,
7Scott J. Bertin <scottbertin@yahoo.com>, and
8Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
9this one was modelled from.
10
11Introduction
12------------
13
14This is a driver for STMicroelectronics's CPiA2 (second generation
15Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG
16stream at up to vga size. It implements the Video4Linux interface as much as
17possible.  Since the V4L interface does not support compressed formats, only
18an mjpeg enabled application can be used with the camera. We have modified the
19gqcam application to view this stream.
20
21The driver is implemented as two kernel modules. The cpia2 module
22contains the camera functions and the V4L interface.  The cpia2_usb module
23contains usb specific functions.  The main reason for this was the size of the
24module was getting out of hand, so I separated them.  It is not likely that
25there will be a parallel port version.
26
27Features
28--------
29
30- Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos
31  sensors. I only have the vga sensor, so can't test the other.
32- Image formats: VGA, QVGA, CIF, QCIF, and a number of sizes in between.
33  VGA and QVGA are the native image sizes for the VGA camera. CIF is done
34  in the coprocessor by scaling QVGA.  All other sizes are done by clipping.
35- Palette: YCrCb, compressed with MJPEG.
36- Some compression parameters are settable.
37- Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA).
38- Adjust brightness, color, contrast while streaming.
39- Flicker control settable for 50 or 60 Hz mains frequency.
40
41Making and installing the stv672 driver modules
42-----------------------------------------------
43
44Requirements
45~~~~~~~~~~~~
46
47Video4Linux must be either compiled into the kernel or
48available as a module.  Video4Linux2 is automatically detected and made
49available at compile time.
50
51Setup
52~~~~~
53
54Use ``modprobe cpia2`` to load and ``modprobe -r cpia2`` to unload. This
55may be done automatically by your distribution.
56
57Driver options
58~~~~~~~~~~~~~~
59
60.. tabularcolumns:: |p{13ex}|L|
61
62
63==============  ========================================================
64Option		Description
65==============  ========================================================
66video_nr	video device to register (0=/dev/video0, etc)
67		range -1 to 64.  default is -1 (first available)
68		If you have more than 1 camera, this MUST be -1.
69buffer_size	Size for each frame buffer in bytes (default 68k)
70num_buffers	Number of frame buffers (1-32, default 3)
71alternate	USB Alternate (2-7, default 7)
72flicker_freq	Frequency for flicker reduction(50 or 60, default 60)
73flicker_mode	0 to disable, or 1 to enable flicker reduction.
74		(default 0). This is only effective if the camera
75		uses a stv0672 coprocessor.
76==============  ========================================================
77
78Setting the options
79~~~~~~~~~~~~~~~~~~~
80
81If you are using modules, edit /etc/modules.conf and add an options
82line like this::
83
84	options cpia2 num_buffers=3 buffer_size=65535
85
86If the driver is compiled into the kernel, at boot time specify them
87like this::
88
89	cpia2.num_buffers=3 cpia2.buffer_size=65535
90
91What buffer size should I use?
92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93
94The maximum image size depends on the alternate you choose, and the
95frame rate achieved by the camera.  If the compression engine is able to
96keep up with the frame rate, the maximum image size is given by the table
97below.
98
99The compression engine starts out at maximum compression, and will
100increase image quality until it is close to the size in the table.  As long
101as the compression engine can keep up with the frame rate, after a short time
102the images will all be about the size in the table, regardless of resolution.
103
104At low alternate settings, the compression engine may not be able to
105compress the image enough and will reduce the frame rate by producing larger
106images.
107
108The default of 68k should be good for most users.  This will handle
109any alternate at frame rates down to 15fps.  For lower frame rates, it may
110be necessary to increase the buffer size to avoid having frames dropped due
111to insufficient space.
112
113========== ========== ======== =====
114Alternate  bytes/ms   15fps    30fps
115========== ========== ======== =====
116    2         128      8533     4267
117    3         384     25600    12800
118    4         640     42667    21333
119    5         768     51200    25600
120    6         896     59733    29867
121    7        1023     68200    34100
122========== ========== ======== =====
123
124Table: Image size(bytes)
125
126
127How many buffers should I use?
128~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130For normal streaming, 3 should give the best results.  With only 2,
131it is possible for the camera to finish sending one image just after a
132program has started reading the other.  If this happens, the driver must drop
133a frame.  The exception to this is if you have a heavily loaded machine.  In
134this case use 2 buffers.  You are probably not reading at the full frame rate.
135If the camera can send multiple images before a read finishes, it could
136overwrite the third buffer before the read finishes, leading to a corrupt
137image.  Single and double buffering have extra checks to avoid overwriting.
138
139Using the camera
140~~~~~~~~~~~~~~~~
141
142We are providing a modified gqcam application to view the output. In
143order to avoid confusion, here it is called mview.  There is also the qx5view
144program which can also control the lights on the qx5 microscope. MJPEG Tools
145(http://mjpeg.sourceforge.net) can also be used to record from the camera.
146