248 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Philips webcams (pwc driver)4============================5 6This file contains some additional information for the Philips and OEM webcams.7E-mail: webcam@smcc.demon.nl Last updated: 2004-01-198Site: http://www.smcc.demon.nl/webcam/9 10As of this moment, the following cameras are supported:11 12 * Philips PCA64513 * Philips PCA64614 * Philips PCVC67515 * Philips PCVC68016 * Philips PCVC69017 * Philips PCVC720/4018 * Philips PCVC73019 * Philips PCVC74020 * Philips PCVC75021 * Askey VC01022 * Creative Labs Webcam 523 * Creative Labs Webcam Pro Ex24 * Logitech QuickCam 3000 Pro25 * Logitech QuickCam 4000 Pro26 * Logitech QuickCam Notebook Pro27 * Logitech QuickCam Zoom28 * Logitech QuickCam Orbit29 * Logitech QuickCam Sphere30 * Samsung MPC-C1031 * Samsung MPC-C3032 * Sotec Afina Eye33 * AME CU-00134 * Visionite VCS-UM10035 * Visionite VCS-UC30036 37The main webpage for the Philips driver is at the address above. It contains38a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin39contains decompression routines that allow you to use higher image sizes and40framerates; in addition the webcam uses less bandwidth on the USB bus (handy41if you want to run more than 1 camera simultaneously). These routines fall42under a NDA, and may therefore not be distributed as source; however, its use43is completely optional.44 45You can build this code either into your kernel, or as a module. I recommend46the latter, since it makes troubleshooting a lot easier. The built-in47microphone is supported through the USB Audio class.48 49When you load the module you can set some default settings for the50camera; some programs depend on a particular image-size or -format and51don't know how to set it properly in the driver. The options are:52 53size54 Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or55 'vga', for an image size of resp. 128x96, 160x120, 176x144,56 320x240, 352x288 and 640x480 (of course, only for those cameras that57 support these resolutions).58 59fps60 Specifies the desired framerate. Is an integer in the range of 4-30.61 62fbufs63 This parameter specifies the number of internal buffers to use for storing64 frames from the cam. This will help if the process that reads images from65 the cam is a bit slow or momentarily busy. However, on slow machines it66 only introduces lag, so choose carefully. The default is 3, which is67 reasonable. You can set it between 2 and 5.68 69mbufs70 This is an integer between 1 and 10. It will tell the module the number of71 buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.72 The default is 2, which is adequate for most applications (double73 buffering).74 75 Should you experience a lot of 'Dumping frame...' messages during76 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 more78 slack when your program is behind. But you need a multi-threaded or79 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 takes82 up 460 KB of RAM, so unless you have a lot of memory setting this to83 something more than 4 is an absolute waste. This memory is only84 allocated during open(), so nothing is wasted when the camera is not in85 use.86 87power_save88 When power_save is enabled (set to 1), the module will try to shut down89 the cam on close() and re-activate on open(). This will save power and90 turn off the LED. Not all cameras support this though (the 645 and 64691 don't have power saving at all), and some models don't work either (they92 will shut down, but never wake up). Consider this experimental. By93 default this option is disabled.94 95compression (only useful with the plugin)96 With this option you can control the compression factor that the camera97 uses to squeeze the image through the USB bus. You can set the98 parameter between 0 and 3::99 100 0 = prefer uncompressed images; if the requested mode is not available101 in an uncompressed format, the driver will silently switch to low102 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 also108 introduce some unwanted artefacts. The default is 2, medium compression.109 See the FAQ on the website for an overview of which modes require110 compression.111 112 The compression parameter does not apply to the 645 and 646 cameras113 and OEM models derived from those (only a few). Most cams honour this114 parameter.115 116leds117 This settings takes 2 integers, that define the on/off time for the LED118 (in milliseconds). One of the interesting things that you can do with119 this is let the LED blink while the camera is in use. This::120 121 leds=500,500122 123 will blink the LED once every second. But with::124 125 leds=0,0126 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 off130 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, and134 the LED cannot be controlled.135 136 Finally: this parameters does not take effect UNTIL the first time you137 open the camera device. Until then, the LED remains on.138 139dev_hint140 A long standing problem with USB devices is their dynamic nature: you141 never know what device a camera gets assigned; it depends on module load142 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 you144 can give the driver a hint as to what video device node (/dev/videoX) it145 should use with a specific camera. This is also handy if you have two146 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 (visible150 in /sys/kernel/debug/usb/devices). A hint consists of a string with the151 following format::152 153 [type[.serialnumber]:]node154 155 The square brackets mean that both the type and the serialnumber are156 optional, but a serialnumber cannot be specified without a type (which157 would be rather pointless). The serialnumber is separated from the type158 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 assigned163 /dev/video3, the second /dev/video5. Any164 other cameras will get the first free165 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 serialnumber171 0123 goes to /dev/video3, the same172 camera model with the 4567 serial173 gets /dev/video0.174 175 dev_hint=750:1,4,5,6 The PCVC750 camera will get /dev/video1, the176 next 3 Philips cams will use /dev/video4177 through /dev/video6.178 179 Some points worth knowing:180 181 - Serialnumbers are case sensitive and must be written full, including182 leading zeroes (it's treated as a string).183 - If a device node is already occupied, registration will fail and184 the webcam is not available.185 - You can have up to 64 video devices; be sure to make enough device186 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 assigned189 the first available device node, just as it used to be.190 191trace192 In order to better detect problems, it is now possible to turn on a193 'trace' of some of the calls the module makes; it logs all items in your194 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 table198 below, add the values together and supply that to the trace variable.199 200 ====== ======= ================================================ =======201 Value Value Description Default202 (dec) (hex)203 ====== ======= ================================================ =======204 1 0x1 Module initialization; this will log messages On205 while loading and unloading the module206 207 2 0x2 probe() and disconnect() traces On208 209 4 0x4 Trace open() and close() calls Off210 211 8 0x8 read(), mmap() and associated ioctl() calls Off212 213 16 0x10 Memory allocation of buffers, etc. Off214 215 32 0x20 Showing underflow, overflow and Dumping frame On216 messages217 218 64 0x40 Show viewport and image sizes Off219 220 128 0x80 PWCX debugging Off221 ====== ======= ================================================ =======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. If225 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 230Example::231 232 # modprobe pwc size=cif fps=15 power_save=1233 234The fbufs, mbufs and trace parameters are global and apply to all connected235cameras. Each camera has its own set of buffers.236 237size and fps only specify defaults when you open() the device; this is to238accommodate some tools that don't set the size. You can change these239settings after open() with the Video4Linux ioctl() calls. The default of240defaults is QCIF size at 10 fps.241 242The compression parameter is semiglobal; it sets the initial compression243preference for all camera's, but this parameter can be set per camera with244the VIDIOCPWCSCQUAL ioctl() call.245 246All parameters are optional.247 248