blob: b5125016cfcbc0d604727308b0e79988d40a2679 [file] [log] [blame]
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -03001The cpia2 driver
2================
Alan Coxab33d502006-02-27 00:09:05 -03003
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -03004Authors: Peter Pregler <Peter_Pregler@email.com>,
5Scott J. Bertin <scottbertin@yahoo.com>, and
6Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
7this one was modelled from.
Alan Coxab33d502006-02-27 00:09:05 -03008
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -03009Introduction
10------------
11
12This is a driver for STMicroelectronics's CPiA2 (second generation
Alan Coxab33d502006-02-27 00:09:05 -030013Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG
14stream at up to vga size. It implements the Video4Linux interface as much as
15possible. Since the V4L interface does not support compressed formats, only
16an mjpeg enabled application can be used with the camera. We have modified the
17gqcam application to view this stream.
18
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030019The driver is implemented as two kernel modules. The cpia2 module
Alan Coxab33d502006-02-27 00:09:05 -030020contains the camera functions and the V4L interface. The cpia2_usb module
21contains usb specific functions. The main reason for this was the size of the
Masanari Iida5edfe7d2012-04-05 17:02:52 -070022module was getting out of hand, so I separated them. It is not likely that
Alan Coxab33d502006-02-27 00:09:05 -030023there will be a parallel port version.
24
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030025Features
26--------
Alan Coxab33d502006-02-27 00:09:05 -030027
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030028- Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos
29 sensors. I only have the vga sensor, so can't test the other.
30- Image formats: VGA, QVGA, CIF, QCIF, and a number of sizes in between.
31 VGA and QVGA are the native image sizes for the VGA camera. CIF is done
32 in the coprocessor by scaling QVGA. All other sizes are done by clipping.
33- Palette: YCrCb, compressed with MJPEG.
34- Some compression parameters are settable.
35- Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA).
36- Adjust brightness, color, contrast while streaming.
37- Flicker control settable for 50 or 60 Hz mains frequency.
Alan Coxab33d502006-02-27 00:09:05 -030038
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030039Making and installing the stv672 driver modules
40-----------------------------------------------
41
42Requirements
43~~~~~~~~~~~~
44
45Video4Linux must be either compiled into the kernel or
Alan Coxab33d502006-02-27 00:09:05 -030046available as a module. Video4Linux2 is automatically detected and made
47available at compile time.
48
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030049Setup
50~~~~~
Alan Coxab33d502006-02-27 00:09:05 -030051
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030052Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This
Alan Coxab33d502006-02-27 00:09:05 -030053may be done automatically by your distribution.
54
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030055Driver options
56~~~~~~~~~~~~~~
Alan Coxab33d502006-02-27 00:09:05 -030057
Mauro Carvalho Chehabe6530622016-08-20 09:26:42 -030058.. tabularcolumns:: |p{13ex}|L|
59
60
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030061============== ========================================================
62Option Description
63============== ========================================================
64video_nr video device to register (0=/dev/video0, etc)
65 range -1 to 64. default is -1 (first available)
66 If you have more than 1 camera, this MUST be -1.
67buffer_size Size for each frame buffer in bytes (default 68k)
68num_buffers Number of frame buffers (1-32, default 3)
69alternate USB Alternate (2-7, default 7)
70flicker_freq Frequency for flicker reduction(50 or 60, default 60)
71flicker_mode 0 to disable, or 1 to enable flicker reduction.
72 (default 0). This is only effective if the camera
73 uses a stv0672 coprocessor.
74============== ========================================================
Alan Coxab33d502006-02-27 00:09:05 -030075
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030076Setting the options
77~~~~~~~~~~~~~~~~~~~
78
79If you are using modules, edit /etc/modules.conf and add an options
Alan Coxab33d502006-02-27 00:09:05 -030080line like this:
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030081
82.. code-block:: none
83
Alan Coxab33d502006-02-27 00:09:05 -030084 options cpia2 num_buffers=3 buffer_size=65535
85
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030086If the driver is compiled into the kernel, at boot time specify them
Alan Coxab33d502006-02-27 00:09:05 -030087like this:
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030088
89.. code-block:: none
90
Adrian Bunk8cbe84f2006-02-28 04:40:51 -030091 cpia2.num_buffers=3 cpia2.buffer_size=65535
Alan Coxab33d502006-02-27 00:09:05 -030092
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -030093What buffer size should I use?
94~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95
96The maximum image size depends on the alternate you choose, and the
Alan Coxab33d502006-02-27 00:09:05 -030097frame rate achieved by the camera. If the compression engine is able to
98keep up with the frame rate, the maximum image size is given by the table
99below.
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300100
101The compression engine starts out at maximum compression, and will
Alan Coxab33d502006-02-27 00:09:05 -0300102increase image quality until it is close to the size in the table. As long
103as the compression engine can keep up with the frame rate, after a short time
104the images will all be about the size in the table, regardless of resolution.
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300105
106At low alternate settings, the compression engine may not be able to
Alan Coxab33d502006-02-27 00:09:05 -0300107compress the image enough and will reduce the frame rate by producing larger
108images.
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300109
110The default of 68k should be good for most users. This will handle
Alan Coxab33d502006-02-27 00:09:05 -0300111any alternate at frame rates down to 15fps. For lower frame rates, it may
112be necessary to increase the buffer size to avoid having frames dropped due
113to insufficient space.
114
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300115========== ========== ======== =====
116Alternate bytes/ms 15fps 30fps
117========== ========== ======== =====
118 2 128 8533 4267
119 3 384 25600 12800
120 4 640 42667 21333
121 5 768 51200 25600
122 6 896 59733 29867
123 7 1023 68200 34100
124========== ========== ======== =====
Alan Coxab33d502006-02-27 00:09:05 -0300125
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300126Table: Image size(bytes)
127
128
129How many buffers should I use?
130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131
132For normal streaming, 3 should give the best results. With only 2,
Alan Coxab33d502006-02-27 00:09:05 -0300133it is possible for the camera to finish sending one image just after a
134program has started reading the other. If this happens, the driver must drop
135a frame. The exception to this is if you have a heavily loaded machine. In
136this case use 2 buffers. You are probably not reading at the full frame rate.
137If the camera can send multiple images before a read finishes, it could
138overwrite the third buffer before the read finishes, leading to a corrupt
139image. Single and double buffering have extra checks to avoid overwriting.
140
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300141Using the camera
142~~~~~~~~~~~~~~~~
Alan Coxab33d502006-02-27 00:09:05 -0300143
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300144We are providing a modified gqcam application to view the output. In
Alan Coxab33d502006-02-27 00:09:05 -0300145order to avoid confusion, here it is called mview. There is also the qx5view
146program which can also control the lights on the qx5 microscope. MJPEG Tools
147(http://mjpeg.sourceforge.net) can also be used to record from the camera.
148
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300149Notes to developers
150~~~~~~~~~~~~~~~~~~~
Alan Coxab33d502006-02-27 00:09:05 -0300151
152 - This is a driver version stripped of the 2.4 back compatibility
153 and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.
154
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300155Programmer's overview of cpia2 driver
156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alan Coxab33d502006-02-27 00:09:05 -0300157
Mauro Carvalho Chehabba9f2702016-07-17 17:20:26 -0300158Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a
159division of ST Microelectronics). There are two versions. The first is the
160STV0672, which is capable of up to 30 frames per second (fps) in frame sizes
161up to CIF, and 15 fps for VGA frames. The STV0676 is an improved version,
162which can handle up to 30 fps VGA. Both coprocessors can be attached to two
163CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor. These will
164be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors.
165
166The two chipsets operate almost identically. The core is an 8051 processor,
167running two different versions of firmware. The 672 runs the VP4 video
168processor code, the 676 runs VP5. There are a few differences in register
169mappings for the two chips. In these cases, the symbols defined in the
170header files are marked with VP4 or VP5 as part of the symbol name.
171
172The cameras appear externally as three sets of registers. Setting register
173values is the only way to control the camera. Some settings are
174interdependant, such as the sequence required to power up the camera. I will
175try to make note of all of these cases.
176
177The register sets are called blocks. Block 0 is the system block. This
178section is always powered on when the camera is plugged in. It contains
179registers that control housekeeping functions such as powering up the video
180processor. The video processor is the VP block. These registers control
181how the video from the sensor is processed. Examples are timing registers,
182user mode (vga, qvga), scaling, cropping, framerates, and so on. The last
183block is the video compressor (VC). The video stream sent from the camera is
184compressed as Motion JPEG (JPEGA). The VC controls all of the compression
185parameters. Looking at the file cpia2_registers.h, you can get a full view
186of these registers and the possible values for most of them.
187
188One or more registers can be set or read by sending a usb control message to
189the camera. There are three modes for this. Block mode requests a number
190of contiguous registers. Random mode reads or writes random registers with
191a tuple structure containing address/value pairs. The repeat mode is only
192used by VP4 to load a firmware patch. It contains a starting address and
193a sequence of bytes to be written into a gpio port.