diff options
Diffstat (limited to 'Documentation/video4linux')
| -rw-r--r-- | Documentation/video4linux/CARDLIST.saa7134 | 5 | ||||
| -rw-r--r-- | Documentation/video4linux/et61x251.txt | 314 | ||||
| -rw-r--r-- | Documentation/video4linux/ibmcam.txt | 324 | ||||
| -rw-r--r-- | Documentation/video4linux/ov511.txt | 288 | ||||
| -rw-r--r-- | Documentation/video4linux/se401.txt | 54 | ||||
| -rw-r--r-- | Documentation/video4linux/sn9c102.txt | 518 | ||||
| -rw-r--r-- | Documentation/video4linux/stv680.txt | 53 | ||||
| -rw-r--r-- | Documentation/video4linux/w9968cf.txt | 461 | ||||
| -rw-r--r-- | Documentation/video4linux/zc0301.txt | 254 |
9 files changed, 2269 insertions, 2 deletions
diff --git a/Documentation/video4linux/CARDLIST.saa7134 b/Documentation/video4linux/CARDLIST.saa7134 index 8c719545596..bca50903233 100644 --- a/Documentation/video4linux/CARDLIST.saa7134 +++ b/Documentation/video4linux/CARDLIST.saa7134 @@ -52,7 +52,7 @@ 51 -> ProVideo PV952 [1540:9524] 52 -> AverMedia AverTV/305 [1461:2108] 53 -> ASUS TV-FM 7135 [1043:4845] - 54 -> LifeView FlyTV Platinum FM [5168:0214,1489:0214] + 54 -> LifeView FlyTV Platinum FM / Gold [5168:0214,1489:0214,5168:0304] 55 -> LifeView FlyDVB-T DUO [5168:0306] 56 -> Avermedia AVerTV 307 [1461:a70a] 57 -> Avermedia AVerTV GO 007 FM [1461:f31f] @@ -84,7 +84,7 @@ 83 -> Terratec Cinergy 250 PCI TV [153b:1160] 84 -> LifeView FlyDVB Trio [5168:0319] 85 -> AverTV DVB-T 777 [1461:2c05] - 86 -> LifeView FlyDVB-T [5168:0301] + 86 -> LifeView FlyDVB-T / Genius VideoWonder DVB-T [5168:0301,1489:0301] 87 -> ADS Instant TV Duo Cardbus PTV331 [0331:1421] 88 -> Tevion/KWorld DVB-T 220RF [17de:7201] 89 -> ELSA EX-VISION 700TV [1048:226c] @@ -92,3 +92,4 @@ 91 -> AVerMedia A169 B [1461:7360] 92 -> AVerMedia A169 B1 [1461:6360] 93 -> Medion 7134 Bridge #2 [16be:0005] + 94 -> LifeView FlyDVB-T Hybrid Cardbus [5168:3306,5168:3502] diff --git a/Documentation/video4linux/et61x251.txt b/Documentation/video4linux/et61x251.txt new file mode 100644 index 00000000000..29340282ab5 --- /dev/null +++ b/Documentation/video4linux/et61x251.txt @@ -0,0 +1,314 @@ + + ET61X[12]51 PC Camera Controllers + Driver for Linux + ================================= + + - Documentation - + + +Index +===== +1. Copyright +2. Disclaimer +3. License +4. Overview and features +5. Module dependencies +6. Module loading +7. Module parameters +8. Optional device control through "sysfs" +9. Supported devices +10. Notes for V4L2 application developers +11. Contact information + + +1. Copyright +============ +Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it> + + +2. Disclaimer +============= +Etoms is a trademark of Etoms Electronics Corp. +This software is not developed or sponsored by Etoms Electronics. + + +3. License +========== +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +4. Overview and features +======================== +This driver supports the video interface of the devices mounting the ET61X151 +or ET61X251 PC Camera Controllers. + +It's worth to note that Etoms Electronics has never collaborated with the +author during the development of this project; despite several requests, +Etoms Electronics also refused to release enough detailed specifications of +the video compression engine. + +The driver relies on the Video4Linux2 and USB core modules. It has been +designed to run properly on SMP systems as well. + +The latest version of the ET61X[12]51 driver can be found at the following URL: +http://www.linux-projects.org/ + +Some of the features of the driver are: + +- full compliance with the Video4Linux2 API (see also "Notes for V4L2 + application developers" paragraph); +- available mmap or read/poll methods for video streaming through isochronous + data transfers; +- automatic detection of image sensor; +- support for any window resolutions and optional panning within the maximum + pixel area of image sensor; +- image downscaling with arbitrary scaling factors from 1 and 2 in both + directions (see "Notes for V4L2 application developers" paragraph); +- two different video formats for uncompressed or compressed data in low or + high compression quality (see also "Notes for V4L2 application developers" + paragraph); +- full support for the capabilities of every possible image sensors that can + be connected to the ET61X[12]51 bridges, including, for istance, red, green, + blue and global gain adjustments and exposure control (see "Supported + devices" paragraph for details); +- use of default color settings for sunlight conditions; +- dynamic I/O interface for both ET61X[12]51 and image sensor control (see + "Optional device control through 'sysfs'" paragraph); +- dynamic driver control thanks to various module parameters (see "Module + parameters" paragraph); +- up to 64 cameras can be handled at the same time; they can be connected and + disconnected from the host many times without turning off the computer, if + the system supports hotplugging; +- no known bugs. + + +5. Module dependencies +====================== +For it to work properly, the driver needs kernel support for Video4Linux and +USB. + +The following options of the kernel configuration file must be enabled and +corresponding modules must be compiled: + + # Multimedia devices + # + CONFIG_VIDEO_DEV=m + +To enable advanced debugging functionality on the device through /sysfs: + + # Multimedia devices + # + CONFIG_VIDEO_ADV_DEBUG=y + + # USB support + # + CONFIG_USB=m + +In addition, depending on the hardware being used, the modules below are +necessary: + + # USB Host Controller Drivers + # + CONFIG_USB_EHCI_HCD=m + CONFIG_USB_UHCI_HCD=m + CONFIG_USB_OHCI_HCD=m + +And finally: + + # USB Multimedia devices + # + CONFIG_USB_ET61X251=m + + +6. Module loading +================= +To use the driver, it is necessary to load the "et61x251" module into memory +after every other module required: "videodev", "usbcore" and, depending on +the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". + +Loading can be done as shown below: + + [root@localhost home]# modprobe et61x251 + +At this point the devices should be recognized. You can invoke "dmesg" to +analyze kernel messages and verify that the loading process has gone well: + + [user@localhost home]$ dmesg + + +7. Module parameters +==================== +Module parameters are listed below: +------------------------------------------------------------------------------- +Name: video_nr +Type: short array (min = 0, max = 64) +Syntax: <-1|n[,...]> +Description: Specify V4L2 minor mode number: + -1 = use next available + n = use minor number n + You can specify up to 64 cameras this way. + For example: + video_nr=-1,2,-1 would assign minor number 2 to the second + registered camera and use auto for the first one and for every + other camera. +Default: -1 +------------------------------------------------------------------------------- +Name: force_munmap +Type: bool array (min = 0, max = 64) +Syntax: <0|1[,...]> +Description: Force the application to unmap previously mapped buffer memory + before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not + all the applications support this feature. This parameter is + specific for each detected camera. + 0 = do not force memory unmapping + 1 = force memory unmapping (save memory) +Default: 0 +------------------------------------------------------------------------------- +Name: frame_timeout +Type: uint array (min = 0, max = 64) +Syntax: <n[,...]> +Description: Timeout for a video frame in seconds. This parameter is + specific for each detected camera. This parameter can be + changed at runtime thanks to the /sys filesystem interface. +Default: 2 +------------------------------------------------------------------------------- +Name: debug +Type: ushort +Syntax: <n> +Description: Debugging information level, from 0 to 3: + 0 = none (use carefully) + 1 = critical errors + 2 = significant informations + 3 = more verbose messages + Level 3 is useful for testing only, when only one device + is used at the same time. It also shows some more informations + about the hardware being detected. This module parameter can be + changed at runtime thanks to the /sys filesystem interface. +Default: 2 +------------------------------------------------------------------------------- + + +8. Optional device control through "sysfs" +========================================== +If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled, +it is possible to read and write both the ET61X[12]51 and the image sensor +registers by using the "sysfs" filesystem interface. + +There are four files in the /sys/class/video4linux/videoX directory for each +registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files +control the ET61X[12]51 bridge, while the other two control the sensor chip. +"reg" and "i2c_reg" hold the values of the current register index where the +following reading/writing operations are addressed at through "val" and +"i2c_val". Their use is not intended for end-users, unless you know what you +are doing. Remember that you must be logged in as root before writing to them. + +As an example, suppose we were to want to read the value contained in the +register number 1 of the sensor register table - which is usually the product +identifier - of the camera registered as "/dev/video0": + + [root@localhost #] cd /sys/class/video4linux/video0 + [root@localhost #] echo 1 > i2c_reg + [root@localhost #] cat i2c_val + +Note that if the sensor registers can not be read, "cat" will fail. +To avoid race conditions, all the I/O accesses to the files are serialized. + + +9. Supported devices +==================== +None of the names of the companies as well as their products will be mentioned +here. They have never collaborated with the author, so no advertising. + +From the point of view of a driver, what unambiguously identify a device are +its vendor and product USB identifiers. Below is a list of known identifiers of +devices mounting the ET61X[12]51 PC camera controllers: + +Vendor ID Product ID +--------- ---------- +0x102c 0x6151 +0x102c 0x6251 +0x102c 0x6253 +0x102c 0x6254 +0x102c 0x6255 +0x102c 0x6256 +0x102c 0x6257 +0x102c 0x6258 +0x102c 0x6259 +0x102c 0x625a +0x102c 0x625b +0x102c 0x625c +0x102c 0x625d +0x102c 0x625e +0x102c 0x625f +0x102c 0x6260 +0x102c 0x6261 +0x102c 0x6262 +0x102c 0x6263 +0x102c 0x6264 +0x102c 0x6265 +0x102c 0x6266 +0x102c 0x6267 +0x102c 0x6268 +0x102c 0x6269 + +The following image sensors are supported: + +Model Manufacturer +----- ------------ +TAS5130D1B Taiwan Advanced Sensor Corporation + +All the available control settings of each image sensor are supported through +the V4L2 interface. + + +10. Notes for V4L2 application developers +========================================= +This driver follows the V4L2 API specifications. In particular, it enforces two +rules: + +- exactly one I/O method, either "mmap" or "read", is associated with each +file descriptor. Once it is selected, the application must close and reopen the +device to switch to the other I/O method; + +- although it is not mandatory, previously mapped buffer memory should always +be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. +The same number of buffers as before will be allocated again to match the size +of the new video frames, so you have to map the buffers again before any I/O +attempts on them. + +Consistently with the hardware limits, this driver also supports image +downscaling with arbitrary scaling factors from 1 and 2 in both directions. +However, the V4L2 API specifications don't correctly define how the scaling +factor can be chosen arbitrarily by the "negotiation" of the "source" and +"target" rectangles. To work around this flaw, we have added the convention +that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the +scaling factor is restored to 1. + +This driver supports two different video formats: the first one is the "8-bit +Sequential Bayer" format and can be used to obtain uncompressed video data +from the device through the current I/O method, while the second one provides +"raw" compressed video data (without frame headers not related to the +compressed data). The current compression quality may vary from 0 to 1 and can +be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP +V4L2 ioctl's. + + +11. Contact information +======================= +The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. + +GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is +'FCE635A4'; the public 1024-bit key should be available at any keyserver; +the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. diff --git a/Documentation/video4linux/ibmcam.txt b/Documentation/video4linux/ibmcam.txt new file mode 100644 index 00000000000..4a40a2e9945 --- /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. diff --git a/Documentation/video4linux/ov511.txt b/Documentation/video4linux/ov511.txt new file mode 100644 index 00000000000..142741e3c57 --- /dev/null +++ b/Documentation/video4linux/ov511.txt @@ -0,0 +1,288 @@ +------------------------------------------------------------------------------- +Readme for Linux device driver for the OmniVision OV511 USB to camera bridge IC +------------------------------------------------------------------------------- + +Author: Mark McClelland +Homepage: http://alpha.dyndns.org/ov511 + +INTRODUCTION: + +This is a driver for the OV511, a USB-only chip used in many "webcam" devices. +Any camera using the OV511/OV511+ and the OV6620/OV7610/20/20AE should work. +Video capture devices that use the Philips SAA7111A decoder also work. It +supports streaming and capture of color or monochrome video via the Video4Linux +API. Most V4L apps are compatible with it. Most resolutions with a width and +height that are a multiple of 8 are supported. + +If you need more information, please visit the OV511 homepage at the above URL. + +WHAT YOU NEED: + +- If you want to help with the development, get the chip's specification docs at + http://www.ovt.com/omniusbp.html + +- A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv) + vidcat is part of the w3cam package: http://mpx.freeshell.net/ + xawtv is available at: http://linux.bytesex.org/xawtv/ + +HOW TO USE IT: + +Note: These are simplified instructions. For complete instructions see: + http://alpha.dyndns.org/ov511/install.html + +You must have first compiled USB support, support for your specific USB host +controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend +making them modules.) Make sure "Enforce bandwidth allocation" is NOT enabled. + +Next, (as root): + + modprobe usbcore + modprobe usb-uhci <OR> modprobe usb-ohci + modprobe videodev + modprobe ov511 + +If it is not already there (it usually is), create the video device: + + mknod /dev/video0 c 81 0 + +Optionally, symlink /dev/video to /dev/video0 + +You will have to set permissions on this device to allow you to read/write +from it: + + chmod 666 /dev/video + chmod 666 /dev/video0 (if necessary) + +Now you are ready to run a video app! Both vidcat and xawtv work well for me +at 640x480. + +[Using vidcat:] + + vidcat -s 640x480 -p c > test.jpg + xview test.jpg + +[Using xawtv:] + +From the main xawtv directory: + + make clean + ./configure + make + make install + +Now you should be able to run xawtv. Right click for the options dialog. + +MODULE PARAMETERS: + + You can set these with: insmod ov511 NAME=VALUE + There is currently no way to set these on a per-camera basis. + + NAME: autobright + TYPE: integer (Boolean) + DEFAULT: 1 + DESC: Brightness is normally under automatic control and can't be set + manually by the video app. Set to 0 for manual control. + + NAME: autogain + TYPE: integer (Boolean) + DEFAULT: 1 + DESC: Auto Gain Control enable. This feature is not yet implemented. + + NAME: autoexp + TYPE: integer (Boolean) + DEFAULT: 1 + DESC: Auto Exposure Control enable. This feature is not yet implemented. + + NAME: debug + TYPE: integer (0-6) + DEFAULT: 3 + DESC: Sets the threshold for printing debug messages. The higher the value, + the more is printed. The levels are cumulative, and are as follows: + 0=no debug messages + 1=init/detection/unload and other significant messages + 2=some warning messages + 3=config/control function calls + 4=most function calls and data parsing messages + 5=highly repetitive mesgs + + NAME: snapshot + TYPE: integer (Boolean) + DEFAULT: 0 + DESC: Set to 1 to enable snapshot mode. read()/VIDIOCSYNC will block until + the snapshot button is pressed. Note: enabling this mode disables + /proc/video/ov511/<minor#>/button + + NAME: cams + TYPE: integer (1-4 for OV511, 1-31 for OV511+) + DEFAULT: 1 + DESC: Number of cameras allowed to stream simultaneously on a single bus. + Values higher than 1 reduce the data rate of each camera, allowing two + or more to be used at once. If you have a complicated setup involving + both OV511 and OV511+ cameras, trial-and-error may be necessary for + finding the optimum setting. + + NAME: compress + TYPE: integer (Boolean) + DEFAULT: 0 + DESC: Set this to 1 to turn on the camera's compression engine. This can + potentially increase the frame rate at the expense of quality, if you + have a fast CPU. You must load the proper compression module for your + camera before starting your application (ov511_decomp or ov518_decomp). + + NAME: testpat + TYPE: integer (Boolean) + DEFAULT: 0 + DESC: This configures the camera's sensor to transmit a colored test-pattern + instead of an image. This does not work correctly yet. + + NAME: dumppix + TYPE: integer (0-2) + DEFAULT: 0 + DESC: Dumps raw pixel data and skips post-processing and format conversion. + It is for debugging purposes only. Options are: + 0: Disable (default) + 1: Dump raw data from camera, excluding headers and trailers + 2: Dumps data exactly as received from camera + + NAME: led + TYPE: integer (0-2) + DEFAULT: 1 (Always on) + DESC: Controls whether the LED (the little light) on the front of the camera + is always off (0), always on (1), or only on when driver is open (2). + This is not supported with the OV511, and might only work with certain + cameras (ones that actually have the LED wired to the control pin, and + not just hard-wired to be on all the time). + + NAME: dump_bridge + TYPE: integer (Boolean) + DEFAULT: 0 + DESC: Dumps the bridge (OV511[+] or OV518[+]) register values to the system + log. Only useful for serious debugging/development purposes. + + NAME: dump_sensor + TYPE: integer (Boolean) + DEFAULT: 0 + DESC: Dumps the sensor register values to the system log. Only useful for + serious debugging/development purposes. + + NAME: printph + TYPE: integer (Boolean) + DEFAULT: 0 + DESC: Setting this to 1 will dump the first 12 bytes of each isoc frame. This + is only useful if you are trying to debug problems with the isoc data + stream (i.e.: camera initializes, but vidcat hangs until Ctrl-C). Be + warned that this dumps a large number of messages to your kernel log. + + NAME: phy, phuv, pvy, pvuv, qhy, qhuv, qvy, qvuv + TYPE: integer (0-63 for phy and phuv, 0-255 for rest) + DEFAULT: OV511 default values + DESC: These are registers 70h - 77h of the OV511, which control the + prediction ranges and quantization thresholds of the compressor, for + the Y and UV channels in the horizontal and vertical directions. See + the OV511 or OV511+ data sheet for more detailed descriptions. These + normally do not need to be changed. + + NAME: lightfreq + TYPE: integer (0, 50, or 60) + DEFAULT: 0 (use sensor default) + DESC: Sets the sensor to match your lighting frequency. This can reduce the + appearance of "banding", i.e. horizontal lines or waves of light and + dark that are often caused by artificial lighting. Valid values are: + 0 - Use default (depends on sensor, most likely 60 Hz) + 50 - For European and Asian 50 Hz power + 60 - For American 60 Hz power + + NAME: bandingfilter + TYPE: integer (Boolean) + DEFAULT: 0 (off) + DESC: Enables the sensor´s banding filter exposure algorithm. This reduces + or stabilizes the "banding" caused by some artificial light sources + (especially fluorescent). You might have to set lightfreq correctly for + this to work right. As an added bonus, this sometimes makes it + possible to capture your monitor´s output. + + NAME: fastset + TYPE: integer (Boolean) + DEFAULT: 0 (off) + DESC: Allows picture settings (brightness, contrast, color, and hue) to take + effect immediately, even in the middle of a frame. This reduces the + time to change settings, but can ruin frames during the change. Only + affects OmniVision sensors. + + NAME: force_palette + TYPE: integer (Boolean) + DEFAULT: 0 (off) + DESC: Forces the palette (color format) to a specific value. If an + application requests a different palette, it will be rejected, thereby + forcing it to try others until it succeeds. This is useful for forcing + greyscale mode with a color camera, for example. Supported modes are: + 0 (Allows all the following formats) + 1 VIDEO_PALETTE_GREY (Linear greyscale) + 10 VIDEO_PALETTE_YUV420 (YUV 4:2:0 Planar) + 15 VIDEO_PALETTE_YUV420P (YUV 4:2:0 Planar, same as 10) + + NAME: backlight + TYPE: integer (Boolean) + DEFAULT: 0 (off) + DESC: Setting this flag changes the exposure algorithm for OmniVision sensors + such that objects in the camera's view (i.e. your head) can be clearly + seen when they are illuminated from behind. It reduces or eliminates + the sensor's auto-exposure function, so it should only be used when + needed. Additionally, it is only supported with the OV6620 and OV7620. + + NAME: unit_video + TYPE: Up to 16 comma-separated integers + DEFAULT: 0,0,0... (automatically assign the next available minor(s)) + DESC: You can specify up to 16 minor numbers to be assigned to ov511 devices. + For example, "unit_video=1,3" will make the driver use /dev/video1 and + /dev/video3 for the first two devices it detects. Additional devices + will be assigned automatically starting at the first available device + node (/dev/video0 in this case). Note that you cannot specify 0 as a + minor number. This feature requires kernel version 2.4.5 or higher. + + NAME: remove_zeros + TYPE: integer (Boolean) + DEFAULT: 0 (do not skip any incoming data) + DESC: Setting this to 1 will remove zero-padding from incoming data. This + will compensate for the blocks of corruption that can appear when the + camera cannot keep up with the speed of the USB bus (eg. at low frame + resolutions). This feature is always enabled when compression is on. + + NAME: mirror + TYPE: integer (Boolean) + DEFAULT: 0 (off) + DESC: Setting this to 1 will reverse ("mirror") the image horizontally. This + might be necessary if your camera has a custom lens assembly. This has + no effect with video capture devices. + + NAME: ov518_color + TYPE: integer (Boolean) + DEFAULT: 0 (off) + DESC: Enable OV518 color support. This is off by default since it doesn't + work most of the time. If you want to try it, you must also load + ov518_decomp with the "nouv=0" parameter. If you get improper colors or + diagonal lines through the image, restart your video app and try again. + Repeat as necessary. + +WORKING FEATURES: + o Color streaming/capture at most widths and heights that are multiples of 8. + o Monochrome (use force_palette=1 to enable) + o Setting/getting of saturation, contrast, brightness, and hue (only some of + them work the OV7620 and OV7620AE) + o /proc status reporting + o SAA7111A video capture support at 320x240 and 640x480 + o Compression support + o SMP compatibility + +HOW TO CONTACT ME: + +You can email me at mark@alpha.dyndns.org . Please prefix the subject line +with "OV511: " so that I am certain to notice your message. + +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. Thanks to Bret Wallach for getting camera reg IO, ISOC, and +image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio +Matsuoka for their work as well. diff --git a/Documentation/video4linux/se401.txt b/Documentation/video4linux/se401.txt new file mode 100644 index 00000000000..7b9d1c960a1 --- /dev/null +++ b/Documentation/video4linux/se401.txt @@ -0,0 +1,54 @@ +Linux driver for SE401 based USB cameras + +Copyright, 2001, Jeroen Vreeken + + +INTRODUCTION: + +The SE401 chip is the used in low-cost usb webcams. +It is produced by Endpoints Inc. (www.endpoints.com). +It interfaces directly to a cmos image sensor and USB. The only other major +part in a se401 based camera is a dram chip. + +The following cameras are known to work with this driver: + +Aox se401 (non-branded) cameras +Philips PVCV665 USB VGA webcam 'Vesta Fun' +Kensington VideoCAM PC Camera Model 67014 +Kensington VideoCAM PC Camera Model 67015 +Kensington VideoCAM PC Camera Model 67016 +Kensington VideoCAM PC Camera Model 67017 + + +WHAT YOU NEED: + +- USB support +- VIDEO4LINUX support + +More information about USB support for linux can be found at: +http://www.linux-usb.org + + +MODULE OPTIONS: + +When the driver is compiled as a module you can also use the 'flickerless' +option. With it exposure is limited to values that do not interfere with the +net frequency. Valid options for this option are 0, 50 and 60. (0=disable, +50=50hz, 60=60hz) + + +KNOWN PROBLEMS: + +The driver works fine with the usb-ohci and uhci host controller drivers, +the default settings also work with usb-uhci. But sending more than one bulk +transfer at a time with usb-uhci doesn't work yet. +Users of usb-ohci and uhci can safely enlarge SE401_NUMSBUF in se401.h in +order to increase the throughput (and thus framerate). + + +HELP: + +The latest info on this driver can be found at: +http://www.chello.nl/~j.vreeken/se401/ +And questions to me can be send to: +pe1rxq@amsat.org diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt new file mode 100644 index 00000000000..142920bc011 --- /dev/null +++ b/Documentation/video4linux/sn9c102.txt @@ -0,0 +1,518 @@ + + SN9C10x PC Camera Controllers + Driver for Linux + ============================= + + - Documentation - + + +Index +===== +1. Copyright +2. Disclaimer +3. License +4. Overview and features +5. Module dependencies +6. Module loading +7. Module parameters +8. Optional device control through "sysfs" +9. Supported devices +10. Notes for V4L2 application developers +11. Video frame formats +12. Contact information +13. Credits + + +1. Copyright +============ +Copyright (C) 2004-2006 by Luca Risolia <luca.risolia@studio.unibo.it> + + +2. Disclaimer +============= +SONiX is a trademark of SONiX Technology Company Limited, inc. +This software is not sponsored or developed by SONiX. + + +3. License +========== +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +4. Overview and features +======================== +This driver attempts to support the video interface of the devices mounting the +SONiX SN9C101, SN9C102 and SN9C103 PC Camera Controllers. + +It's worth to note that SONiX has never collaborated with the author during the +development of this project, despite several requests for enough detailed +specifications of the register tables, compression engine and video data format +of the above chips. Nevertheless, these informations are no longer necessary, +becouse all the aspects related to these chips are known and have been +described in detail in this documentation. + +The driver relies on the Video4Linux2 and USB core modules. It has been +designed to run properly on SMP systems as well. + +The latest version of the SN9C10x driver can be found at the following URL: +http://www.linux-projects.org/ + +Some of the features of the driver are: + +- full compliance with the Video4Linux2 API (see also "Notes for V4L2 + application developers" paragraph); +- available mmap or read/poll methods for video streaming through isochronous + data transfers; +- automatic detection of image sensor; +- support for built-in microphone interface; +- support for any window resolutions and optional panning within the maximum + pixel area of image sensor; +- image downscaling with arbitrary scaling factors from 1, 2 and 4 in both + directions (see "Notes for V4L2 application developers" paragraph); +- two different video formats for uncompressed or compressed data in low or + high compression quality (see also "Notes for V4L2 application developers" + and "Video frame formats" paragraphs); +- full support for the capabilities of many of the possible image sensors that + can be connected to the SN9C10x bridges, including, for istance, red, green, + blue and global gain adjustments and exposure (see "Supported devices" + paragraph for details); +- use of default color settings for sunlight conditions; +- dynamic I/O interface for both SN9C10x and image sensor control and + monitoring (see "Optional device control through 'sysfs'" paragraph); +- dynamic driver control thanks to various module parameters (see "Module + parameters" paragraph); +- up to 64 cameras can be handled at the same time; they can be connected and + disconnected from the host many times without turning off the computer, if + the system supports hotplugging; +- no known bugs. + + +5. Module dependencies +====================== +For it to work properly, the driver needs kernel support for Video4Linux and +USB. + +The following options of the kernel configuration file must be enabled and +corresponding modules must be compiled: + + # Multimedia devices + # + CONFIG_VIDEO_DEV=m + +To enable advanced debugging functionality on the device through /sysfs: + + # Multimedia devices + # + CONFIG_VIDEO_ADV_DEBUG=y + + # USB support + # + CONFIG_USB=m + +In addition, depending on the hardware being used, the modules below are +necessary: + + # USB Host Controller Drivers + # + CONFIG_USB_EHCI_HCD=m + CONFIG_USB_UHCI_HCD=m + CONFIG_USB_OHCI_HCD=m + +The SN9C103 controller also provides a built-in microphone interface. It is +supported by the USB Audio driver thanks to the ALSA API: + + # Sound + # + CONFIG_SOUND=y + + # Advanced Linux Sound Architecture + # + CONFIG_SND=m + + # USB devices + # + CONFIG_SND_USB_AUDIO=m + +And finally: + + # USB Multimedia devices + # + CONFIG_USB_SN9C102=m + + +6. Module loading +================= +To use the driver, it is necessary to load the "sn9c102" module into memory +after every other module required: "videodev", "usbcore" and, depending on +the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". + +Loading can be done as shown below: + + [root@localhost home]# modprobe sn9c102 + +At this point the devices should be recognized. You can invoke "dmesg" to +analyze kernel messages and verify that the loading process has gone well: + + [user@localhost home]$ dmesg + + +7. Module parameters +==================== +Module parameters are listed below: +------------------------------------------------------------------------------- +Name: video_nr +Type: short array (min = 0, max = 64) +Syntax: <-1|n[,...]> +Description: Specify V4L2 minor mode number: + -1 = use next available + n = use minor number n + You can specify up to 64 cameras this way. + For example: + video_nr=-1,2,-1 would assign minor number 2 to the second + recognized camera and use auto for the first one and for every + other camera. +Default: -1 +------------------------------------------------------------------------------- +Name: force_munmap +Type: bool array (min = 0, max = 64) +Syntax: <0|1[,...]> +Description: Force the application to unmap previously mapped buffer memory + before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not + all the applications support this feature. This parameter is + specific for each detected camera. + 0 = do not force memory unmapping + 1 = force memory unmapping (save memory) +Default: 0 +------------------------------------------------------------------------------- +Name: frame_timeout +Type: uint array (min = 0, max = 64) +Syntax: <n[,...]> +Description: Timeout for a video frame in seconds. This parameter is + specific for each detected camera. This parameter can be + changed at runtime thanks to the /sys filesystem interface. +Default: 2 +------------------------------------------------------------------------------- +Name: debug +Type: ushort +Syntax: <n> +Description: Debugging information level, from 0 to 3: + 0 = none (use carefully) + 1 = critical errors + 2 = significant informations + 3 = more verbose messages + Level 3 is useful for testing only, when only one device + is used. It also shows some more informations about the + hardware being detected. This parameter can be changed at + runtime thanks to the /sys filesystem interface. +Default: 2 +------------------------------------------------------------------------------- + + +8. Optional device control through "sysfs" [1] +========================================== +If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled, +it is possible to read and write both the SN9C10x and the image sensor +registers by using the "sysfs" filesystem interface. + +Every time a supported device is recognized, a write-only file named "green" is +created in the /sys/class/video4linux/videoX directory. You can set the green +channel's gain by writing the desired value to it. The value may range from 0 +to 15 for SN9C101 or SN9C102 bridges, from 0 to 127 for SN9C103 bridges. +Similarly, only for SN9C103 controllers, blue and red gain control files are +available in the same directory, for which accepted values may range from 0 to +127. + +There are other four entries in the directory above for each registered camera: +"reg", "val", "i2c_reg" and "i2c_val". The first two files control the +SN9C10x bridge, while the other two control the sensor chip. "reg" and +"i2c_reg" hold the values of the current register index where the following +reading/writing operations are addressed at through "val" and "i2c_val". Their +use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not +be created if the sensor does not actually support the standard I2C protocol or +its registers are not 8-bit long. Also, remember that you must be logged in as +root before writing to them. + +As an example, suppose we were to want to read the value contained in the +register number 1 of the sensor register table - which is usually the product +identifier - of the camera registered as "/dev/video0": + + [root@localhost #] cd /sys/class/video4linux/video0 + [root@localhost #] echo 1 > i2c_reg + [root@localhost #] cat i2c_val + +Note that "cat" will fail if sensor registers cannot be read. + +Now let's set the green gain's register of the SN9C101 or SN9C102 chips to 2: + + [root@localhost #] echo 0x11 > reg + [root@localhost #] echo 2 > val + +Note that the SN9C10x always returns 0 when some of its registers are read. +To avoid race conditions, all the I/O accesses to the above files are +serialized. + +The sysfs interface also provides the "frame_header" entry, which exports the +frame header of the most recent requested and captured video frame. The header +is always 18-bytes long and is appended to every video frame by the SN9C10x +controllers. As an example, this additional information can be used by the user +application for implementing auto-exposure features via software. + +The following table describes the frame header: + +Byte # Value Description +------ ----- ----------- +0x00 0xFF Frame synchronisation pattern. +0x01 0xFF Frame synchronisation pattern. +0x02 0x00 Frame synchronisation pattern. +0x03 0xC4 Frame synchronisation pattern. +0x04 0xC4 Frame synchronisation pattern. +0x05 0x96 Frame synchronisation pattern. +0x06 0xXX Unknown meaning. The exact value depends on the chip; + possible values are 0x00, 0x01 and 0x20. +0x07 0xXX Variable value, whose bits are ff00uzzc, where ff is a + frame counter, u is unknown, zz is a size indicator + (00 = VGA, 01 = SIF, 10 = QSIF) and c stands for + "compression enabled" (1 = yes, 0 = no). +0x08 0xXX Brightness sum inside Auto-Exposure area (low-byte). +0x09 0xXX Brightness sum inside Auto-Exposure area (high-byte). + For a pure white image, this number will be equal to 500 + times the area of the specified AE area. For images + that are not pure white, the value scales down according + to relative whiteness. +0x0A 0xXX Brightness sum outside Auto-Exposure area (low-byte). +0x0B 0xXX Brightness sum outside Auto-Exposure area (high-byte). + For a pure white image, this number will be equal to 125 + times the area outside of the specified AE area. For + images that are not pure white, the value scales down + according to relative whiteness. + according to relative whiteness. + +The following bytes are used by the SN9C103 bridge only: + +0x0C 0xXX Unknown meaning +0x0D 0xXX Unknown meaning +0x0E 0xXX Unknown meaning +0x0F 0xXX Unknown meaning +0x10 0xXX Unknown meaning +0x11 0xXX Unknown meaning + +The AE area (sx, sy, ex, ey) in the active window can be set by programming the +registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C10x controllers, where one unit +corresponds to 32 pixels. + +[1] Part of the meaning of the frame header has been documented by Bertrik + Sikken. + + +9. Supported devices +==================== +None of the names of the companies as well as their products will be mentioned +here. They have never collaborated with the author, so no advertising. + +From the point of view of a driver, what unambiguously identify a device are +its vendor and product USB identifiers. Below is a list of known identifiers of +devices mounting the SN9C10x PC camera controllers: + +Vendor ID Product ID +--------- ---------- +0x0c45 0x6001 +0x0c45 0x6005 +0x0c45 0x6007 +0x0c45 0x6009 +0x0c45 0x600d +0x0c45 0x6024 +0x0c45 0x6025 +0x0c45 0x6028 +0x0c45 0x6029 +0x0c45 0x602a +0x0c45 0x602b +0x0c45 0x602c +0x0c45 0x602d +0x0c45 0x602e +0x0c45 0x6030 +0x0c45 0x6080 +0x0c45 0x6082 +0x0c45 0x6083 +0x0c45 0x6088 +0x0c45 0x608a +0x0c45 0x608b +0x0c45 0x608c +0x0c45 0x608e +0x0c45 0x608f +0x0c45 0x60a0 +0x0c45 0x60a2 +0x0c45 0x60a3 +0x0c45 0x60a8 +0x0c45 0x60aa +0x0c45 0x60ab +0x0c45 0x60ac +0x0c45 0x60ae +0x0c45 0x60af +0x0c45 0x60b0 +0x0c45 0x60b2 +0x0c45 0x60b3 +0x0c45 0x60b8 +0x0c45 0x60ba +0x0c45 0x60bb +0x0c45 0x60bc +0x0c45 0x60be + +The list above does not imply that all those devices work with this driver: up +until now only the ones that mount the following image sensors are supported; +kernel messages will always tell you whether this is the case: + +Model Manufacturer +----- ------------ +HV7131D Hynix Semiconductor, Inc. +MI-0343 Micron Technology, Inc. +OV7630 OmniVision Technologies, Inc. +PAS106B PixArt Imaging, Inc. +PAS202BCA PixArt Imaging, Inc. +PAS202BCB PixArt Imaging, Inc. +TAS5110C1B Taiwan Advanced Sensor Corporation +TAS5130D1B Taiwan Advanced Sensor Corporation + +All the available control settings of each image sensor are supported through +the V4L2 interface. + +Donations of new models for further testing and support would be much +appreciated. Non-available hardware will not be supported by the author of this +driver. + + +10. Notes for V4L2 application developers +========================================= +This driver follows the V4L2 API specifications. In particular, it enforces two +rules: + +- exactly one I/O method, either "mmap" or "read", is associated with each +file descriptor. Once it is selected, the application must close and reopen the +device to switch to the other I/O method; + +- although it is not mandatory, previously mapped buffer memory should always +be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. +The same number of buffers as before will be allocated again to match the size +of the new video frames, so you have to map the buffers again before any I/O +attempts on them. + +Consistently with the hardware limits, this driver also supports image +downscaling with arbitrary scaling factors from 1, 2 and 4 in both directions. +However, the V4L2 API specifications don't correctly define how the scaling +factor can be chosen arbitrarily by the "negotiation" of the "source" and +"target" rectangles. To work around this flaw, we have added the convention +that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the +scaling factor is restored to 1. + +This driver supports two different video formats: the first one is the "8-bit +Sequential Bayer" format and can be used to obtain uncompressed video data +from the device through the current I/O method, while the second one provides +"raw" compressed video data (without frame headers not related to the +compressed data). The compression quality may vary from 0 to 1 and can be +selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP V4L2 +ioctl's. For maximum flexibility, both the default active video format and the +default compression quality depend on how the image sensor being used is +initialized (as described in the documentation of the API for the image sensors +supplied by this driver). + + +11. Video frame formats [1] +======================= +The SN9C10x PC Camera Controllers can send images in two possible video +formats over the USB: either native "Sequential RGB Bayer" or Huffman +compressed. The latter is used to achieve high frame rates. The current video +format may be selected or queried from the user application by calling the +VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API +specifications. + +The name "Sequential Bayer" indicates the organization of the red, green and +blue pixels in one video frame. Each pixel is associated with a 8-bit long +value and is disposed in memory according to the pattern shown below: + +B[0] G[1] B[2] G[3] ... B[m-2] G[m-1] +G[m] R[m+1] G[m+2] R[m+2] ... G[2m-2] R[2m-1] +... +... B[(n-1)(m-2)] G[(n-1)(m-1)] +... G[n(m-2)] R[n(m-1)] + +The above matrix also represents the sequential or progressive read-out mode of +the (n, m) Bayer color filter array used in many CCD/CMOS image sensors. + +One compressed video frame consists of a bitstream that encodes for every R, G, +or B pixel the difference between the value of the pixel itself and some +reference pixel value. Pixels are organised in the Bayer pattern and the Bayer +sub-pixels are tracked individually and alternatingly. For example, in the +first line values for the B and G1 pixels are alternatingly encoded, while in +the second line values for the G2 and R pixels are alternatingly encoded. + +The pixel reference value is calculated as follows: +- the 4 top left pixels are encoded in raw uncompressed 8-bit format; +- the value in the top two rows is the value of the pixel left of the current + pixel; +- the value in the left column is the value of the pixel above the current + pixel; +- for all other pixels, the reference value is the average of the value of the + pixel on the left and the value of the pixel above the current pixel; +- there is one code in the bitstream that specifies the value of a pixel + directly (in 4-bit resolution); +- pixel values need to be clamped inside the range [0..255] for proper + decoding. + +The algorithm purely describes the conversion from compressed Bayer code used +in the SN9C10x chips to uncompressed Bayer. Additional steps are required to +convert this to a color image (i.e. a color interpolation algorithm). + +The following Huffman codes have been found: +0: +0 (relative to reference pixel value) +100: +4 +101: -4? +1110xxxx: set absolute value to xxxx.0000 +1101: +11 +1111: -11 +11001: +20 +110000: -20 +110001: ??? - these codes are apparently not used + +[1] The Huffman compression algorithm has been reverse-engineered and + documented by Bertrik Sikken. + + +12. Contact information +======================= +The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. + +GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is +'FCE635A4'; the public 1024-bit key should be available at any keyserver; +the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. + + +13. Credits +=========== +Many thanks to following persons for their contribute (listed in alphabetical +order): + +- Luca Capello for the donation of a webcam; +- Philippe Coval for having helped testing the PAS202BCA image sensor; +- Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the + donation of a webcam; +- Jon Hollstrom for the donation of a webcam; +- Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB + image sensor; +- Stefano Mozzi, who donated 45 EU; +- Andrew Pearce for the donation of a webcam; +- Bertrik Sikken, who reverse-engineered and documented the Huffman compression + algorithm used in the SN9C10x controllers and implemented the first decoder; +- Mizuno Takafumi for the donation of a webcam; +- an "anonymous" donator (who didn't want his name to be revealed) for the + donation of a webcam. diff --git a/Documentation/video4linux/stv680.txt b/Documentation/video4linux/stv680.txt new file mode 100644 index 00000000000..4f8946f32f5 --- /dev/null +++ b/Documentation/video4linux/stv680.txt @@ -0,0 +1,53 @@ +Linux driver for STV0680 based USB cameras + +Copyright, 2001, Kevin Sisson + + +INTRODUCTION: + +STMicroelectronics produces the STV0680B chip, which comes in two +types, -001 and -003. The -003 version allows the recording and downloading +of sound clips from the camera, and allows a flash attachment. Otherwise, +it uses the same commands as the -001 version. Both versions support a +variety of SDRAM sizes and sensors, allowing for a maximum of 26 VGA or 20 +CIF pictures. The STV0680 supports either a serial or a usb interface, and +video is possible through the usb interface. + +The following cameras are known to work with this driver, although any +camera with Vendor/Product codes of 0553/0202 should work: + +Aiptek Pencam (various models) +Nisis QuickPix 2 +Radio Shack 'Kid's digital camera' (#60-1207) +At least one Trust Spycam model +Several other European brand models + +WHAT YOU NEED: + +- USB support +- VIDEO4LINUX support + +More information about USB support for linux can be found at: +http://www.linux-usb.org + + +MODULE OPTIONS: + +When the driver is compiled as a module, you can set a "swapRGB=1" +option, if necessary, for those applications that require it +(such as xawtv). However, the driver should detect and set this +automatically, so this option should not normally be used. + + +KNOWN PROBLEMS: + +The driver seems to work better with the usb-ohci than the usb-uhci host +controller driver. + +HELP: + +The latest info on this driver can be found at: +http://personal.clt.bellsouth.net/~kjsisson or at +http://stv0680-usb.sourceforge.net + +Any questions to me can be send to: kjsisson@bellsouth.net
\ No newline at end of file diff --git a/Documentation/video4linux/w9968cf.txt b/Documentation/video4linux/w9968cf.txt new file mode 100644 index 00000000000..3b704f2aae6 --- /dev/null +++ b/Documentation/video4linux/w9968cf.txt @@ -0,0 +1,461 @@ + + W996[87]CF JPEG USB Dual Mode Camera Chip + Driver for Linux 2.6 (basic version) + ========================================= + + - Documentation - + + +Index +===== +1. Copyright +2. Disclaimer +3. License +4. Overview +5. Supported devices +6. Module dependencies +7. Module loading +8. Module paramaters +9. Contact information +10. Credits + + +1. Copyright +============ +Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it> + + +2. Disclaimer +============= +Winbond is a trademark of Winbond Electronics Corporation. +This software is not sponsored or developed by Winbond. + + +3. License +========== +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +4. Overview +=========== +This driver supports the video streaming capabilities of the devices mounting +Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681 +based cameras should be supported as well. + +The driver is divided into two modules: the basic one, "w9968cf", is needed for +the supported devices to work; the second one, "w9968cf-vpp", is an optional +module, which provides some useful video post-processing functions like video +decoding, up-scaling and colour conversions. + +Note that the official kernels do neither include nor support the second +module for performance purposes. Therefore, it is always recommended to +download and install the latest and complete release of the driver, +replacing the existing one, if present. + +The latest and full-featured version of the W996[87]CF driver can be found at: +http://www.linux-projects.org. Please refer to the documentation included in +that package, if you are going to use it. + +Up to 32 cameras can be handled at the same time. They can be connected and +disconnected from the host many times without turning off the computer, if +your system supports the hotplug facility. + +To change the default settings for each camera, many parameters can be passed +through command line when the module is loaded into memory. + +The driver relies on the Video4Linux, USB and I2C core modules. It has been +designed to run properly on SMP systems as well. An additional module, +"ovcamchip", is mandatory; it provides support for some OmniVision image +sensors connected to the W996[87]CF chips; if found in the system, the module +will be automatically loaded by default (provided that the kernel has been +compiled with the automatic module loading option). + + +5. Supported devices +==================== +At the moment, known W996[87]CF and OV681 based devices are: +- Aroma Digi Pen VGA Dual Mode ADG-5000 (unknown image sensor) +- AVerMedia AVerTV USB (SAA7111A, Philips FI1216Mk2 tuner, PT2313L audio chip) +- Creative Labs Video Blaster WebCam Go (OmniVision OV7610 sensor) +- Creative Labs Video Blaster WebCam Go Plus (OmniVision OV7620 sensor) +- Lebon LDC-035A (unknown image sensor) +- Ezonics EZ-802 EZMega Cam (OmniVision OV8610C sensor) +- OmniVision OV8610-EDE (OmniVision OV8610 sensor) +- OPCOM Digi Pen VGA Dual Mode Pen Camera (unknown image sensor) +- Pretec Digi Pen-II (OmniVision OV7620 sensor) +- Pretec DigiPen-480 (OmniVision OV8610 sensor) + +If you know any other W996[87]CF or OV681 based cameras, please contact me. + +The list above does not imply that all those devices work with this driver: up +until now only webcams that have an image sensor supported by the "ovcamchip" +module work. Kernel messages will always tell you whether this is case. + +Possible external microcontrollers of those webcams are not supported: this +means that still images cannot be downloaded from the device memory. + +Furthermore, it's worth to note that I was only able to run tests on my +"Creative Labs Video Blaster WebCam Go". Donations of other models, for +additional testing and full support, would be much appreciated. + + +6. Module dependencies +====================== +For it to work properly, the driver needs kernel support for Video4Linux, USB +and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not +actually using any external "ovcamchip" module, given that the W996[87]CF +driver depends on the version of the module present in the official kernels. + +The following options of the kernel configuration file must be enabled and +corresponding modules must be compiled: + + # Multimedia devices + # + CONFIG_VIDEO_DEV=m + + # I2C support + # + CONFIG_I2C=m + +The I2C core module can be compiled statically in the kernel as well. + + # OmniVision Camera Chip support + # + CONFIG_VIDEO_OVCAMCHIP=m + + # USB support + # + CONFIG_USB=m + +In addition, depending on the hardware being used, only one of the modules +below is necessary: + + # USB Host Controller Drivers + # + CONFIG_USB_EHCI_HCD=m + CONFIG_USB_UHCI_HCD=m + CONFIG_USB_OHCI_HCD=m + +And finally: + + # USB Multimedia devices + # + CONFIG_USB_W9968CF=m + + +7. Module loading +================= +To use the driver, it is necessary to load the "w9968cf" module into memory +after every other module required. + +Loading can be done this way, from root: + + [root@localhost home]# modprobe usbcore + [root@localhost home]# modprobe i2c-core + [root@localhost home]# modprobe videodev + [root@localhost home]# modprobe w9968cf + +At this point the pertinent devices should be recognized: "dmesg" can be used +to analyze kernel messages: + + [user@localhost home]$ dmesg + +There are a lot of parameters the module can use to change the default +settings for each device. To list every possible parameter with a brief +explanation about them and which syntax to use, it is recommended to run the +"modinfo" command: + + [root@locahost home]# modinfo w9968cf + + +8. Module parameters +==================== +Module parameters are listed below: +------------------------------------------------------------------------------- +Name: ovmod_load +Type: bool +Syntax: <0|1> +Description: Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled. + If enabled, 'insmod' searches for the required 'ovcamchip' + module in the system, according to its configuration, and + loads that module automatically. This action is performed as + once soon as the 'w9968cf' module is loaded into memory. +Default: 1 +Note: The kernel must be compiled with the CONFIG_KMOD option + enabled for the 'ovcamchip' module to be loaded and for + this parameter to be present. +------------------------------------------------------------------------------- +Name: simcams +Type: int +Syntax: <n> +Description: Number of cameras allowed to stream simultaneously. + n may vary from 0 to 32. +Default: 32 +------------------------------------------------------------------------------- +Name: video_nr +Type: int array (min = 0, max = 32) +Syntax: <-1|n[,...]> +Description: Specify V4L minor mode number. + -1 = use next available + n = use minor number n + You can specify up to 32 cameras this way. + For example: + video_nr=-1,2,-1 would assign minor number 2 to the second + recognized camera and use auto for the first one and for every + other camera. +Default: -1 +------------------------------------------------------------------------------- +Name: packet_size +Type: int array (min = 0, max = 32) +Syntax: <n[,...]> +Description: Specify the maximum data payload size in bytes for alternate + settings, for each device. n is scaled between 63 and 1023. +Default: 1023 +------------------------------------------------------------------------------- +Name: max_buffers +Type: int array (min = 0, max = 32) +Syntax: <n[,...]> +Description: For advanced users. + Specify the maximum number of video frame buffers to allocate + for each device, from 2 to 32. +Default: 2 +------------------------------------------------------------------------------- +Name: double_buffer +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Hardware double buffering: 0 disabled, 1 enabled. + It should be enabled if you want smooth video output: if you + obtain out of sync. video, disable it, or try to + decrease the 'clockdiv' module parameter value. +Default: 1 for every device. +------------------------------------------------------------------------------- +Name: clamping +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Video data clamping: 0 disabled, 1 enabled. +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: filter_type +Type: int array (min = 0, max = 32) +Syntax: <0|1|2[,...]> +Description: Video filter type. + 0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter. + The filter is used to reduce noise and aliasing artifacts + produced by the CCD or CMOS image sensor. +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: largeview +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Large view: 0 disabled, 1 enabled. +Default: 1 for every device. +------------------------------------------------------------------------------- +Name: upscaling +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Software scaling (for non-compressed video only): + 0 disabled, 1 enabled. + Disable it if you have a slow CPU or you don't have enough + memory. +Default: 0 for every device. +Note: If 'w9968cf-vpp' is not present, this parameter is set to 0. +------------------------------------------------------------------------------- +Name: decompression +Type: int array (min = 0, max = 32) +Syntax: <0|1|2[,...]> +Description: Software video decompression: + 0 = disables decompression + (doesn't allow formats needing decompression). + 1 = forces decompression + (allows formats needing decompression only). + 2 = allows any permitted formats. + Formats supporting (de)compressed video are YUV422P and + YUV420P/YUV420 in any resolutions where width and height are + multiples of 16. +Default: 2 for every device. +Note: If 'w9968cf-vpp' is not present, forcing decompression is not + allowed; in this case this parameter is set to 2. +------------------------------------------------------------------------------- +Name: force_palette +Type: int array (min = 0, max = 32) +Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]> +Description: Force picture palette. + In order: + 0 = Off - allows any of the following formats: + 9 = UYVY 16 bpp - Original video, compression disabled + 10 = YUV420 12 bpp - Original video, compression enabled + 13 = YUV422P 16 bpp - Original video, compression enabled + 15 = YUV420P 12 bpp - Original video, compression enabled + 8 = YUVY 16 bpp - Software conversion from UYVY + 7 = YUV422 16 bpp - Software conversion from UYVY + 1 = GREY 8 bpp - Software conversion from UYVY + 6 = RGB555 16 bpp - Software conversion from UYVY + 3 = RGB565 16 bpp - Software conversion from UYVY + 4 = RGB24 24 bpp - Software conversion from UYVY + 5 = RGB32 32 bpp - Software conversion from UYVY + When not 0, this parameter will override 'decompression'. +Default: 0 for every device. Initial palette is 9 (UYVY). +Note: If 'w9968cf-vpp' is not present, this parameter is set to 9. +------------------------------------------------------------------------------- +Name: force_rgb +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Read RGB video data instead of BGR: + 1 = use RGB component ordering. + 0 = use BGR component ordering. + This parameter has effect when using RGBX palettes only. +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: autobright +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Image sensor automatically changes brightness: + 0 = no, 1 = yes +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: autoexp +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Image sensor automatically changes exposure: + 0 = no, 1 = yes +Default: 1 for every device. +------------------------------------------------------------------------------- +Name: lightfreq +Type: int array (min = 0, max = 32) +Syntax: <50|60[,...]> +Description: Light frequency in Hz: + 50 for European and Asian lighting, 60 for American lighting. +Default: 50 for every device. +------------------------------------------------------------------------------- +Name: bandingfilter +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Banding filter to reduce effects of fluorescent + lighting: + 0 disabled, 1 enabled. + This filter tries to reduce the pattern of horizontal + light/dark bands caused by some (usually fluorescent) lighting. +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: clockdiv +Type: int array (min = 0, max = 32) +Syntax: <-1|n[,...]> +Description: Force pixel clock divisor to a specific value (for experts): + n may vary from 0 to 127. + -1 for automatic value. + See also the 'double_buffer' module parameter. +Default: -1 for every device. +------------------------------------------------------------------------------- +Name: backlight +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Objects are lit from behind: + 0 = no, 1 = yes +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: mirror +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: Reverse image horizontally: + 0 = no, 1 = yes +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: monochrome +Type: bool array (min = 0, max = 32) +Syntax: <0|1[,...]> +Description: The image sensor is monochrome: + 0 = no, 1 = yes +Default: 0 for every device. +------------------------------------------------------------------------------- +Name: brightness +Type: long array (min = 0, max = 32) +Syntax: <n[,...]> +Description: Set picture brightness (0-65535). + This parameter has no effect if 'autobright' is enabled. +Default: 31000 for every device. +------------------------------------------------------------------------------- +Name: hue +Type: long array (min = 0, max = 32) +Syntax: <n[,...]> +Description: Set picture hue (0-65535). +Default: 32768 for every device. +------------------------------------------------------------------------------- +Name: colour +Type: long array (min = 0, max = 32) +Syntax: <n[,...]> +Description: Set picture saturation (0-65535). +Default: 32768 for every device. +------------------------------------------------------------------------------- +Name: contrast +Type: long array (min = 0, max = 32) +Syntax: <n[,...]> +Description: Set picture contrast (0-65535). +Default: 50000 for every device. +------------------------------------------------------------------------------- +Name: whiteness +Type: long array (min = 0, max = 32) +Syntax: <n[,...]> +Description: Set picture whiteness (0-65535). +Default: 32768 for every device. +------------------------------------------------------------------------------- +Name: debug +Type: int +Syntax: <n> +Description: Debugging information level, from 0 to 6: + 0 = none (use carefully) + 1 = critical errors + 2 = significant informations + 3 = configuration or general messages + 4 = warnings + 5 = called functions + 6 = function internals + Level 5 and 6 are useful for testing only, when only one + device is used. +Default: 2 +------------------------------------------------------------------------------- +Name: specific_debug +Type: bool +Syntax: <0|1> +Description: Enable or disable specific debugging messages: + 0 = print messages concerning every level <= 'debug' level. + 1 = print messages concerning the level indicated by 'debug'. +Default: 0 +------------------------------------------------------------------------------- + + +9. Contact information +====================== +I may be contacted by e-mail at <luca.risolia@studio.unibo.it>. + +I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'. +My public 1024-bit key should be available at your keyserver; the fingerprint +is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. + + +10. Credits +========== +The development would not have proceed much further without having looked at +the source code of other drivers and without the help of several persons; in +particular: + +- the I2C interface to kernel and high-level image sensor control routines have + been taken from the OV511 driver by Mark McClelland; + +- memory management code has been copied from the bttv driver by Ralph Metzler, + Marcus Metzler and Gerd Knorr; + +- the low-level I2C read function has been written by Frederic Jouault; + +- the low-level I2C fast write function has been written by Piotr Czerczak. diff --git a/Documentation/video4linux/zc0301.txt b/Documentation/video4linux/zc0301.txt new file mode 100644 index 00000000000..f55262c6733 --- /dev/null +++ b/Documentation/video4linux/zc0301.txt @@ -0,0 +1,254 @@ + + ZC0301 Image Processor and Control Chip + Driver for Linux + ======================================= + + - Documentation - + + +Index +===== +1. Copyright +2. Disclaimer +3. License +4. Overview and features +5. Module dependencies +6. Module loading +7. Module parameters +8. Supported devices +9. Notes for V4L2 application developers +10. Contact information +11. Credits + + +1. Copyright +============ +Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it> + + +2. Disclaimer +============= +This software is not developed or sponsored by Z-Star Microelectronics Corp. +Trademarks are property of their respective owner. + + +3. License +========== +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +4. Overview and features +======================== +This driver supports the video interface of the devices mounting the ZC0301 +Image Processor and Control Chip. + +The driver relies on the Video4Linux2 and USB core modules. It has been +designed to run properly on SMP systems as well. + +The latest version of the ZC0301 driver can be found at the following URL: +http://www.linux-projects.org/ + +Some of the features of the driver are: + +- full compliance with the Video4Linux2 API (see also "Notes for V4L2 + application developers" paragraph); +- available mmap or read/poll methods for video streaming through isochronous + data transfers; +- automatic detection of image sensor; +- video format is standard JPEG; +- dynamic driver control thanks to various module parameters (see "Module + parameters" paragraph); +- up to 64 cameras can be handled at the same time; they can be connected and + disconnected from the host many times without turning off the computer, if + the system supports hotplugging; + + +5. Module dependencies +====================== +For it to work properly, the driver needs kernel support for Video4Linux and +USB. + +The following options of the kernel configuration file must be enabled and +corresponding modules must be compiled: + + # Multimedia devices + # + CONFIG_VIDEO_DEV=m + + # USB support + # + CONFIG_USB=m + +In addition, depending on the hardware being used, the modules below are +necessary: + + # USB Host Controller Drivers + # + CONFIG_USB_EHCI_HCD=m + CONFIG_USB_UHCI_HCD=m + CONFIG_USB_OHCI_HCD=m + +The ZC0301 controller also provides a built-in microphone interface. It is +supported by the USB Audio driver thanks to the ALSA API: + + # Sound + # + CONFIG_SOUND=y + + # Advanced Linux Sound Architecture + # + CONFIG_SND=m + + # USB devices + # + CONFIG_SND_USB_AUDIO=m + +And finally: + + # USB Multimedia devices + # + CONFIG_USB_ZC0301=m + + +6. Module loading +================= +To use the driver, it is necessary to load the "zc0301" module into memory +after every other module required: "videodev", "usbcore" and, depending on +the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". + +Loading can be done as shown below: + + [root@localhost home]# modprobe zc0301 + +At this point the devices should be recognized. You can invoke "dmesg" to +analyze kernel messages and verify that the loading process has gone well: + + [user@localhost home]$ dmesg + + +7. Module parameters +==================== +Module parameters are listed below: +------------------------------------------------------------------------------- +Name: video_nr +Type: short array (min = 0, max = 64) +Syntax: <-1|n[,...]> +Description: Specify V4L2 minor mode number: + -1 = use next available + n = use minor number n + You can specify up to 64 cameras this way. + For example: + video_nr=-1,2,-1 would assign minor number 2 to the second + registered camera and use auto for the first one and for every + other camera. +Default: -1 +------------------------------------------------------------------------------- +Name: force_munmap +Type: bool array (min = 0, max = 64) +Syntax: <0|1[,...]> +Description: Force the application to unmap previously mapped buffer memory + before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not + all the applications support this feature. This parameter is + specific for each detected camera. + 0 = do not force memory unmapping + 1 = force memory unmapping (save memory) +Default: 0 +------------------------------------------------------------------------------- +Name: frame_timeout +Type: uint array (min = 0, max = 64) +Syntax: <n[,...]> +Description: Timeout for a video frame in seconds. This parameter is + specific for each detected camera. This parameter can be + changed at runtime thanks to the /sys filesystem interface. +Default: 2 +------------------------------------------------------------------------------- +Name: debug +Type: ushort +Syntax: <n> +Description: Debugging information level, from 0 to 3: + 0 = none (use carefully) + 1 = critical errors + 2 = significant informations + 3 = more verbose messages + Level 3 is useful for testing only, when only one device + is used at the same time. It also shows some more informations + about the hardware being detected. This module parameter can be + changed at runtime thanks to the /sys filesystem interface. +Default: 2 +------------------------------------------------------------------------------- + + +8. Supported devices +==================== +None of the names of the companies as well as their products will be mentioned +here. They have never collaborated with the author, so no advertising. + +From the point of view of a driver, what unambiguously identify a device are +its vendor and product USB identifiers. Below is a list of known identifiers of +devices mounting the ZC0301 Image Processor and Control Chips: + +Vendor ID Product ID +--------- ---------- +0x041e 0x4017 +0x041e 0x401c +0x041e 0x401e +0x041e 0x4034 +0x041e 0x4035 +0x046d 0x08ae +0x0ac8 0x0301 +0x10fd 0x8050 + +The list above does not imply that all those devices work with this driver: up +until now only the ones that mount the following image sensors are supported; +kernel messages will always tell you whether this is the case: + +Model Manufacturer +----- ------------ +PAS202BCB PixArt Imaging, Inc. + + +9. Notes for V4L2 application developers +======================================== +This driver follows the V4L2 API specifications. In particular, it enforces two +rules: + +- exactly one I/O method, either "mmap" or "read", is associated with each +file descriptor. Once it is selected, the application must close and reopen the +device to switch to the other I/O method; + +- although it is not mandatory, previously mapped buffer memory should always +be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. +The same number of buffers as before will be allocated again to match the size +of the new video frames, so you have to map the buffers again before any I/O +attempts on them. + + +10. Contact information +======================= +The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. + +GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is +'FCE635A4'; the public 1024-bit key should be available at any keyserver; +the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. + + +11. Credits +=========== +- Informations about the chip internals needed to enable the I2C protocol have + been taken from the documentation of the ZC030x Video4Linux1 driver written + by Andrew Birkett <andy@nobugs.org>; +- The initialization values of the ZC0301 controller connected to the PAS202BCB + image sensor have been taken from the SPCA5XX driver maintained by + Michel Xhaard <mxhaard@magic.fr>. |