Documentation/media/v4l-drivers/cpia2.rst

   1 The cpia2 driver
   2 ================
   3
   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.
   8
   9 Introduction
  10 ------------
  11
  12 This is a driver for STMicroelectronics's CPiA2 (second generation
  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
  19 The driver is implemented as two kernel modules. The cpia2 module
  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
  22 module was getting out of hand, so I separated them.  It is not likely that
  23 there will be a parallel port version.
  24
  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
  46 available as a module.  Video4Linux2 is automatically detected and made
  47 available at compile time.
  48
  49 Setup
  50 ~~~~~
  51
  52 Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This
  53 may be done automatically by your distribution.
  54
  55 Driver options
  56 ~~~~~~~~~~~~~~
  57
  58 .. tabularcolumns:: |p{13ex}|L|
  59
  60
  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
  80 line like this:
  81
  82 .. code-block:: none
  83
  84         options cpia2 num_buffers=3 buffer_size=65535
  85
  86 If the driver is compiled into the kernel, at boot time specify them
  87 like this:
  88
  89 .. code-block:: none
  90
  91         cpia2.num_buffers=3 cpia2.buffer_size=65535
  92
  93 What buffer size should I use?
  94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  95
  96 The maximum image size depends on the alternate you choose, and the
  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.
 100
 101 The compression engine starts out at maximum compression, and will
 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.
 105
 106 At low alternate settings, the compression engine may not be able to
 107 compress the image enough and will reduce the frame rate by producing larger
 108 images.
 109
 110 The default of 68k should be good for most users.  This will handle
 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
 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,
 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
 141 Using the camera
 142 ~~~~~~~~~~~~~~~~
 143
 144 We are providing a modified gqcam application to view the output. In
 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
 149 Notes to developers
 150 ~~~~~~~~~~~~~~~~~~~
 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
 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.