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 | ||
58 | ============== ======================================================== | |
59 | Option Description | |
60 | ============== ======================================================== | |
61 | video_nr video device to register (0=/dev/video0, etc) | |
62 | range -1 to 64. default is -1 (first available) | |
63 | If you have more than 1 camera, this MUST be -1. | |
64 | buffer_size Size for each frame buffer in bytes (default 68k) | |
65 | num_buffers Number of frame buffers (1-32, default 3) | |
66 | alternate USB Alternate (2-7, default 7) | |
67 | flicker_freq Frequency for flicker reduction(50 or 60, default 60) | |
68 | flicker_mode 0 to disable, or 1 to enable flicker reduction. | |
69 | (default 0). This is only effective if the camera | |
70 | uses a stv0672 coprocessor. | |
71 | ============== ======================================================== | |
72 | ||
73 | Setting the options | |
74 | ~~~~~~~~~~~~~~~~~~~ | |
75 | ||
76 | If you are using modules, edit /etc/modules.conf and add an options | |
ab33d507 | 77 | line like this: |
ba9f270e MCC |
78 | |
79 | .. code-block:: none | |
80 | ||
ab33d507 AC |
81 | options cpia2 num_buffers=3 buffer_size=65535 |
82 | ||
ba9f270e | 83 | If the driver is compiled into the kernel, at boot time specify them |
ab33d507 | 84 | like this: |
ba9f270e MCC |
85 | |
86 | .. code-block:: none | |
87 | ||
8cbe84f3 | 88 | cpia2.num_buffers=3 cpia2.buffer_size=65535 |
ab33d507 | 89 | |
ba9f270e MCC |
90 | What buffer size should I use? |
91 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
92 | ||
93 | The maximum image size depends on the alternate you choose, and the | |
ab33d507 AC |
94 | frame rate achieved by the camera. If the compression engine is able to |
95 | keep up with the frame rate, the maximum image size is given by the table | |
96 | below. | |
ba9f270e MCC |
97 | |
98 | The compression engine starts out at maximum compression, and will | |
ab33d507 AC |
99 | increase image quality until it is close to the size in the table. As long |
100 | as the compression engine can keep up with the frame rate, after a short time | |
101 | the images will all be about the size in the table, regardless of resolution. | |
ba9f270e MCC |
102 | |
103 | At low alternate settings, the compression engine may not be able to | |
ab33d507 AC |
104 | compress the image enough and will reduce the frame rate by producing larger |
105 | images. | |
ba9f270e MCC |
106 | |
107 | The default of 68k should be good for most users. This will handle | |
ab33d507 AC |
108 | any alternate at frame rates down to 15fps. For lower frame rates, it may |
109 | be necessary to increase the buffer size to avoid having frames dropped due | |
110 | to insufficient space. | |
111 | ||
ba9f270e MCC |
112 | ========== ========== ======== ===== |
113 | Alternate bytes/ms 15fps 30fps | |
114 | ========== ========== ======== ===== | |
115 | 2 128 8533 4267 | |
116 | 3 384 25600 12800 | |
117 | 4 640 42667 21333 | |
118 | 5 768 51200 25600 | |
119 | 6 896 59733 29867 | |
120 | 7 1023 68200 34100 | |
121 | ========== ========== ======== ===== | |
122 | ||
123 | Table: Image size(bytes) | |
124 | ||
125 | ||
126 | How many buffers should I use? | |
127 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
128 | ||
129 | For normal streaming, 3 should give the best results. With only 2, | |
ab33d507 AC |
130 | it is possible for the camera to finish sending one image just after a |
131 | program has started reading the other. If this happens, the driver must drop | |
132 | a frame. The exception to this is if you have a heavily loaded machine. In | |
133 | this case use 2 buffers. You are probably not reading at the full frame rate. | |
134 | If the camera can send multiple images before a read finishes, it could | |
135 | overwrite the third buffer before the read finishes, leading to a corrupt | |
136 | image. Single and double buffering have extra checks to avoid overwriting. | |
137 | ||
ba9f270e MCC |
138 | Using the camera |
139 | ~~~~~~~~~~~~~~~~ | |
ab33d507 | 140 | |
ba9f270e | 141 | We are providing a modified gqcam application to view the output. In |
ab33d507 AC |
142 | order to avoid confusion, here it is called mview. There is also the qx5view |
143 | program which can also control the lights on the qx5 microscope. MJPEG Tools | |
144 | (http://mjpeg.sourceforge.net) can also be used to record from the camera. | |
145 | ||
ba9f270e MCC |
146 | Notes to developers |
147 | ~~~~~~~~~~~~~~~~~~~ | |
ab33d507 AC |
148 | |
149 | - This is a driver version stripped of the 2.4 back compatibility | |
150 | and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support. | |
151 | ||
ba9f270e MCC |
152 | Programmer's overview of cpia2 driver |
153 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
154 | ||
155 | Cpia2 is the second generation video coprocessor from VLSI Vision Ltd (now a | |
156 | division of ST Microelectronics). There are two versions. The first is the | |
157 | STV0672, which is capable of up to 30 frames per second (fps) in frame sizes | |
158 | up to CIF, and 15 fps for VGA frames. The STV0676 is an improved version, | |
159 | which can handle up to 30 fps VGA. Both coprocessors can be attached to two | |
160 | CMOS sensors - the vvl6410 CIF sensor and the vvl6500 VGA sensor. These will | |
161 | be referred to as the 410 and the 500 sensors, or the CIF and VGA sensors. | |
162 | ||
163 | The two chipsets operate almost identically. The core is an 8051 processor, | |
164 | running two different versions of firmware. The 672 runs the VP4 video | |
165 | processor code, the 676 runs VP5. There are a few differences in register | |
166 | mappings for the two chips. In these cases, the symbols defined in the | |
167 | header files are marked with VP4 or VP5 as part of the symbol name. | |
168 | ||
169 | The cameras appear externally as three sets of registers. Setting register | |
170 | values is the only way to control the camera. Some settings are | |
171 | interdependant, such as the sequence required to power up the camera. I will | |
172 | try to make note of all of these cases. | |
173 | ||
174 | The register sets are called blocks. Block 0 is the system block. This | |
175 | section is always powered on when the camera is plugged in. It contains | |
176 | registers that control housekeeping functions such as powering up the video | |
177 | processor. The video processor is the VP block. These registers control | |
178 | how the video from the sensor is processed. Examples are timing registers, | |
179 | user mode (vga, qvga), scaling, cropping, framerates, and so on. The last | |
180 | block is the video compressor (VC). The video stream sent from the camera is | |
181 | compressed as Motion JPEG (JPEGA). The VC controls all of the compression | |
182 | parameters. Looking at the file cpia2_registers.h, you can get a full view | |
183 | of these registers and the possible values for most of them. | |
184 | ||
185 | One or more registers can be set or read by sending a usb control message to | |
186 | the camera. There are three modes for this. Block mode requests a number | |
187 | of contiguous registers. Random mode reads or writes random registers with | |
188 | a tuple structure containing address/value pairs. The repeat mode is only | |
189 | used by VP4 to load a firmware patch. It contains a starting address and | |
190 | a sequence of bytes to be written into a gpio port. |