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