Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 1 | The cpia2 driver |
| 2 | ================ |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 3 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 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. |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 8 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 9 | Introduction |
| 10 | ------------ |
| 11 | |
| 12 | This is a driver for STMicroelectronics's CPiA2 (second generation |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 19 | The driver is implemented as two kernel modules. The cpia2 module |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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 |
Masanari Iida | 5edfe7d | 2012-04-05 17:02:52 -0700 | [diff] [blame] | 22 | module was getting out of hand, so I separated them. It is not likely that |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 23 | there will be a parallel port version. |
| 24 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 25 | Features |
| 26 | -------- |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 27 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 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. |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 38 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 39 | Making and installing the stv672 driver modules |
| 40 | ----------------------------------------------- |
| 41 | |
| 42 | Requirements |
| 43 | ~~~~~~~~~~~~ |
| 44 | |
| 45 | Video4Linux must be either compiled into the kernel or |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 46 | available as a module. Video4Linux2 is automatically detected and made |
| 47 | available at compile time. |
| 48 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 49 | Setup |
| 50 | ~~~~~ |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 51 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 52 | Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 53 | may be done automatically by your distribution. |
| 54 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 55 | Driver options |
| 56 | ~~~~~~~~~~~~~~ |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 57 | |
Mauro Carvalho Chehab | e653062 | 2016-08-20 09:26:42 -0300 | [diff] [blame] | 58 | .. tabularcolumns:: |p{13ex}|L| |
| 59 | |
| 60 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 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 | ============== ======================================================== |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 75 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 76 | Setting the options |
| 77 | ~~~~~~~~~~~~~~~~~~~ |
| 78 | |
| 79 | If you are using modules, edit /etc/modules.conf and add an options |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 80 | line like this: |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 81 | |
| 82 | .. code-block:: none |
| 83 | |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 84 | options cpia2 num_buffers=3 buffer_size=65535 |
| 85 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 86 | If the driver is compiled into the kernel, at boot time specify them |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 87 | like this: |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 88 | |
| 89 | .. code-block:: none |
| 90 | |
Adrian Bunk | 8cbe84f | 2006-02-28 04:40:51 -0300 | [diff] [blame] | 91 | cpia2.num_buffers=3 cpia2.buffer_size=65535 |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 92 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 93 | What buffer size should I use? |
| 94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 95 | |
| 96 | The maximum image size depends on the alternate you choose, and the |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 100 | |
| 101 | The compression engine starts out at maximum compression, and will |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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. |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 105 | |
| 106 | At low alternate settings, the compression engine may not be able to |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 107 | compress the image enough and will reduce the frame rate by producing larger |
| 108 | images. |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 109 | |
| 110 | The default of 68k should be good for most users. This will handle |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 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 | ========== ========== ======== ===== |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 125 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 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, |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 141 | Using the camera |
| 142 | ~~~~~~~~~~~~~~~~ |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 143 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 144 | We are providing a modified gqcam application to view the output. In |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 149 | Notes to developers |
| 150 | ~~~~~~~~~~~~~~~~~~~ |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 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 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 155 | Programmer's overview of cpia2 driver |
| 156 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 157 | |
Mauro Carvalho Chehab | ba9f270 | 2016-07-17 17:20:26 -0300 | [diff] [blame] | 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. |