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