Documentation/media/v4l-drivers/philips.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Philips webcams (pwc driver)
   4 ============================
   5
   6 This file contains some additional information for the Philips and OEM webcams.
   7 E-mail: webcam@smcc.demon.nl                        Last updated: 2004-01-19
   8 Site: http://www.smcc.demon.nl/webcam/
   9
  10 As of this moment, the following cameras are supported:
  11
  12  * Philips PCA645
  13  * Philips PCA646
  14  * Philips PCVC675
  15  * Philips PCVC680
  16  * Philips PCVC690
  17  * Philips PCVC720/40
  18  * Philips PCVC730
  19  * Philips PCVC740
  20  * Philips PCVC750
  21  * Askey VC010
  22  * Creative Labs Webcam 5
  23  * Creative Labs Webcam Pro Ex
  24  * Logitech QuickCam 3000 Pro
  25  * Logitech QuickCam 4000 Pro
  26  * Logitech QuickCam Notebook Pro
  27  * Logitech QuickCam Zoom
  28  * Logitech QuickCam Orbit
  29  * Logitech QuickCam Sphere
  30  * Samsung MPC-C10
  31  * Samsung MPC-C30
  32  * Sotec Afina Eye
  33  * AME CU-001
  34  * Visionite VCS-UM100
  35  * Visionite VCS-UC300
  36
  37 The main webpage for the Philips driver is at the address above. It contains
  38 a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin
  39 contains decompression routines that allow you to use higher image sizes and
  40 framerates; in addition the webcam uses less bandwidth on the USB bus (handy
  41 if you want to run more than 1 camera simultaneously). These routines fall
  42 under a NDA, and may therefore not be distributed as source; however, its use
  43 is completely optional.
  44
  45 You can build this code either into your kernel, or as a module. I recommend
  46 the latter, since it makes troubleshooting a lot easier. The built-in
  47 microphone is supported through the USB Audio class.
  48
  49 When you load the module you can set some default settings for the
  50 camera; some programs depend on a particular image-size or -format and
  51 don't know how to set it properly in the driver. The options are:
  52
  53 size
  54    Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or
  55    'vga', for an image size of resp. 128x96, 160x120, 176x144,
  56    320x240, 352x288 and 640x480 (of course, only for those cameras that
  57    support these resolutions).
  58
  59 fps
  60    Specifies the desired framerate. Is an integer in the range of 4-30.
  61
  62 fbufs
  63    This parameter specifies the number of internal buffers to use for storing
  64    frames from the cam. This will help if the process that reads images from
  65    the cam is a bit slow or momentarily busy. However, on slow machines it
  66    only introduces lag, so choose carefully. The default is 3, which is
  67    reasonable. You can set it between 2 and 5.
  68
  69 mbufs
  70    This is an integer between 1 and 10. It will tell the module the number of
  71    buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.
  72    The default is 2, which is adequate for most applications (double
  73    buffering).
  74
  75    Should you experience a lot of 'Dumping frame...' messages during
  76    grabbing with a tool that uses mmap(), you might want to increase if.
  77    However, it doesn't really buffer images, it just gives you a bit more
  78    slack when your program is behind. But you need a multi-threaded or
  79    forked program to really take advantage of these buffers.
  80
  81    The absolute maximum is 10, but don't set it too high!  Every buffer takes
  82    up 460 KB of RAM, so unless you have a lot of memory setting this to
  83    something more than 4 is an absolute waste.  This memory is only
  84    allocated during open(), so nothing is wasted when the camera is not in
  85    use.
  86
  87 power_save
  88    When power_save is enabled (set to 1), the module will try to shut down
  89    the cam on close() and re-activate on open(). This will save power and
  90    turn off the LED. Not all cameras support this though (the 645 and 646
  91    don't have power saving at all), and some models don't work either (they
  92    will shut down, but never wake up). Consider this experimental. By
  93    default this option is disabled.
  94
  95 compression (only useful with the plugin)
  96    With this option you can control the compression factor that the camera
  97    uses to squeeze the image through the USB bus. You can set the
  98    parameter between 0 and 3::
  99
 100      0 = prefer uncompressed images; if the requested mode is not available
 101          in an uncompressed format, the driver will silently switch to low
 102          compression.
 103      1 = low compression.
 104      2 = medium compression.
 105      3 = high compression.
 106
 107    High compression takes less bandwidth of course, but it could also
 108    introduce some unwanted artefacts. The default is 2, medium compression.
 109    See the FAQ on the website for an overview of which modes require
 110    compression.
 111
 112    The compression parameter does not apply to the 645 and 646 cameras
 113    and OEM models derived from those (only a few). Most cams honour this
 114    parameter.
 115
 116 leds
 117    This settings takes 2 integers, that define the on/off time for the LED
 118    (in milliseconds). One of the interesting things that you can do with
 119    this is let the LED blink while the camera is in use. This::
 120
 121      leds=500,500
 122
 123    will blink the LED once every second. But with::
 124
 125      leds=0,0
 126
 127    the LED never goes on, making it suitable for silent surveillance.
 128
 129    By default the camera's LED is on solid while in use, and turned off
 130    when the camera is not used anymore.
 131
 132    This parameter works only with the ToUCam range of cameras (720, 730, 740,
 133    750) and OEMs. For other cameras this command is silently ignored, and
 134    the LED cannot be controlled.
 135
 136    Finally: this parameters does not take effect UNTIL the first time you
 137    open the camera device. Until then, the LED remains on.
 138
 139 dev_hint
 140    A long standing problem with USB devices is their dynamic nature: you
 141    never know what device a camera gets assigned; it depends on module load
 142    order, the hub configuration, the order in which devices are plugged in,
 143    and the phase of the moon (i.e. it can be random). With this option you
 144    can give the driver a hint as to what video device node (/dev/videoX) it
 145    should use with a specific camera. This is also handy if you have two
 146    cameras of the same model.
 147
 148    A camera is specified by its type (the number from the camera model,
 149    like PCA645, PCVC750VC, etc) and optionally the serial number (visible
 150    in /sys/kernel/debug/usb/devices). A hint consists of a string with the
 151    following format::
 152
 153       [type[.serialnumber]:]node
 154
 155    The square brackets mean that both the type and the serialnumber are
 156    optional, but a serialnumber cannot be specified without a type (which
 157    would be rather pointless). The serialnumber is separated from the type
 158    by a '.'; the node number by a ':'.
 159
 160    This somewhat cryptic syntax is best explained by a few examples::
 161
 162      dev_hint=3,5              The first detected cam gets assigned
 163                                /dev/video3, the second /dev/video5. Any
 164                                other cameras will get the first free
 165                                available slot (see below).
 166
 167      dev_hint=645:1,680:2      The PCA645 camera will get /dev/video1,
 168                                and a PCVC680 /dev/video2.
 169
 170      dev_hint=645.0123:3,645.4567:0     The PCA645 camera with serialnumber
 171                                         0123 goes to /dev/video3, the same
 172                                         camera model with the 4567 serial
 173                                         gets /dev/video0.
 174
 175      dev_hint=750:1,4,5,6       The PCVC750 camera will get /dev/video1, the
 176                                 next 3 Philips cams will use /dev/video4
 177                                 through /dev/video6.
 178
 179    Some points worth knowing:
 180
 181    - Serialnumbers are case sensitive and must be written full, including
 182      leading zeroes (it's treated as a string).
 183    - If a device node is already occupied, registration will fail and
 184      the webcam is not available.
 185    - You can have up to 64 video devices; be sure to make enough device
 186      nodes in /dev if you want to spread the numbers.
 187      After /dev/video9 comes /dev/video10 (not /dev/videoA).
 188    - If a camera does not match any dev_hint, it will simply get assigned
 189      the first available device node, just as it used to be.
 190
 191 trace
 192    In order to better detect problems, it is now possible to turn on a
 193    'trace' of some of the calls the module makes; it logs all items in your
 194    kernel log at debug level.
 195
 196    The trace variable is a bitmask; each bit represents a certain feature.
 197    If you want to trace something, look up the bit value(s) in the table
 198    below, add the values together and supply that to the trace variable.
 199
 200    ====== ======= ================================================ =======
 201    Value  Value   Description                                      Default
 202    (dec)  (hex)
 203    ====== ======= ================================================ =======
 204        1    0x1   Module initialization; this will log messages       On
 205                   while loading and unloading the module
 206
 207        2    0x2   probe() and disconnect() traces                     On
 208
 209        4    0x4   Trace open() and close() calls                      Off
 210
 211        8    0x8   read(), mmap() and associated ioctl() calls         Off
 212
 213       16   0x10   Memory allocation of buffers, etc.                  Off
 214
 215       32   0x20   Showing underflow, overflow and Dumping frame       On
 216                   messages
 217
 218       64   0x40   Show viewport and image sizes                       Off
 219
 220      128   0x80   PWCX debugging                                      Off
 221    ====== ======= ================================================ =======
 222
 223    For example, to trace the open() & read() functions, sum 8 + 4 = 12,
 224    so you would supply trace=12 during insmod or modprobe. If
 225    you want to turn the initialization and probing tracing off, set trace=0.
 226    The default value for trace is 35 (0x23).
 227
 228
 229
 230 Example::
 231
 232      # modprobe pwc size=cif fps=15 power_save=1
 233
 234 The fbufs, mbufs and trace parameters are global and apply to all connected
 235 cameras. Each camera has its own set of buffers.
 236
 237 size and fps only specify defaults when you open() the device; this is to
 238 accommodate some tools that don't set the size. You can change these
 239 settings after open() with the Video4Linux ioctl() calls. The default of
 240 defaults is QCIF size at 10 fps.
 241
 242 The compression parameter is semiglobal; it sets the initial compression
 243 preference for all camera's, but this parameter can be set per camera with
 244 the VIDIOCPWCSCQUAL ioctl() call.
 245
 246 All parameters are optional.
 247