mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-24 21:24:00 +08:00
0ea6e61122
Below you will find an updated version from the original series bunching all patches into one big patch updating broken web addresses that are located in Documentation/* Some of the addresses date as far far back as 1995 etc... so searching became a bit difficult, the best way to deal with these is to use web.archive.org to locate these addresses that are outdated. Now there are also some addresses pointing to .spec files some are located, but some(after searching on the companies site)where still no where to be found. In this case I just changed the address to the company site this way the users can contact the company and they can locate them for the users. Signed-off-by: Justin P. Mattock <justinmattock@gmail.com> Signed-off-by: Thomas Weber <weber@corscience.de> Signed-off-by: Mike Frysinger <vapier.adi@gmail.com> Cc: Paulo Marques <pmarques@grupopie.com> Cc: Randy Dunlap <rdunlap@xenotime.net> Cc: Michael Neuling <mikey@neuling.org> Signed-off-by: Jiri Kosina <jkosina@suse.cz>
324 lines
14 KiB
Plaintext
324 lines
14 KiB
Plaintext
README for Linux device driver for the IBM "C-It" USB video camera
|
|
|
|
INTRODUCTION:
|
|
|
|
This driver does not use all features known to exist in
|
|
the IBM camera. However most of needed features work well.
|
|
|
|
This driver was developed using logs of observed USB traffic
|
|
which was produced by standard Windows driver (c-it98.sys).
|
|
I did not have data sheets from Xirlink.
|
|
|
|
Video formats:
|
|
128x96 [model 1]
|
|
176x144
|
|
320x240 [model 2]
|
|
352x240 [model 2]
|
|
352x288
|
|
Frame rate: 3 - 30 frames per second (FPS)
|
|
External interface: USB
|
|
Internal interface: Video For Linux (V4L)
|
|
Supported controls:
|
|
- by V4L: Contrast, Brightness, Color, Hue
|
|
- by driver options: frame rate, lighting conditions, video format,
|
|
default picture settings, sharpness.
|
|
|
|
SUPPORTED CAMERAS:
|
|
|
|
Xirlink "C-It" camera, also known as "IBM PC Camera".
|
|
The device uses proprietary ASIC (and compression method);
|
|
it is manufactured by Xirlink. See http://xirlinkwebcam.sourceforge.net,
|
|
http://www.ibmpccamera.com, or http://www.c-itnow.com/ for details and pictures.
|
|
|
|
This very chipset ("X Chip", as marked at the factory)
|
|
is used in several other cameras, and they are supported
|
|
as well:
|
|
|
|
- IBM NetCamera
|
|
- Veo Stingray
|
|
|
|
The Linux driver was developed with camera with following
|
|
model number (or FCC ID): KSX-XVP510. This camera has three
|
|
interfaces, each with one endpoint (control, iso, iso). This
|
|
type of cameras is referred to as "model 1". These cameras are
|
|
no longer manufactured.
|
|
|
|
Xirlink now manufactures new cameras which are somewhat different.
|
|
In particular, following models [FCC ID] belong to that category:
|
|
|
|
XVP300 [KSX-X9903]
|
|
XVP600 [KSX-X9902]
|
|
XVP610 [KSX-X9902]
|
|
|
|
(see http://www.xirlink.com/ibmpccamera/ for updates, they refer
|
|
to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
|
|
These cameras have two interfaces, one endpoint in each (iso, bulk).
|
|
Such type of cameras is referred to as "model 2". They are supported
|
|
(with exception of 352x288 native mode).
|
|
|
|
Some IBM NetCameras (Model 4) are made to generate only compressed
|
|
video streams. This is great for performance, but unfortunately
|
|
nobody knows how to decompress the stream :-( Therefore, these
|
|
cameras are *unsupported* and if you try to use one of those, all
|
|
you get is random colored horizontal streaks, not the image!
|
|
If you have one of those cameras, you probably should return it
|
|
to the store and get something that is supported.
|
|
|
|
Tell me more about all that "model" business
|
|
--------------------------------------------
|
|
|
|
I just invented model numbers to uniquely identify flavors of the
|
|
hardware/firmware that were sold. It was very confusing to use
|
|
brand names or some other internal numbering schemes. So I found
|
|
by experimentation that all Xirlink chipsets fall into four big
|
|
classes, and I called them "models". Each model is programmed in
|
|
its own way, and each model sends back the video in its own way.
|
|
|
|
Quirks of Model 2 cameras:
|
|
-------------------------
|
|
|
|
Model 2 does not have hardware contrast control. Corresponding V4L
|
|
control is implemented in software, which is not very nice to your
|
|
CPU, but at least it works.
|
|
|
|
This driver provides 352x288 mode by switching the camera into
|
|
quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
|
|
this mode to 10 frames per second or less, in ideal conditions on
|
|
the bus (USB is shared, after all). The frame rate
|
|
has to be programmed very conservatively. Additional concern is that
|
|
frame rate depends on brightness setting; therefore the picture can
|
|
be good at one brightness and broken at another! I did not want to fix
|
|
the frame rate at slowest setting, but I had to move it pretty much down
|
|
the scale (so that framerate option barely matters). I also noticed that
|
|
camera after first powering up produces frames slightly faster than during
|
|
consecutive uses. All this means that if you use 352x288 (which is
|
|
default), be warned - you may encounter broken picture on first connect;
|
|
try to adjust brightness - brighter image is slower, so USB will be able
|
|
to send all data. However if you regularly use Model 2 cameras you may
|
|
prefer 176x144 which makes perfectly good I420, with no scaling and
|
|
lesser demands on USB (300 Kbits per second, or 26 frames per second).
|
|
|
|
Another strange effect of 352x288 mode is the fine vertical grid visible
|
|
on some colored surfaces. I am sure it is caused by me not understanding
|
|
what the camera is trying to say. Blame trade secrets for that.
|
|
|
|
The camera that I had also has a hardware quirk: if disconnected,
|
|
it needs few minutes to "relax" before it can be plugged in again
|
|
(poorly designed USB processor reset circuit?)
|
|
|
|
[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
|
|
observed this particular flaw in it.]
|
|
|
|
Model 2 camera can be programmed for very high sensitivity (even starlight
|
|
may be enough), this makes it convenient for tinkering with. The driver
|
|
code has enough comments to help a programmer to tweak the camera
|
|
as s/he feels necessary.
|
|
|
|
WHAT YOU NEED:
|
|
|
|
- A supported IBM PC (C-it) camera (model 1 or 2)
|
|
|
|
- A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)
|
|
|
|
- A Video4Linux compatible frame grabber program such as xawtv.
|
|
|
|
HOW TO COMPILE THE DRIVER:
|
|
|
|
You need to compile the driver only if you are a developer
|
|
or if you want to make changes to the code. Most distributions
|
|
precompile all modules, so you can go directly to the next
|
|
section "HOW TO USE THE DRIVER".
|
|
|
|
The ibmcam driver uses usbvideo helper library (module),
|
|
so if you are studying the ibmcam code you will be led there.
|
|
|
|
The driver itself consists of only one file in usb/ directory:
|
|
ibmcam.c. This file is included into the Linux kernel build
|
|
process if you configure the kernel for CONFIG_USB_IBMCAM.
|
|
Run "make xconfig" and in USB section you will find the IBM
|
|
camera driver. Select it, save the configuration and recompile.
|
|
|
|
HOW TO USE THE DRIVER:
|
|
|
|
I recommend to compile driver as a module. This gives you an
|
|
easier access to its configuration. The camera has many more
|
|
settings than V4L can operate, so some settings are done using
|
|
module options.
|
|
|
|
To begin with, on most modern Linux distributions the driver
|
|
will be automatically loaded whenever you plug the supported
|
|
camera in. Therefore, you don't need to do anything. However
|
|
if you want to experiment with some module parameters then
|
|
you can load and unload the driver manually, with camera
|
|
plugged in or unplugged.
|
|
|
|
Typically module is installed with command 'modprobe', like this:
|
|
|
|
# modprobe ibmcam framerate=1
|
|
|
|
Alternatively you can use 'insmod' in similar fashion:
|
|
|
|
# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
|
|
|
|
Module can be inserted with camera connected or disconnected.
|
|
|
|
The driver can have options, though some defaults are provided.
|
|
|
|
Driver options: (* indicates that option is model-dependent)
|
|
|
|
Name Type Range [default] Example
|
|
-------------- -------------- -------------- ------------------
|
|
debug Integer 0-9 [0] debug=1
|
|
flags Integer 0-0xFF [0] flags=0x0d
|
|
framerate Integer 0-6 [2] framerate=1
|
|
hue_correction Integer 0-255 [128] hue_correction=115
|
|
init_brightness Integer 0-255 [128] init_brightness=100
|
|
init_contrast Integer 0-255 [192] init_contrast=200
|
|
init_color Integer 0-255 [128] init_color=130
|
|
init_hue Integer 0-255 [128] init_hue=115
|
|
lighting Integer 0-2* [1] lighting=2
|
|
sharpness Integer 0-6* [4] sharpness=3
|
|
size Integer 0-2* [2] size=1
|
|
|
|
Options for Model 2 only:
|
|
|
|
Name Type Range [default] Example
|
|
-------------- -------------- -------------- ------------------
|
|
init_model2_rg Integer 0..255 [0x70] init_model2_rg=128
|
|
init_model2_rg2 Integer 0..255 [0x2f] init_model2_rg2=50
|
|
init_model2_sat Integer 0..255 [0x34] init_model2_sat=65
|
|
init_model2_yb Integer 0..255 [0xa0] init_model2_yb=200
|
|
|
|
debug You don't need this option unless you are a developer.
|
|
If you are a developer then you will see in the code
|
|
what values do what. 0=off.
|
|
|
|
flags This is a bit mask, and you can combine any number of
|
|
bits to produce what you want. Usually you don't want
|
|
any of extra features this option provides:
|
|
|
|
FLAGS_RETRY_VIDIOCSYNC 1 This bit allows to retry failed
|
|
VIDIOCSYNC ioctls without failing.
|
|
Will work with xawtv, will not
|
|
with xrealproducer. Default is
|
|
not set.
|
|
FLAGS_MONOCHROME 2 Activates monochrome (b/w) mode.
|
|
FLAGS_DISPLAY_HINTS 4 Shows colored pixels which have
|
|
magic meaning to developers.
|
|
FLAGS_OVERLAY_STATS 8 Shows tiny numbers on screen,
|
|
useful only for debugging.
|
|
FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers.
|
|
FLAGS_SEPARATE_FRAMES 32 Shows each frame separately, as
|
|
it was received from the camera.
|
|
Default (not set) is to mix the
|
|
preceding frame in to compensate
|
|
for occasional loss of Isoc data
|
|
on high frame rates.
|
|
FLAGS_CLEAN_FRAMES 64 Forces "cleanup" of each frame
|
|
prior to use; relevant only if
|
|
FLAGS_SEPARATE_FRAMES is set.
|
|
Default is not to clean frames,
|
|
this is a little faster but may
|
|
produce flicker if frame rate is
|
|
too high and Isoc data gets lost.
|
|
FLAGS_NO_DECODING 128 This flag turns the video stream
|
|
decoder off, and dumps the raw
|
|
Isoc data from the camera into
|
|
the reading process. Useful to
|
|
developers, but not to users.
|
|
|
|
framerate This setting controls frame rate of the camera. This is
|
|
an approximate setting (in terms of "worst" ... "best")
|
|
because camera changes frame rate depending on amount
|
|
of light available. Setting 0 is slowest, 6 is fastest.
|
|
Beware - fast settings are very demanding and may not
|
|
work well with all video sizes. Be conservative.
|
|
|
|
hue_correction This highly optional setting allows to adjust the
|
|
hue of the image in a way slightly different from
|
|
what usual "hue" control does. Both controls affect
|
|
YUV colorspace: regular "hue" control adjusts only
|
|
U component, and this "hue_correction" option similarly
|
|
adjusts only V component. However usually it is enough
|
|
to tweak only U or V to compensate for colored light or
|
|
color temperature; this option simply allows more
|
|
complicated correction when and if it is necessary.
|
|
|
|
init_brightness These settings specify _initial_ values which will be
|
|
init_contrast used to set up the camera. If your V4L application has
|
|
init_color its own controls to adjust the picture then these
|
|
init_hue controls will be used too. These options allow you to
|
|
preconfigure the camera when it gets connected, before
|
|
any V4L application connects to it. Good for webcams.
|
|
|
|
init_model2_rg These initial settings alter color balance of the
|
|
init_model2_rg2 camera on hardware level. All four settings may be used
|
|
init_model2_sat to tune the camera to specific lighting conditions. These
|
|
init_model2_yb settings only apply to Model 2 cameras.
|
|
|
|
lighting This option selects one of three hardware-defined
|
|
photosensitivity settings of the camera. 0=bright light,
|
|
1=Medium (default), 2=Low light. This setting affects
|
|
frame rate: the dimmer the lighting the lower the frame
|
|
rate (because longer exposition time is needed). The
|
|
Model 2 cameras allow values more than 2 for this option,
|
|
thus enabling extremely high sensitivity at cost of frame
|
|
rate, color saturation and imaging sensor noise.
|
|
|
|
sharpness This option controls smoothing (noise reduction)
|
|
made by camera. Setting 0 is most smooth, setting 6
|
|
is most sharp. Be aware that CMOS sensor used in the
|
|
camera is pretty noisy, so if you choose 6 you will
|
|
be greeted with "snowy" image. Default is 4. Model 2
|
|
cameras do not support this feature.
|
|
|
|
size This setting chooses one of several image sizes that are
|
|
supported by this driver. Cameras may support more, but
|
|
it's difficult to reverse-engineer all formats.
|
|
Following video sizes are supported:
|
|
|
|
size=0 128x96 (Model 1 only)
|
|
size=1 160x120
|
|
size=2 176x144
|
|
size=3 320x240 (Model 2 only)
|
|
size=4 352x240 (Model 2 only)
|
|
size=5 352x288
|
|
size=6 640x480 (Model 3 only)
|
|
|
|
The 352x288 is the native size of the Model 1 sensor
|
|
array, so it's the best resolution the camera can
|
|
yield. The best resolution of Model 2 is 176x144, and
|
|
larger images are produced by stretching the bitmap.
|
|
Model 3 has sensor with 640x480 grid, and it works too,
|
|
but the frame rate will be exceptionally low (1-2 FPS);
|
|
it may be still OK for some applications, like security.
|
|
Choose the image size you need. The smaller image can
|
|
support faster frame rate. Default is 352x288.
|
|
|
|
For more information and the Troubleshooting FAQ visit this URL:
|
|
|
|
http://www.linux-usb.org/ibmcam/
|
|
|
|
WHAT NEEDS TO BE DONE:
|
|
|
|
- The button on the camera is not used. I don't know how to get to it.
|
|
I know now how to read button on Model 2, but what to do with it?
|
|
|
|
- Camera reports its status back to the driver; however I don't know
|
|
what returned data means. If camera fails at some initialization
|
|
stage then something should be done, and I don't do that because
|
|
I don't even know that some command failed. This is mostly Model 1
|
|
concern because Model 2 uses different commands which do not return
|
|
status (and seem to complete successfully every time).
|
|
|
|
- Some flavors of Model 4 NetCameras produce only compressed video
|
|
streams, and I don't know how to decode them.
|
|
|
|
CREDITS:
|
|
|
|
The code is based in no small part on the CPiA driver by Johannes Erdfelt,
|
|
Randy Dunlap, and others. Big thanks to them for their pioneering work on that
|
|
and the USB stack.
|
|
|
|
I also thank John Lightsey for his donation of the Veo Stingray camera.
|