V4L/DVB (3653h): Move usb v4l docs into Documentation/video4linux
- Move documentation for usb v4l devices from
Documentation/usb to Documentation/video4linux.
- Removed trailing whitespace.
- Update Kconfig help text links to reflect the new file locations.
Signed-off-by: Michael Krufky <mkrufky@linuxtv.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@infradead.org>
diff --git a/Documentation/video4linux/ibmcam.txt b/Documentation/video4linux/ibmcam.txt
new file mode 100644
index 0000000..4a40a2e
--- /dev/null
+++ b/Documentation/video4linux/ibmcam.txt
@@ -0,0 +1,324 @@
+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://www.xirlink.com/
+(renamed to http://www.veo.com), 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.
