1.. SPDX-License-Identifier: GPL-2.0
2
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-19
8Site: http://www.smcc.demon.nl/webcam/
9
10As 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
37The main webpage for the Philips driver is at the address above. It contains
38a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin
39contains decompression routines that allow you to use higher image sizes and
40framerates; in addition the webcam uses less bandwidth on the USB bus (handy
41if you want to run more than 1 camera simultaneously). These routines fall
42under a NDA, and may therefore not be distributed as source; however, its use
43is completely optional.
44
45You can build this code either into your kernel, or as a module. I recommend
46the latter, since it makes troubleshooting a lot easier. The built-in
47microphone is supported through the USB Audio class.
48
49When you load the module you can set some default settings for the
50camera; some programs depend on a particular image-size or -format and
51don't know how to set it properly in the driver. The options are:
52
53size
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
59fps
60   Specifies the desired framerate. Is an integer in the range of 4-30.
61
62fbufs
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
69mbufs
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
87power_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
95compression (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
116leds
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
139dev_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
191trace
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
230Example::
231
232     # modprobe pwc size=cif fps=15 power_save=1
233
234The fbufs, mbufs and trace parameters are global and apply to all connected
235cameras. Each camera has its own set of buffers.
236
237size and fps only specify defaults when you open() the device; this is to
238accommodate some tools that don't set the size. You can change these
239settings after open() with the Video4Linux ioctl() calls. The default of
240defaults is QCIF size at 10 fps.
241
242The compression parameter is semiglobal; it sets the initial compression
243preference for all camera's, but this parameter can be set per camera with
244the VIDIOCPWCSCQUAL ioctl() call.
245
246All parameters are optional.
247
248