요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
Philips webcams (pwc driver)
============================
This file contains some additional information for the Philips and OEM webcams.
E-mail: webcam@smcc.demon.nl Last updated: 2004-01-19
Site: http://www.smcc.demon.nl/webcam/
As of this moment, the following cameras are supported:
* Philips PCA645
* Philips PCA646
* Philips PCVC675
* Philips PCVC680
* Philips PCVC690
* Philips PCVC720/40
* Philips PCVC730
* Philips PCVC740
* Philips PCVC750
* Askey VC010
* Creative Labs Webcam 5
* Creative Labs Webcam Pro Ex
* Logitech QuickCam 3000 Pro
* Logitech QuickCam 4000 Pro
* Logitech QuickCam Notebook Pro
* Logitech QuickCam Zoom
* Logitech QuickCam Orbit
* Logitech QuickCam Sphere
* Samsung MPC-C10
* Samsung MPC-C30
* Sotec Afina Eye
* AME CU-001
* Visionite VCS-UM100
* Visionite VCS-UC300
The main webpage for the Philips driver is at the address above. It contains
a lot of extra information, a FAQ, and the binary plugin 'PWCX'. This plugin
contains decompression routines that allow you to use higher image sizes and
framerates; in addition the webcam uses less bandwidth on the USB bus (handy
if you want to run more than 1 camera simultaneously). These routines fall
under a NDA, and may therefore not be distributed as source; however, its use
is completely optional.
You can build this code either into your kernel, or as a module. I recommend
the latter, since it makes troubleshooting a lot easier. The built-in
microphone is supported through the USB Audio class.
When you load the module you can set some default settings for the
camera; some programs depend on a particular image-size or -format and
don't know how to set it properly in the driver. The options are:
size
Can be one of 'sqcif', 'qsif', 'qcif', 'sif', 'cif' or
'vga', for an image size of resp. 128x96, 160x120, 176x144,
320x240, 352x288 and 640x480 (of course, only for those cameras that
support these resolutions).
fps
Specifies the desired framerate. Is an integer in the range of 4-30.
fbufs
This parameter specifies the number of internal buffers to use for storing
frames from the cam. This will help if the process that reads images from
the cam is a bit slow or momentarily busy. However, on slow machines it
only introduces lag, so choose carefully. The default is 3, which is
reasonable. You can set it between 2 and 5.
mbufs
This is an integer between 1 and 10. It will tell the module the number of
buffers to reserve for mmap(), VIDIOCCGMBUF, VIDIOCMCAPTURE and friends.
The default is 2, which is adequate for most applications (double
buffering).
Should you experience a lot of 'Dumping frame...' messages during
grabbing with a tool that uses mmap(), you might want to increase if.
However, it doesn't really buffer images, it just gives you a bit more
slack when your program is behind. But you need a multi-threaded or
forked program to really take advantage of these buffers.
The absolute maximum is 10, but don't set it too high! Every buffer takes
up 460 KB of RAM, so unless you have a lot of memory setting this to
something more than 4 is an absolute waste. This memory is only
allocated during open(), so nothing is wasted when the camera is not in
use.
power_save
When power_save is enabled (set to 1), the module will try to shut down
the cam on close() and re-activate on open(). This will save power and
turn off the LED. Not all cameras support this though (the 645 and 646
don't have power saving at all), and some models don't work either (they
will shut down, but never wake up). Consider this experimental. By
default this option is disabled.
compression (only useful with the plugin)
With this option you can control the compression factor that the camera
uses to squeeze the image through the USB bus. You can set the
parameter between 0 and 3::
0 = prefer uncompressed images; if the requested mode is not available
in an uncompressed format, the driver will silently switch to low
compression.
1 = low compression.
2 = medium compression.
3 = high compression.
High compression takes less bandwidth of course, but it could also
introduce some unwanted artefacts. The default is 2, medium compression.
See the FAQ on the website for an overview of which modes require
compression.
The compression parameter does not apply to the 645 and 646 cameras
and OEM models derived from those (only a few). Most cams honour this
parameter.
leds
This settings takes 2 integers, that define the on/off time for the LED
(in milliseconds). One of the interesting things that you can do with
this is let the LED blink while the camera is in use. This::
leds=500,500
will blink the LED once every second. But with::
leds=0,0
the LED never goes on, making it suitable for silent surveillance.
By default the camera's LED is on solid while in use, and turned off
when the camera is not used anymore.
This parameter works only with the ToUCam range of cameras (720, 730, 740,
750) and OEMs. For other cameras this command is silently ignored, and
the LED cannot be controlled.
Finally: this parameters does not take effect UNTIL the first time you
open the camera device. Until then, the LED remains on.
dev_hint
A long standing problem with USB devices is their dynamic nature: you
never know what device a camera gets assigned; it depends on module load
order, the hub configuration, the order in which devices are plugged in,
and the phase of the moon (i.e. it can be random). With this option you
can give the driver a hint as to what video device node (/dev/videoX) it
should use with a specific camera. This is also handy if you have two
cameras of the same model.
A camera is specified by its type (the number from the camera model,
like PCA645, PCVC750VC, etc) and optionally the serial number (visible
in /sys/kernel/debug/usb/devices). A hint consists of a string with the
following format::
[type[.serialnumber]:]node
The square brackets mean that both the type and the serialnumber are
optional, but a serialnumber cannot be specified without a type (which
would be rather pointless). The serialnumber is separated from the type
by a '.'; the node number by a ':'.
This somewhat cryptic syntax is best explained by a few examples::
dev_hint=3,5 The first detected cam gets assigned
/dev/video3, the second /dev/video5. Any
other cameras will get the first free
available slot (see below).
dev_hint=645:1,680:2 The PCA645 camera will get /dev/video1,
and a PCVC680 /dev/video2.
dev_hint=645.0123:3,645.4567:0 The PCA645 camera with serialnumber
0123 goes to /dev/video3, the same
camera model with the 4567 serial
gets /dev/video0.
dev_hint=750:1,4,5,6 The PCVC750 camera will get /dev/video1, the
next 3 Philips cams will use /dev/video4
through /dev/video6.
Some points worth knowing:
- Serialnumbers are case sensitive and must be written full, including
leading zeroes (it's treated as a string).
- If a device node is already occupied, registration will fail and
the webcam is not available.
- You can have up to 64 video devices; be sure to make enough device
nodes in /dev if you want to spread the numbers.
After /dev/video9 comes /dev/video10 (not /dev/videoA).
- If a camera does not match any dev_hint, it will simply get assigned
the first available device node, just as it used to be.
trace
In order to better detect problems, it is now possible to turn on a
'trace' of some of the calls the module makes; it logs all items in your
kernel log at debug level.
The trace variable is a bitmask; each bit represents a certain feature.
If you want to trace something, look up the bit value(s) in the table
below, add the values together and supply that to the trace variable.
====== ======= ================================================ =======
Value Value Description Default
(dec) (hex)
====== ======= ================================================ =======
1 0x1 Module initialization; this will log messages On
while loading and unloading the module
2 0x2 probe() and disconnect() traces On
4 0x4 Trace open() and close() calls Off
8 0x8 read(), mmap() and associated ioctl() calls Off
16 0x10 Memory allocation of buffers, etc. Off
32 0x20 Showing underflow, overflow and Dumping frame On
messages
64 0x40 Show viewport and image sizes Off
128 0x80 PWCX debugging Off
====== ======= ================================================ =======
For example, to trace the open() & read() functions, sum 8 + 4 = 12,
so you would supply trace=12 during insmod or modprobe. If
you want to turn the initialization and probing tracing off, set trace=0.
The default value for trace is 35 (0x23).
Example::
# modprobe pwc size=cif fps=15 power_save=1
The fbufs, mbufs and trace parameters are global and apply to all connected
cameras. Each camera has its own set of buffers.
size and fps only specify defaults when you open() the device; this is to
accommodate some tools that don't set the size. You can change these
settings after open() with the Video4Linux ioctl() calls. The default of
defaults is QCIF size at 10 fps.
The compression parameter is semiglobal; it sets the initial compression
preference for all camera's, but this parameter can be set per camera with
the VIDIOCPWCSCQUAL ioctl() call.
All parameters are optional.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Philips 웹캠과 pwc 드라이버
1-9이 문서는 GPL-2.0 라이선스를 따르며 Philips 및 OEM 웹캠용 `pwc` 드라이버의 추가 정보를 제공합니다. 연락처는 webcam@smcc.demon.nl이고 마지막 갱신일은 2004-01-19입니다.
지원 카메라와 PWCX
10-47문서가 명시하는 지원 카메라는 다음 24종입니다.
- Philips PCA645
- Philips PCA646
- Philips PCVC675
- Philips PCVC680
- Philips PCVC690
- Philips PCVC720/40
- Philips PCVC730
- Philips PCVC740
- Philips PCVC750
- Askey VC010
- Creative Labs Webcam 5
- Creative Labs Webcam Pro Ex
- Logitech QuickCam 3000 Pro
- Logitech QuickCam 4000 Pro
- Logitech QuickCam Notebook Pro
- Logitech QuickCam Zoom
- Logitech QuickCam Orbit
- Logitech QuickCam Sphere
- Samsung MPC-C10
- Samsung MPC-C30
- Sotec Afina Eye
- AME CU-001
- Visionite VCS-UM100
- Visionite VCS-UC300
위 웹사이트에는 추가 정보, FAQ 및 binary plugin `PWCX`가 있습니다. 이 plugin의 decompression routine을 사용하면 더 큰 image size와 frame rate를 쓸 수 있고, USB bus bandwidth도 덜 사용하므로 여러 카메라를 동시에 운용할 때 유용합니다.
`PWCX` routine은 NDA 적용 대상이어서 source로 배포할 수 없습니다. 하지만 plugin 사용은 완전히 선택 사항입니다.
드라이버는 커널에 built-in으로 넣거나 module로 빌드할 수 있습니다. 문서는 문제 해결이 쉬운 module 방식을 권장합니다. 내장 microphone은 USB Audio class를 통해 지원됩니다.
size, fps, fbufs
48-67Module을 로드할 때 카메라의 기본 설정을 지정할 수 있습니다. 일부 프로그램은 특정 image size나 format을 요구하면서도 이를 드라이버에 올바르게 설정하지 못하므로 이 기본값이 필요합니다.
`size`는 `sqcif`, `qsif`, `qcif`, `sif`, `cif`, `vga` 중 하나이며 각각 128x96, 160x120, 176x144, 320x240, 352x288, 640x480입니다. 카메라가 해당 해상도를 지원해야 사용할 수 있습니다.
`fps`는 원하는 frame rate이며 4부터 30까지의 정수입니다.
`fbufs`는 카메라 frame을 저장하는 내부 buffer 수입니다. 읽기 프로세스가 잠시 느리거나 바쁠 때 도움이 되지만 느린 시스템에서는 지연만 늘릴 수 있습니다. 범위는 2-5이고 기본값 3이 합리적입니다.
mbufs와 power_save
68-94`mbufs`는 `mmap()`, `VIDIOCCGMBUF`, `VIDIOCMCAPTURE` 및 관련 작업에 예약할 buffer 수로 1-10 사이의 정수입니다. 기본값 2는 대부분의 응용 프로그램에 적합한 double buffering입니다.
`mmap()`을 사용하는 캡처 도구에서 `Dumping frame...` 메시지가 많으면 `mbufs`를 늘릴 수 있습니다. 이 값은 실제 image를 buffering하기보다 프로그램이 뒤처졌을 때 여유를 주며, 이점을 활용하려면 multi-threaded 또는 forked 프로그램이 필요합니다.
`mbufs`의 절대 최댓값은 10이지만 각 buffer가 RAM 460 KB를 사용하므로 4보다 크게 잡는 것은 대개 낭비입니다. 메모리는 `open()` 중에만 할당되어 카메라를 사용하지 않을 때는 소비되지 않습니다.
`power_save=1`이면 module은 `close()`에서 카메라를 종료하고 `open()`에서 다시 활성화해 전력을 절약하고 LED를 끕니다. 645와 646은 전원 절약을 지원하지 않으며 일부 모델은 종료 후 깨어나지 않습니다. 실험적 기능이고 기본값은 비활성입니다.
compression
95-115`compression`은 PWCX plugin을 사용할 때만 유용하며, image를 USB bus로 전송하기 위해 카메라가 사용하는 압축 계수를 0-3으로 제어합니다.
0 = prefer uncompressed images; if the requested mode is not available
in an uncompressed format, the driver will silently switch to low
compression.
1 = low compression.
2 = medium compression.
3 = high compression.압축률이 높으면 bandwidth 사용량이 줄지만 원하지 않는 artefact가 생길 수 있습니다. 기본값은 medium compression인 2이며, 어떤 mode에 압축이 필요한지는 웹사이트 FAQ에서 확인할 수 있습니다.
`compression`은 645와 646 카메라 및 여기서 파생된 일부 OEM 모델에는 적용되지 않습니다. 그 밖의 대부분 카메라는 이 값을 따릅니다.
leds
116-138`leds`는 LED의 on/off 시간을 millisecond 단위 정수 두 개로 받습니다. 다음 값은 카메라 사용 중 LED를 1초마다 한 번 깜박이게 합니다.
leds=500,500다음 값은 LED가 전혀 켜지지 않게 합니다.
leds=0,0기본 동작은 카메라 사용 중 LED를 계속 켜고, 사용이 끝나면 끄는 것입니다. 이 매개변수는 ToUCam 720, 730, 740, 750 및 OEM 모델에서만 동작합니다. 다른 카메라에서는 조용히 무시되며 LED를 제어할 수 없습니다.
`leds`는 카메라 device를 처음 `open()`할 때까지 적용되지 않습니다. 그 전에는 LED가 켜진 상태로 남습니다.
dev_hint
139-190USB device는 module load 순서, hub 구성, 연결 순서 등에 따라 동적으로 번호가 달라질 수 있습니다. `dev_hint`는 특정 카메라가 사용할 video device node(`/dev/videoX`)를 드라이버에 알려 주며, 같은 모델 카메라가 두 대일 때도 유용합니다.
카메라는 PCA645나 PCVC750VC 같은 model number인 type과 선택적인 serial number로 지정합니다. Serial number는 `/sys/kernel/debug/usb/devices`에서 확인할 수 있습니다. 형식은 다음과 같습니다.
[type[.serialnumber]:]node대괄호는 type과 serial number가 모두 선택적임을 뜻하지만, type 없이 serial number만 지정할 수는 없습니다. Serial number는 type과 `.`으로, node number는 `:`으로 구분합니다.
다음 예제는 감지 순서, model, serial number를 이용한 배정을 보여 줍니다.
dev_hint=3,5 The first detected cam gets assigned
/dev/video3, the second /dev/video5. Any
other cameras will get the first free
available slot (see below).
dev_hint=645:1,680:2 The PCA645 camera will get /dev/video1,
and a PCVC680 /dev/video2.
dev_hint=645.0123:3,645.4567:0 The PCA645 camera with serialnumber
0123 goes to /dev/video3, the same
camera model with the 4567 serial
gets /dev/video0.
dev_hint=750:1,4,5,6 The PCVC750 camera will get /dev/video1, the
next 3 Philips cams will use /dev/video4
through /dev/video6.- Serial number는 대소문자를 구분하며 앞쪽 0을 포함한 전체 문자열을 써야 합니다.
- Device node가 이미 사용 중이면 등록이 실패해 webcam을 사용할 수 없습니다.
- Video device는 최대 64개이며 번호를 분산하려면 `/dev`에 충분한 node를 만들어야 합니다.
- `/dev/video9` 다음은 `/dev/videoA`가 아니라 `/dev/video10`입니다.
- 어떤 `dev_hint`와도 일치하지 않는 카메라는 첫 번째 사용 가능한 device node를 받습니다.
trace bitmask
191-229문제 감지를 돕기 위해 module 호출 일부의 `trace`를 켤 수 있으며, 모든 항목은 kernel log의 debug level로 기록됩니다. `trace` 변수는 bitmask이고 각 bit가 기능 하나를 나타냅니다. 원하는 항목의 값을 더해 `trace`에 전달합니다.
| Value (dec) | Value (hex) | Description | Default |
|---|---|---|---|
| 1 | 0x1 | Module initialization; this will log messages while loading and unloading the module | On |
| 2 | 0x2 | probe() and disconnect() traces | On |
| 4 | 0x4 | Trace open() and close() calls | Off |
| 8 | 0x8 | read(), mmap() and associated ioctl() calls | Off |
| 16 | 0x10 | Memory allocation of buffers, etc. | Off |
| 32 | 0x20 | Showing underflow, overflow and Dumping frame messages | On |
| 64 | 0x40 | Show viewport and image sizes | Off |
| 128 | 0x80 | PWCX debugging | Off |
예를 들어 `open()`과 `read()`를 추적하려면 4와 8을 더해 `trace=12`를 `insmod` 또는 `modprobe`에 전달합니다. 초기화와 probe 추적을 모두 끄려면 `trace=0`을 사용합니다. 기본값은 35(`0x23`)입니다.
Module load 예제와 적용 범위
230-247다음은 CIF, 15 fps, power saving을 선택해 module을 로드하는 예입니다.
# modprobe pwc size=cif fps=15 power_save=1`fbufs`, `mbufs`, `trace`는 global 매개변수로 연결된 모든 카메라에 적용되지만 각 카메라는 자체 buffer 집합을 갖습니다.
`size`와 `fps`는 device를 `open()`할 때의 기본값만 지정합니다. 이후 Video4Linux `ioctl()` 호출로 바꿀 수 있으며, 아무 값도 지정하지 않았을 때의 기본값은 QCIF 10 fps입니다.
`compression`은 semiglobal입니다. 모든 카메라의 초기 압축 선호도를 설정하지만 `VIDIOCPWCSCQUAL` `ioctl()`로 카메라마다 바꿀 수 있습니다. 모든 매개변수는 선택 사항입니다.
pwc 설정 지도
philips.rst:1-247`pwc`는 Philips 및 여러 OEM USB webcam을 지원합니다. Module load 기본값으로 해상도와 frame rate를 정하고, buffer·power saving·compression·LED·device node·trace 동작을 조정할 수 있습니다.
Module 공통 설정과 카메라별 초기값은 적용 시점과 범위가 서로 다릅니다.