Commit | Line | Data |
---|---|---|
ba9f270e MCC |
1 | The cpia2 driver |
2 | ================ | |
ab33d507 | 3 | |
ba9f270e MCC |
4 | Authors: Peter Pregler <Peter_Pregler@email.com>, |
5 | Scott J. Bertin <scottbertin@yahoo.com>, and | |
6 | Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which | |
7 | this one was modelled from. | |
ab33d507 | 8 | |
ba9f270e MCC |
9 | Introduction |
10 | ------------ | |
11 | ||
12 | This is a driver for STMicroelectronics's CPiA2 (second generation | |
ab33d507 AC |
13 | Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG |
14 | stream at up to vga size. It implements the Video4Linux interface as much as | |
15 | possible. Since the V4L interface does not support compressed formats, only | |
16 | an mjpeg enabled application can be used with the camera. We have modified the | |
17 | gqcam application to view this stream. | |
18 | ||
ba9f270e | 19 | The driver is implemented as two kernel modules. The cpia2 module |
ab33d507 AC |
20 | contains the camera functions and the V4L interface. The cpia2_usb module |
21 | contains usb specific functions. The main reason for this was the size of the | |
5edfe7d8 | 22 | module was getting out of hand, so I separated them. It is not likely that |
ab33d507 AC |
23 | there will be a parallel port version. |
24 | ||
ba9f270e MCC |
25 | Features |
26 | -------- | |
27 | ||
28 | - 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. | |
38 | ||
39 | Making and installing the stv672 driver modules | |
40 | ----------------------------------------------- | |
41 | ||
42 | Requirements | |
43 | ~~~~~~~~~~~~ | |
44 | ||
45 | Video4Linux must be either compiled into the kernel or | |
ab33d507 AC |
46 | available as a module. Video4Linux2 is automatically detected and made |
47 | available at compile time. | |
48 | ||
ba9f270e MCC |
49 | Setup |
50 | ~~~~~ | |
ab33d507 | 51 | |
ba9f270e | 52 | Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This |
ab33d507 AC |
53 | may be done automatically by your distribution. |
54 | ||
ba9f270e MCC |
55 | Driver options |
56 | ~~~~~~~~~~~~~~ | |
57 | ||
e6530624 MCC |
58 | .. tabularcolumns:: |p{13ex}|L| |
59 | ||
60 | ||
ba9f270e MCC |
61 | ============== ======================================================== |
62 | Option Description | |
63 | ============== ======================================================== | |
64 | video_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. | |
67 | buffer_size Size for each frame buffer in bytes (default 68k) | |
68 | num_buffers Number of frame buffers (1-32, default 3) | |
69 | alternate USB Alternate (2-7, default 7) | |
70 | flicker_freq Frequency for flicker reduction(50 or 60, default 60) | |
71 | flicker_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 | ============== ======================================================== | |
75 | ||
76 | Setting the options | |
77 | ~~~~~~~~~~~~~~~~~~~ | |
78 | ||
79 | If you are using modules, edit /etc/modules.conf and add an options | |
ab33d507 | 80 | line like this: |
ba9f270e MCC |
81 | |
82 | .. code-block:: none | |
83 | ||
ab33d507 AC |
84 | options cpia2 num_buffers=3 buffer_size=65535 |
85 | ||
ba9f270e | 86 | If the driver is compiled into the kernel, at boot time specify them |
ab33d507 | 87 | like this: |
ba9f270e MCC |
88 | |
89 | .. code-block:: none | |
90 | ||
8cbe84f3 | 91 | cpia2.num_buffers=3 cpia2.buffer_size=65535 |
ab33d507 | 92 | |
ba9f270e MCC |
93 | What buffer size should I use? |
94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
95 | ||
96 | The maximum image size depends on the alternate you choose, and the | |
ab33d507 AC |
97 | frame rate achieved by the camera. If the compression engine is able to |
98 | keep up with the frame rate, the maximum image size is given by the table | |
99 | below. | |
ba9f270e MCC |
100 | |
101 | The compression engine starts out at maximum compression, and will | |
ab33d507 AC |
102 | increase image quality until it is close to the size in the table. As long |
103 | as the compression engine can keep up with the frame rate, after a short time | |
104 | the images will all be about the size in the table, regardless of resolution. | |
ba9f270e MCC |
105 | |
106 | At low alternate settings, the compression engine may not be able to | |
ab33d507 AC |
107 | compress the image enough and will reduce the frame rate by producing larger |
108 | images. | |
ba9f270e MCC |
109 | |
110 | The default of 68k should be good for most users. This will handle | |
ab33d507 AC |
111 | any alternate at frame rates down to 15fps. For lower frame rates, it may |
112 | be necessary to increase the buffer size to avoid having frames dropped due | |
113 | to insufficient space. | |
114 | ||
ba9f270e MCC |
115 | ========== ========== ======== ===== |
116 | Alternate 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 | ========== ========== ======== ===== | |
125 | ||
126 | Table: Image size(bytes) | |
127 | ||
128 | ||
129 | How many buffers should I use? | |
130 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
131 | ||
132 | For normal streaming, 3 should give the best results. With only 2, | |
ab33d507 AC |
133 | it is possible for the camera to finish sending one image just after a |
134 | program has started reading the other. If this happens, the driver must drop | |
135 | a frame. The exception to this is if you have a heavily loaded machine. In | |
136 | this case use 2 buffers. You are probably not reading at the full frame rate. | |
137 | If the camera can send multiple images before a read finishes, it could | |
138 | overwrite the third buffer before the read finishes, leading to a corrupt | |
139 | image. Single and double buffering have extra checks to avoid overwriting. | |
140 | ||
ba9f270e MCC |
141 | Using the camera |
142 | ~~~~~~~~~~~~~~~~ | |
ab33d507 | 143 | |
ba9f270e | 144 | We are providing a modified gqcam application to view the output. In |
ab33d507 AC |
145 | order to avoid confusion, here it is called mview. There is also the qx5view |
146 | program 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 | ||
ba9f270e MCC |
149 | Notes to developers |
150 | ~~~~~~~~~~~~~~~~~~~ | |
ab33d507 AC |
151 | |
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 | ||
ba9f270e MCC |
155 | Programmer's overview of cpia2 driver |
156 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
157 | ||
158 | Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a | |
159 | division of ST Microelectronics). There are two versions. The first is the | |
160 | STV0672, which is capable of up to 30 frames per second (fps) in frame sizes | |
161 | up to CIF, and 15 fps for VGA frames. The STV0676 is an improved version, | |
162 | which can handle up to 30 fps VGA. Both coprocessors can be attached to two | |
163 | CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor. These will | |
164 | be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors. | |
165 | ||
166 | The two chipsets operate almost identically. The core is an 8051 processor, | |
167 | running two different versions of firmware. The 672 runs the VP4 video | |
168 | processor code, the 676 runs VP5. There are a few differences in register | |
169 | mappings for the two chips. In these cases, the symbols defined in the | |
170 | header files are marked with VP4 or VP5 as part of the symbol name. | |
171 | ||
172 | The cameras appear externally as three sets of registers. Setting register | |
173 | values is the only way to control the camera. Some settings are | |
174 | interdependant, such as the sequence required to power up the camera. I will | |
175 | try to make note of all of these cases. | |
176 | ||
177 | The register sets are called blocks. Block 0 is the system block. This | |
178 | section is always powered on when the camera is plugged in. It contains | |
179 | registers that control housekeeping functions such as powering up the video | |
180 | processor. The video processor is the VP block. These registers control | |
181 | how the video from the sensor is processed. Examples are timing registers, | |
182 | user mode (vga, qvga), scaling, cropping, framerates, and so on. The last | |
183 | block is the video compressor (VC). The video stream sent from the camera is | |
184 | compressed as Motion JPEG (JPEGA). The VC controls all of the compression | |
185 | parameters. Looking at the file cpia2_registers.h, you can get a full view | |
186 | of these registers and the possible values for most of them. | |
187 | ||
188 | One or more registers can be set or read by sending a usb control message to | |
189 | the camera. There are three modes for this. Block mode requests a number | |
190 | of contiguous registers. Random mode reads or writes random registers with | |
191 | a tuple structure containing address/value pairs. The repeat mode is only | |
192 | used by VP4 to load a firmware patch. It contains a starting address and | |
193 | a sequence of bytes to be written into a gpio port. |