aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/video4linux
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/video4linux')
-rw-r--r--Documentation/video4linux/et61x251.txt314
-rw-r--r--Documentation/video4linux/ibmcam.txt324
-rw-r--r--Documentation/video4linux/ov511.txt288
-rw-r--r--Documentation/video4linux/se401.txt54
-rw-r--r--Documentation/video4linux/sn9c102.txt518
-rw-r--r--Documentation/video4linux/stv680.txt53
-rw-r--r--Documentation/video4linux/w9968cf.txt461
-rw-r--r--Documentation/video4linux/zc0301.txt254
8 files changed, 2266 insertions, 0 deletions
diff --git a/Documentation/video4linux/et61x251.txt b/Documentation/video4linux/et61x251.txt
new file mode 100644
index 000000000000..29340282ab5f
--- /dev/null
+++ b/Documentation/video4linux/et61x251.txt
@@ -0,0 +1,314 @@
1
2 ET61X[12]51 PC Camera Controllers
3 Driver for Linux
4 =================================
5
6 - Documentation -
7
8
9Index
10=====
111. Copyright
122. Disclaimer
133. License
144. Overview and features
155. Module dependencies
166. Module loading
177. Module parameters
188. Optional device control through "sysfs"
199. Supported devices
2010. Notes for V4L2 application developers
2111. Contact information
22
23
241. Copyright
25============
26Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it>
27
28
292. Disclaimer
30=============
31Etoms is a trademark of Etoms Electronics Corp.
32This software is not developed or sponsored by Etoms Electronics.
33
34
353. License
36==========
37This program is free software; you can redistribute it and/or modify
38it under the terms of the GNU General Public License as published by
39the Free Software Foundation; either version 2 of the License, or
40(at your option) any later version.
41
42This program is distributed in the hope that it will be useful,
43but WITHOUT ANY WARRANTY; without even the implied warranty of
44MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
45GNU General Public License for more details.
46
47You should have received a copy of the GNU General Public License
48along with this program; if not, write to the Free Software
49Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
50
51
524. Overview and features
53========================
54This driver supports the video interface of the devices mounting the ET61X151
55or ET61X251 PC Camera Controllers.
56
57It's worth to note that Etoms Electronics has never collaborated with the
58author during the development of this project; despite several requests,
59Etoms Electronics also refused to release enough detailed specifications of
60the video compression engine.
61
62The driver relies on the Video4Linux2 and USB core modules. It has been
63designed to run properly on SMP systems as well.
64
65The latest version of the ET61X[12]51 driver can be found at the following URL:
66http://www.linux-projects.org/
67
68Some of the features of the driver are:
69
70- full compliance with the Video4Linux2 API (see also "Notes for V4L2
71 application developers" paragraph);
72- available mmap or read/poll methods for video streaming through isochronous
73 data transfers;
74- automatic detection of image sensor;
75- support for any window resolutions and optional panning within the maximum
76 pixel area of image sensor;
77- image downscaling with arbitrary scaling factors from 1 and 2 in both
78 directions (see "Notes for V4L2 application developers" paragraph);
79- two different video formats for uncompressed or compressed data in low or
80 high compression quality (see also "Notes for V4L2 application developers"
81 paragraph);
82- full support for the capabilities of every possible image sensors that can
83 be connected to the ET61X[12]51 bridges, including, for istance, red, green,
84 blue and global gain adjustments and exposure control (see "Supported
85 devices" paragraph for details);
86- use of default color settings for sunlight conditions;
87- dynamic I/O interface for both ET61X[12]51 and image sensor control (see
88 "Optional device control through 'sysfs'" paragraph);
89- dynamic driver control thanks to various module parameters (see "Module
90 parameters" paragraph);
91- up to 64 cameras can be handled at the same time; they can be connected and
92 disconnected from the host many times without turning off the computer, if
93 the system supports hotplugging;
94- no known bugs.
95
96
975. Module dependencies
98======================
99For it to work properly, the driver needs kernel support for Video4Linux and
100USB.
101
102The following options of the kernel configuration file must be enabled and
103corresponding modules must be compiled:
104
105 # Multimedia devices
106 #
107 CONFIG_VIDEO_DEV=m
108
109To enable advanced debugging functionality on the device through /sysfs:
110
111 # Multimedia devices
112 #
113 CONFIG_VIDEO_ADV_DEBUG=y
114
115 # USB support
116 #
117 CONFIG_USB=m
118
119In addition, depending on the hardware being used, the modules below are
120necessary:
121
122 # USB Host Controller Drivers
123 #
124 CONFIG_USB_EHCI_HCD=m
125 CONFIG_USB_UHCI_HCD=m
126 CONFIG_USB_OHCI_HCD=m
127
128And finally:
129
130 # USB Multimedia devices
131 #
132 CONFIG_USB_ET61X251=m
133
134
1356. Module loading
136=================
137To use the driver, it is necessary to load the "et61x251" module into memory
138after every other module required: "videodev", "usbcore" and, depending on
139the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd".
140
141Loading can be done as shown below:
142
143 [root@localhost home]# modprobe et61x251
144
145At this point the devices should be recognized. You can invoke "dmesg" to
146analyze kernel messages and verify that the loading process has gone well:
147
148 [user@localhost home]$ dmesg
149
150
1517. Module parameters
152====================
153Module parameters are listed below:
154-------------------------------------------------------------------------------
155Name: video_nr
156Type: short array (min = 0, max = 64)
157Syntax: <-1|n[,...]>
158Description: Specify V4L2 minor mode number:
159 -1 = use next available
160 n = use minor number n
161 You can specify up to 64 cameras this way.
162 For example:
163 video_nr=-1,2,-1 would assign minor number 2 to the second
164 registered camera and use auto for the first one and for every
165 other camera.
166Default: -1
167-------------------------------------------------------------------------------
168Name: force_munmap
169Type: bool array (min = 0, max = 64)
170Syntax: <0|1[,...]>
171Description: Force the application to unmap previously mapped buffer memory
172 before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not
173 all the applications support this feature. This parameter is
174 specific for each detected camera.
175 0 = do not force memory unmapping
176 1 = force memory unmapping (save memory)
177Default: 0
178-------------------------------------------------------------------------------
179Name: frame_timeout
180Type: uint array (min = 0, max = 64)
181Syntax: <n[,...]>
182Description: Timeout for a video frame in seconds. This parameter is
183 specific for each detected camera. This parameter can be
184 changed at runtime thanks to the /sys filesystem interface.
185Default: 2
186-------------------------------------------------------------------------------
187Name: debug
188Type: ushort
189Syntax: <n>
190Description: Debugging information level, from 0 to 3:
191 0 = none (use carefully)
192 1 = critical errors
193 2 = significant informations
194 3 = more verbose messages
195 Level 3 is useful for testing only, when only one device
196 is used at the same time. It also shows some more informations
197 about the hardware being detected. This module parameter can be
198 changed at runtime thanks to the /sys filesystem interface.
199Default: 2
200-------------------------------------------------------------------------------
201
202
2038. Optional device control through "sysfs"
204==========================================
205If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
206it is possible to read and write both the ET61X[12]51 and the image sensor
207registers by using the "sysfs" filesystem interface.
208
209There are four files in the /sys/class/video4linux/videoX directory for each
210registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files
211control the ET61X[12]51 bridge, while the other two control the sensor chip.
212"reg" and "i2c_reg" hold the values of the current register index where the
213following reading/writing operations are addressed at through "val" and
214"i2c_val". Their use is not intended for end-users, unless you know what you
215are doing. Remember that you must be logged in as root before writing to them.
216
217As an example, suppose we were to want to read the value contained in the
218register number 1 of the sensor register table - which is usually the product
219identifier - of the camera registered as "/dev/video0":
220
221 [root@localhost #] cd /sys/class/video4linux/video0
222 [root@localhost #] echo 1 > i2c_reg
223 [root@localhost #] cat i2c_val
224
225Note that if the sensor registers can not be read, "cat" will fail.
226To avoid race conditions, all the I/O accesses to the files are serialized.
227
228
2299. Supported devices
230====================
231None of the names of the companies as well as their products will be mentioned
232here. They have never collaborated with the author, so no advertising.
233
234From the point of view of a driver, what unambiguously identify a device are
235its vendor and product USB identifiers. Below is a list of known identifiers of
236devices mounting the ET61X[12]51 PC camera controllers:
237
238Vendor ID Product ID
239--------- ----------
2400x102c 0x6151
2410x102c 0x6251
2420x102c 0x6253
2430x102c 0x6254
2440x102c 0x6255
2450x102c 0x6256
2460x102c 0x6257
2470x102c 0x6258
2480x102c 0x6259
2490x102c 0x625a
2500x102c 0x625b
2510x102c 0x625c
2520x102c 0x625d
2530x102c 0x625e
2540x102c 0x625f
2550x102c 0x6260
2560x102c 0x6261
2570x102c 0x6262
2580x102c 0x6263
2590x102c 0x6264
2600x102c 0x6265
2610x102c 0x6266
2620x102c 0x6267
2630x102c 0x6268
2640x102c 0x6269
265
266The following image sensors are supported:
267
268Model Manufacturer
269----- ------------
270TAS5130D1B Taiwan Advanced Sensor Corporation
271
272All the available control settings of each image sensor are supported through
273the V4L2 interface.
274
275
27610. Notes for V4L2 application developers
277=========================================
278This driver follows the V4L2 API specifications. In particular, it enforces two
279rules:
280
281- exactly one I/O method, either "mmap" or "read", is associated with each
282file descriptor. Once it is selected, the application must close and reopen the
283device to switch to the other I/O method;
284
285- although it is not mandatory, previously mapped buffer memory should always
286be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
287The same number of buffers as before will be allocated again to match the size
288of the new video frames, so you have to map the buffers again before any I/O
289attempts on them.
290
291Consistently with the hardware limits, this driver also supports image
292downscaling with arbitrary scaling factors from 1 and 2 in both directions.
293However, the V4L2 API specifications don't correctly define how the scaling
294factor can be chosen arbitrarily by the "negotiation" of the "source" and
295"target" rectangles. To work around this flaw, we have added the convention
296that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the
297scaling factor is restored to 1.
298
299This driver supports two different video formats: the first one is the "8-bit
300Sequential Bayer" format and can be used to obtain uncompressed video data
301from the device through the current I/O method, while the second one provides
302"raw" compressed video data (without frame headers not related to the
303compressed data). The current compression quality may vary from 0 to 1 and can
304be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP
305V4L2 ioctl's.
306
307
30811. Contact information
309=======================
310The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
311
312GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is
313'FCE635A4'; the public 1024-bit key should be available at any keyserver;
314the 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 000000000000..4a40a2e99451
--- /dev/null
+++ b/Documentation/video4linux/ibmcam.txt
@@ -0,0 +1,324 @@
1README for Linux device driver for the IBM "C-It" USB video camera
2
3INTRODUCTION:
4
5This driver does not use all features known to exist in
6the IBM camera. However most of needed features work well.
7
8This driver was developed using logs of observed USB traffic
9which was produced by standard Windows driver (c-it98.sys).
10I did not have data sheets from Xirlink.
11
12Video formats:
13 128x96 [model 1]
14 176x144
15 320x240 [model 2]
16 352x240 [model 2]
17 352x288
18Frame rate: 3 - 30 frames per second (FPS)
19External interface: USB
20Internal interface: Video For Linux (V4L)
21Supported controls:
22- by V4L: Contrast, Brightness, Color, Hue
23- by driver options: frame rate, lighting conditions, video format,
24 default picture settings, sharpness.
25
26SUPPORTED CAMERAS:
27
28Xirlink "C-It" camera, also known as "IBM PC Camera".
29The device uses proprietary ASIC (and compression method);
30it is manufactured by Xirlink. See http://www.xirlink.com/
31(renamed to http://www.veo.com), http://www.ibmpccamera.com,
32or http://www.c-itnow.com/ for details and pictures.
33
34This very chipset ("X Chip", as marked at the factory)
35is used in several other cameras, and they are supported
36as well:
37
38- IBM NetCamera
39- Veo Stingray
40
41The Linux driver was developed with camera with following
42model number (or FCC ID): KSX-XVP510. This camera has three
43interfaces, each with one endpoint (control, iso, iso). This
44type of cameras is referred to as "model 1". These cameras are
45no longer manufactured.
46
47Xirlink now manufactures new cameras which are somewhat different.
48In particular, following models [FCC ID] belong to that category:
49
50XVP300 [KSX-X9903]
51XVP600 [KSX-X9902]
52XVP610 [KSX-X9902]
53
54(see http://www.xirlink.com/ibmpccamera/ for updates, they refer
55to these new cameras by Windows driver dated 12-27-99, v3005 BETA)
56These cameras have two interfaces, one endpoint in each (iso, bulk).
57Such type of cameras is referred to as "model 2". They are supported
58(with exception of 352x288 native mode).
59
60Some IBM NetCameras (Model 4) are made to generate only compressed
61video streams. This is great for performance, but unfortunately
62nobody knows how to decompress the stream :-( Therefore, these
63cameras are *unsupported* and if you try to use one of those, all
64you get is random colored horizontal streaks, not the image!
65If you have one of those cameras, you probably should return it
66to the store and get something that is supported.
67
68Tell me more about all that "model" business
69--------------------------------------------
70
71I just invented model numbers to uniquely identify flavors of the
72hardware/firmware that were sold. It was very confusing to use
73brand names or some other internal numbering schemes. So I found
74by experimentation that all Xirlink chipsets fall into four big
75classes, and I called them "models". Each model is programmed in
76its own way, and each model sends back the video in its own way.
77
78Quirks of Model 2 cameras:
79-------------------------
80
81Model 2 does not have hardware contrast control. Corresponding V4L
82control is implemented in software, which is not very nice to your
83CPU, but at least it works.
84
85This driver provides 352x288 mode by switching the camera into
86quasi-352x288 RGB mode (800 Kbits per frame) essentially limiting
87this mode to 10 frames per second or less, in ideal conditions on
88the bus (USB is shared, after all). The frame rate
89has to be programmed very conservatively. Additional concern is that
90frame rate depends on brightness setting; therefore the picture can
91be good at one brightness and broken at another! I did not want to fix
92the frame rate at slowest setting, but I had to move it pretty much down
93the scale (so that framerate option barely matters). I also noticed that
94camera after first powering up produces frames slightly faster than during
95consecutive uses. All this means that if you use 352x288 (which is
96default), be warned - you may encounter broken picture on first connect;
97try to adjust brightness - brighter image is slower, so USB will be able
98to send all data. However if you regularly use Model 2 cameras you may
99prefer 176x144 which makes perfectly good I420, with no scaling and
100lesser demands on USB (300 Kbits per second, or 26 frames per second).
101
102Another strange effect of 352x288 mode is the fine vertical grid visible
103on some colored surfaces. I am sure it is caused by me not understanding
104what the camera is trying to say. Blame trade secrets for that.
105
106The camera that I had also has a hardware quirk: if disconnected,
107it needs few minutes to "relax" before it can be plugged in again
108(poorly designed USB processor reset circuit?)
109
110[Veo Stingray with Product ID 0x800C is also Model 2, but I haven't
111observed this particular flaw in it.]
112
113Model 2 camera can be programmed for very high sensitivity (even starlight
114may be enough), this makes it convenient for tinkering with. The driver
115code has enough comments to help a programmer to tweak the camera
116as s/he feels necessary.
117
118WHAT YOU NEED:
119
120- A supported IBM PC (C-it) camera (model 1 or 2)
121
122- A Linux box with USB support (2.3/2.4; 2.2 w/backport may work)
123
124- A Video4Linux compatible frame grabber program such as xawtv.
125
126HOW TO COMPILE THE DRIVER:
127
128You need to compile the driver only if you are a developer
129or if you want to make changes to the code. Most distributions
130precompile all modules, so you can go directly to the next
131section "HOW TO USE THE DRIVER".
132
133The ibmcam driver uses usbvideo helper library (module),
134so if you are studying the ibmcam code you will be led there.
135
136The driver itself consists of only one file in usb/ directory:
137ibmcam.c. This file is included into the Linux kernel build
138process if you configure the kernel for CONFIG_USB_IBMCAM.
139Run "make xconfig" and in USB section you will find the IBM
140camera driver. Select it, save the configuration and recompile.
141
142HOW TO USE THE DRIVER:
143
144I recommend to compile driver as a module. This gives you an
145easier access to its configuration. The camera has many more
146settings than V4L can operate, so some settings are done using
147module options.
148
149To begin with, on most modern Linux distributions the driver
150will be automatically loaded whenever you plug the supported
151camera in. Therefore, you don't need to do anything. However
152if you want to experiment with some module parameters then
153you can load and unload the driver manually, with camera
154plugged in or unplugged.
155
156Typically module is installed with command 'modprobe', like this:
157
158# modprobe ibmcam framerate=1
159
160Alternatively you can use 'insmod' in similar fashion:
161
162# insmod /lib/modules/2.x.y/usb/ibmcam.o framerate=1
163
164Module can be inserted with camera connected or disconnected.
165
166The driver can have options, though some defaults are provided.
167
168Driver options: (* indicates that option is model-dependent)
169
170Name Type Range [default] Example
171-------------- -------------- -------------- ------------------
172debug Integer 0-9 [0] debug=1
173flags Integer 0-0xFF [0] flags=0x0d
174framerate Integer 0-6 [2] framerate=1
175hue_correction Integer 0-255 [128] hue_correction=115
176init_brightness Integer 0-255 [128] init_brightness=100
177init_contrast Integer 0-255 [192] init_contrast=200
178init_color Integer 0-255 [128] init_color=130
179init_hue Integer 0-255 [128] init_hue=115
180lighting Integer 0-2* [1] lighting=2
181sharpness Integer 0-6* [4] sharpness=3
182size Integer 0-2* [2] size=1
183
184Options for Model 2 only:
185
186Name Type Range [default] Example
187-------------- -------------- -------------- ------------------
188init_model2_rg Integer 0..255 [0x70] init_model2_rg=128
189init_model2_rg2 Integer 0..255 [0x2f] init_model2_rg2=50
190init_model2_sat Integer 0..255 [0x34] init_model2_sat=65
191init_model2_yb Integer 0..255 [0xa0] init_model2_yb=200
192
193debug You don't need this option unless you are a developer.
194 If you are a developer then you will see in the code
195 what values do what. 0=off.
196
197flags This is a bit mask, and you can combine any number of
198 bits to produce what you want. Usually you don't want
199 any of extra features this option provides:
200
201 FLAGS_RETRY_VIDIOCSYNC 1 This bit allows to retry failed
202 VIDIOCSYNC ioctls without failing.
203 Will work with xawtv, will not
204 with xrealproducer. Default is
205 not set.
206 FLAGS_MONOCHROME 2 Activates monochrome (b/w) mode.
207 FLAGS_DISPLAY_HINTS 4 Shows colored pixels which have
208 magic meaning to developers.
209 FLAGS_OVERLAY_STATS 8 Shows tiny numbers on screen,
210 useful only for debugging.
211 FLAGS_FORCE_TESTPATTERN 16 Shows blue screen with numbers.
212 FLAGS_SEPARATE_FRAMES 32 Shows each frame separately, as
213 it was received from the camera.
214 Default (not set) is to mix the
215 preceding frame in to compensate
216 for occasional loss of Isoc data
217 on high frame rates.
218 FLAGS_CLEAN_FRAMES 64 Forces "cleanup" of each frame
219 prior to use; relevant only if
220 FLAGS_SEPARATE_FRAMES is set.
221 Default is not to clean frames,
222 this is a little faster but may
223 produce flicker if frame rate is
224 too high and Isoc data gets lost.
225 FLAGS_NO_DECODING 128 This flag turns the video stream
226 decoder off, and dumps the raw
227 Isoc data from the camera into
228 the reading process. Useful to
229 developers, but not to users.
230
231framerate This setting controls frame rate of the camera. This is
232 an approximate setting (in terms of "worst" ... "best")
233 because camera changes frame rate depending on amount
234 of light available. Setting 0 is slowest, 6 is fastest.
235 Beware - fast settings are very demanding and may not
236 work well with all video sizes. Be conservative.
237
238hue_correction This highly optional setting allows to adjust the
239 hue of the image in a way slightly different from
240 what usual "hue" control does. Both controls affect
241 YUV colorspace: regular "hue" control adjusts only
242 U component, and this "hue_correction" option similarly
243 adjusts only V component. However usually it is enough
244 to tweak only U or V to compensate for colored light or
245 color temperature; this option simply allows more
246 complicated correction when and if it is necessary.
247
248init_brightness These settings specify _initial_ values which will be
249init_contrast used to set up the camera. If your V4L application has
250init_color its own controls to adjust the picture then these
251init_hue controls will be used too. These options allow you to
252 preconfigure the camera when it gets connected, before
253 any V4L application connects to it. Good for webcams.
254
255init_model2_rg These initial settings alter color balance of the
256init_model2_rg2 camera on hardware level. All four settings may be used
257init_model2_sat to tune the camera to specific lighting conditions. These
258init_model2_yb settings only apply to Model 2 cameras.
259
260lighting This option selects one of three hardware-defined
261 photosensitivity settings of the camera. 0=bright light,
262 1=Medium (default), 2=Low light. This setting affects
263 frame rate: the dimmer the lighting the lower the frame
264 rate (because longer exposition time is needed). The
265 Model 2 cameras allow values more than 2 for this option,
266 thus enabling extremely high sensitivity at cost of frame
267 rate, color saturation and imaging sensor noise.
268
269sharpness This option controls smoothing (noise reduction)
270 made by camera. Setting 0 is most smooth, setting 6
271 is most sharp. Be aware that CMOS sensor used in the
272 camera is pretty noisy, so if you choose 6 you will
273 be greeted with "snowy" image. Default is 4. Model 2
274 cameras do not support this feature.
275
276size This setting chooses one of several image sizes that are
277 supported by this driver. Cameras may support more, but
278 it's difficult to reverse-engineer all formats.
279 Following video sizes are supported:
280
281 size=0 128x96 (Model 1 only)
282 size=1 160x120
283 size=2 176x144
284 size=3 320x240 (Model 2 only)
285 size=4 352x240 (Model 2 only)
286 size=5 352x288
287 size=6 640x480 (Model 3 only)
288
289 The 352x288 is the native size of the Model 1 sensor
290 array, so it's the best resolution the camera can
291 yield. The best resolution of Model 2 is 176x144, and
292 larger images are produced by stretching the bitmap.
293 Model 3 has sensor with 640x480 grid, and it works too,
294 but the frame rate will be exceptionally low (1-2 FPS);
295 it may be still OK for some applications, like security.
296 Choose the image size you need. The smaller image can
297 support faster frame rate. Default is 352x288.
298
299For more information and the Troubleshooting FAQ visit this URL:
300
301 http://www.linux-usb.org/ibmcam/
302
303WHAT NEEDS TO BE DONE:
304
305- The button on the camera is not used. I don't know how to get to it.
306 I know now how to read button on Model 2, but what to do with it?
307
308- Camera reports its status back to the driver; however I don't know
309 what returned data means. If camera fails at some initialization
310 stage then something should be done, and I don't do that because
311 I don't even know that some command failed. This is mostly Model 1
312 concern because Model 2 uses different commands which do not return
313 status (and seem to complete successfully every time).
314
315- Some flavors of Model 4 NetCameras produce only compressed video
316 streams, and I don't know how to decode them.
317
318CREDITS:
319
320The code is based in no small part on the CPiA driver by Johannes Erdfelt,
321Randy Dunlap, and others. Big thanks to them for their pioneering work on that
322and the USB stack.
323
324I 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 000000000000..142741e3c578
--- /dev/null
+++ b/Documentation/video4linux/ov511.txt
@@ -0,0 +1,288 @@
1-------------------------------------------------------------------------------
2Readme for Linux device driver for the OmniVision OV511 USB to camera bridge IC
3-------------------------------------------------------------------------------
4
5Author: Mark McClelland
6Homepage: http://alpha.dyndns.org/ov511
7
8INTRODUCTION:
9
10This is a driver for the OV511, a USB-only chip used in many "webcam" devices.
11Any camera using the OV511/OV511+ and the OV6620/OV7610/20/20AE should work.
12Video capture devices that use the Philips SAA7111A decoder also work. It
13supports streaming and capture of color or monochrome video via the Video4Linux
14API. Most V4L apps are compatible with it. Most resolutions with a width and
15height that are a multiple of 8 are supported.
16
17If you need more information, please visit the OV511 homepage at the above URL.
18
19WHAT YOU NEED:
20
21- If you want to help with the development, get the chip's specification docs at
22 http://www.ovt.com/omniusbp.html
23
24- A Video4Linux compatible frame grabber program (I recommend vidcat and xawtv)
25 vidcat is part of the w3cam package: http://mpx.freeshell.net/
26 xawtv is available at: http://linux.bytesex.org/xawtv/
27
28HOW TO USE IT:
29
30Note: These are simplified instructions. For complete instructions see:
31 http://alpha.dyndns.org/ov511/install.html
32
33You must have first compiled USB support, support for your specific USB host
34controller (UHCI or OHCI), and Video4Linux support for your kernel (I recommend
35making them modules.) Make sure "Enforce bandwidth allocation" is NOT enabled.
36
37Next, (as root):
38
39 modprobe usbcore
40 modprobe usb-uhci <OR> modprobe usb-ohci
41 modprobe videodev
42 modprobe ov511
43
44If it is not already there (it usually is), create the video device:
45
46 mknod /dev/video0 c 81 0
47
48Optionally, symlink /dev/video to /dev/video0
49
50You will have to set permissions on this device to allow you to read/write
51from it:
52
53 chmod 666 /dev/video
54 chmod 666 /dev/video0 (if necessary)
55
56Now you are ready to run a video app! Both vidcat and xawtv work well for me
57at 640x480.
58
59[Using vidcat:]
60
61 vidcat -s 640x480 -p c > test.jpg
62 xview test.jpg
63
64[Using xawtv:]
65
66From the main xawtv directory:
67
68 make clean
69 ./configure
70 make
71 make install
72
73Now you should be able to run xawtv. Right click for the options dialog.
74
75MODULE PARAMETERS:
76
77 You can set these with: insmod ov511 NAME=VALUE
78 There is currently no way to set these on a per-camera basis.
79
80 NAME: autobright
81 TYPE: integer (Boolean)
82 DEFAULT: 1
83 DESC: Brightness is normally under automatic control and can't be set
84 manually by the video app. Set to 0 for manual control.
85
86 NAME: autogain
87 TYPE: integer (Boolean)
88 DEFAULT: 1
89 DESC: Auto Gain Control enable. This feature is not yet implemented.
90
91 NAME: autoexp
92 TYPE: integer (Boolean)
93 DEFAULT: 1
94 DESC: Auto Exposure Control enable. This feature is not yet implemented.
95
96 NAME: debug
97 TYPE: integer (0-6)
98 DEFAULT: 3
99 DESC: Sets the threshold for printing debug messages. The higher the value,
100 the more is printed. The levels are cumulative, and are as follows:
101 0=no debug messages
102 1=init/detection/unload and other significant messages
103 2=some warning messages
104 3=config/control function calls
105 4=most function calls and data parsing messages
106 5=highly repetitive mesgs
107
108 NAME: snapshot
109 TYPE: integer (Boolean)
110 DEFAULT: 0
111 DESC: Set to 1 to enable snapshot mode. read()/VIDIOCSYNC will block until
112 the snapshot button is pressed. Note: enabling this mode disables
113 /proc/video/ov511/<minor#>/button
114
115 NAME: cams
116 TYPE: integer (1-4 for OV511, 1-31 for OV511+)
117 DEFAULT: 1
118 DESC: Number of cameras allowed to stream simultaneously on a single bus.
119 Values higher than 1 reduce the data rate of each camera, allowing two
120 or more to be used at once. If you have a complicated setup involving
121 both OV511 and OV511+ cameras, trial-and-error may be necessary for
122 finding the optimum setting.
123
124 NAME: compress
125 TYPE: integer (Boolean)
126 DEFAULT: 0
127 DESC: Set this to 1 to turn on the camera's compression engine. This can
128 potentially increase the frame rate at the expense of quality, if you
129 have a fast CPU. You must load the proper compression module for your
130 camera before starting your application (ov511_decomp or ov518_decomp).
131
132 NAME: testpat
133 TYPE: integer (Boolean)
134 DEFAULT: 0
135 DESC: This configures the camera's sensor to transmit a colored test-pattern
136 instead of an image. This does not work correctly yet.
137
138 NAME: dumppix
139 TYPE: integer (0-2)
140 DEFAULT: 0
141 DESC: Dumps raw pixel data and skips post-processing and format conversion.
142 It is for debugging purposes only. Options are:
143 0: Disable (default)
144 1: Dump raw data from camera, excluding headers and trailers
145 2: Dumps data exactly as received from camera
146
147 NAME: led
148 TYPE: integer (0-2)
149 DEFAULT: 1 (Always on)
150 DESC: Controls whether the LED (the little light) on the front of the camera
151 is always off (0), always on (1), or only on when driver is open (2).
152 This is not supported with the OV511, and might only work with certain
153 cameras (ones that actually have the LED wired to the control pin, and
154 not just hard-wired to be on all the time).
155
156 NAME: dump_bridge
157 TYPE: integer (Boolean)
158 DEFAULT: 0
159 DESC: Dumps the bridge (OV511[+] or OV518[+]) register values to the system
160 log. Only useful for serious debugging/development purposes.
161
162 NAME: dump_sensor
163 TYPE: integer (Boolean)
164 DEFAULT: 0
165 DESC: Dumps the sensor register values to the system log. Only useful for
166 serious debugging/development purposes.
167
168 NAME: printph
169 TYPE: integer (Boolean)
170 DEFAULT: 0
171 DESC: Setting this to 1 will dump the first 12 bytes of each isoc frame. This
172 is only useful if you are trying to debug problems with the isoc data
173 stream (i.e.: camera initializes, but vidcat hangs until Ctrl-C). Be
174 warned that this dumps a large number of messages to your kernel log.
175
176 NAME: phy, phuv, pvy, pvuv, qhy, qhuv, qvy, qvuv
177 TYPE: integer (0-63 for phy and phuv, 0-255 for rest)
178 DEFAULT: OV511 default values
179 DESC: These are registers 70h - 77h of the OV511, which control the
180 prediction ranges and quantization thresholds of the compressor, for
181 the Y and UV channels in the horizontal and vertical directions. See
182 the OV511 or OV511+ data sheet for more detailed descriptions. These
183 normally do not need to be changed.
184
185 NAME: lightfreq
186 TYPE: integer (0, 50, or 60)
187 DEFAULT: 0 (use sensor default)
188 DESC: Sets the sensor to match your lighting frequency. This can reduce the
189 appearance of "banding", i.e. horizontal lines or waves of light and
190 dark that are often caused by artificial lighting. Valid values are:
191 0 - Use default (depends on sensor, most likely 60 Hz)
192 50 - For European and Asian 50 Hz power
193 60 - For American 60 Hz power
194
195 NAME: bandingfilter
196 TYPE: integer (Boolean)
197 DEFAULT: 0 (off)
198 DESC: Enables the sensor´s banding filter exposure algorithm. This reduces
199 or stabilizes the "banding" caused by some artificial light sources
200 (especially fluorescent). You might have to set lightfreq correctly for
201 this to work right. As an added bonus, this sometimes makes it
202 possible to capture your monitor´s output.
203
204 NAME: fastset
205 TYPE: integer (Boolean)
206 DEFAULT: 0 (off)
207 DESC: Allows picture settings (brightness, contrast, color, and hue) to take
208 effect immediately, even in the middle of a frame. This reduces the
209 time to change settings, but can ruin frames during the change. Only
210 affects OmniVision sensors.
211
212 NAME: force_palette
213 TYPE: integer (Boolean)
214 DEFAULT: 0 (off)
215 DESC: Forces the palette (color format) to a specific value. If an
216 application requests a different palette, it will be rejected, thereby
217 forcing it to try others until it succeeds. This is useful for forcing
218 greyscale mode with a color camera, for example. Supported modes are:
219 0 (Allows all the following formats)
220 1 VIDEO_PALETTE_GREY (Linear greyscale)
221 10 VIDEO_PALETTE_YUV420 (YUV 4:2:0 Planar)
222 15 VIDEO_PALETTE_YUV420P (YUV 4:2:0 Planar, same as 10)
223
224 NAME: backlight
225 TYPE: integer (Boolean)
226 DEFAULT: 0 (off)
227 DESC: Setting this flag changes the exposure algorithm for OmniVision sensors
228 such that objects in the camera's view (i.e. your head) can be clearly
229 seen when they are illuminated from behind. It reduces or eliminates
230 the sensor's auto-exposure function, so it should only be used when
231 needed. Additionally, it is only supported with the OV6620 and OV7620.
232
233 NAME: unit_video
234 TYPE: Up to 16 comma-separated integers
235 DEFAULT: 0,0,0... (automatically assign the next available minor(s))
236 DESC: You can specify up to 16 minor numbers to be assigned to ov511 devices.
237 For example, "unit_video=1,3" will make the driver use /dev/video1 and
238 /dev/video3 for the first two devices it detects. Additional devices
239 will be assigned automatically starting at the first available device
240 node (/dev/video0 in this case). Note that you cannot specify 0 as a
241 minor number. This feature requires kernel version 2.4.5 or higher.
242
243 NAME: remove_zeros
244 TYPE: integer (Boolean)
245 DEFAULT: 0 (do not skip any incoming data)
246 DESC: Setting this to 1 will remove zero-padding from incoming data. This
247 will compensate for the blocks of corruption that can appear when the
248 camera cannot keep up with the speed of the USB bus (eg. at low frame
249 resolutions). This feature is always enabled when compression is on.
250
251 NAME: mirror
252 TYPE: integer (Boolean)
253 DEFAULT: 0 (off)
254 DESC: Setting this to 1 will reverse ("mirror") the image horizontally. This
255 might be necessary if your camera has a custom lens assembly. This has
256 no effect with video capture devices.
257
258 NAME: ov518_color
259 TYPE: integer (Boolean)
260 DEFAULT: 0 (off)
261 DESC: Enable OV518 color support. This is off by default since it doesn't
262 work most of the time. If you want to try it, you must also load
263 ov518_decomp with the "nouv=0" parameter. If you get improper colors or
264 diagonal lines through the image, restart your video app and try again.
265 Repeat as necessary.
266
267WORKING FEATURES:
268 o Color streaming/capture at most widths and heights that are multiples of 8.
269 o Monochrome (use force_palette=1 to enable)
270 o Setting/getting of saturation, contrast, brightness, and hue (only some of
271 them work the OV7620 and OV7620AE)
272 o /proc status reporting
273 o SAA7111A video capture support at 320x240 and 640x480
274 o Compression support
275 o SMP compatibility
276
277HOW TO CONTACT ME:
278
279You can email me at mark@alpha.dyndns.org . Please prefix the subject line
280with "OV511: " so that I am certain to notice your message.
281
282CREDITS:
283
284The code is based in no small part on the CPiA driver by Johannes Erdfelt,
285Randy Dunlap, and others. Big thanks to them for their pioneering work on that
286and the USB stack. Thanks to Bret Wallach for getting camera reg IO, ISOC, and
287image capture working. Thanks to Orion Sky Lawlor, Kevin Moore, and Claudio
288Matsuoka for their work as well.
diff --git a/Documentation/video4linux/se401.txt b/Documentation/video4linux/se401.txt
new file mode 100644
index 000000000000..7b9d1c960a10
--- /dev/null
+++ b/Documentation/video4linux/se401.txt
@@ -0,0 +1,54 @@
1Linux driver for SE401 based USB cameras
2
3Copyright, 2001, Jeroen Vreeken
4
5
6INTRODUCTION:
7
8The SE401 chip is the used in low-cost usb webcams.
9It is produced by Endpoints Inc. (www.endpoints.com).
10It interfaces directly to a cmos image sensor and USB. The only other major
11part in a se401 based camera is a dram chip.
12
13The following cameras are known to work with this driver:
14
15Aox se401 (non-branded) cameras
16Philips PVCV665 USB VGA webcam 'Vesta Fun'
17Kensington VideoCAM PC Camera Model 67014
18Kensington VideoCAM PC Camera Model 67015
19Kensington VideoCAM PC Camera Model 67016
20Kensington VideoCAM PC Camera Model 67017
21
22
23WHAT YOU NEED:
24
25- USB support
26- VIDEO4LINUX support
27
28More information about USB support for linux can be found at:
29http://www.linux-usb.org
30
31
32MODULE OPTIONS:
33
34When the driver is compiled as a module you can also use the 'flickerless'
35option. With it exposure is limited to values that do not interfere with the
36net frequency. Valid options for this option are 0, 50 and 60. (0=disable,
3750=50hz, 60=60hz)
38
39
40KNOWN PROBLEMS:
41
42The driver works fine with the usb-ohci and uhci host controller drivers,
43the default settings also work with usb-uhci. But sending more than one bulk
44transfer at a time with usb-uhci doesn't work yet.
45Users of usb-ohci and uhci can safely enlarge SE401_NUMSBUF in se401.h in
46order to increase the throughput (and thus framerate).
47
48
49HELP:
50
51The latest info on this driver can be found at:
52http://www.chello.nl/~j.vreeken/se401/
53And questions to me can be send to:
54pe1rxq@amsat.org
diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt
new file mode 100644
index 000000000000..142920bc011f
--- /dev/null
+++ b/Documentation/video4linux/sn9c102.txt
@@ -0,0 +1,518 @@
1
2 SN9C10x PC Camera Controllers
3 Driver for Linux
4 =============================
5
6 - Documentation -
7
8
9Index
10=====
111. Copyright
122. Disclaimer
133. License
144. Overview and features
155. Module dependencies
166. Module loading
177. Module parameters
188. Optional device control through "sysfs"
199. Supported devices
2010. Notes for V4L2 application developers
2111. Video frame formats
2212. Contact information
2313. Credits
24
25
261. Copyright
27============
28Copyright (C) 2004-2006 by Luca Risolia <luca.risolia@studio.unibo.it>
29
30
312. Disclaimer
32=============
33SONiX is a trademark of SONiX Technology Company Limited, inc.
34This software is not sponsored or developed by SONiX.
35
36
373. License
38==========
39This program is free software; you can redistribute it and/or modify
40it under the terms of the GNU General Public License as published by
41the Free Software Foundation; either version 2 of the License, or
42(at your option) any later version.
43
44This program is distributed in the hope that it will be useful,
45but WITHOUT ANY WARRANTY; without even the implied warranty of
46MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
47GNU General Public License for more details.
48
49You should have received a copy of the GNU General Public License
50along with this program; if not, write to the Free Software
51Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
52
53
544. Overview and features
55========================
56This driver attempts to support the video interface of the devices mounting the
57SONiX SN9C101, SN9C102 and SN9C103 PC Camera Controllers.
58
59It's worth to note that SONiX has never collaborated with the author during the
60development of this project, despite several requests for enough detailed
61specifications of the register tables, compression engine and video data format
62of the above chips. Nevertheless, these informations are no longer necessary,
63becouse all the aspects related to these chips are known and have been
64described in detail in this documentation.
65
66The driver relies on the Video4Linux2 and USB core modules. It has been
67designed to run properly on SMP systems as well.
68
69The latest version of the SN9C10x driver can be found at the following URL:
70http://www.linux-projects.org/
71
72Some of the features of the driver are:
73
74- full compliance with the Video4Linux2 API (see also "Notes for V4L2
75 application developers" paragraph);
76- available mmap or read/poll methods for video streaming through isochronous
77 data transfers;
78- automatic detection of image sensor;
79- support for built-in microphone interface;
80- support for any window resolutions and optional panning within the maximum
81 pixel area of image sensor;
82- image downscaling with arbitrary scaling factors from 1, 2 and 4 in both
83 directions (see "Notes for V4L2 application developers" paragraph);
84- two different video formats for uncompressed or compressed data in low or
85 high compression quality (see also "Notes for V4L2 application developers"
86 and "Video frame formats" paragraphs);
87- full support for the capabilities of many of the possible image sensors that
88 can be connected to the SN9C10x bridges, including, for istance, red, green,
89 blue and global gain adjustments and exposure (see "Supported devices"
90 paragraph for details);
91- use of default color settings for sunlight conditions;
92- dynamic I/O interface for both SN9C10x and image sensor control and
93 monitoring (see "Optional device control through 'sysfs'" paragraph);
94- dynamic driver control thanks to various module parameters (see "Module
95 parameters" paragraph);
96- up to 64 cameras can be handled at the same time; they can be connected and
97 disconnected from the host many times without turning off the computer, if
98 the system supports hotplugging;
99- no known bugs.
100
101
1025. Module dependencies
103======================
104For it to work properly, the driver needs kernel support for Video4Linux and
105USB.
106
107The following options of the kernel configuration file must be enabled and
108corresponding modules must be compiled:
109
110 # Multimedia devices
111 #
112 CONFIG_VIDEO_DEV=m
113
114To enable advanced debugging functionality on the device through /sysfs:
115
116 # Multimedia devices
117 #
118 CONFIG_VIDEO_ADV_DEBUG=y
119
120 # USB support
121 #
122 CONFIG_USB=m
123
124In addition, depending on the hardware being used, the modules below are
125necessary:
126
127 # USB Host Controller Drivers
128 #
129 CONFIG_USB_EHCI_HCD=m
130 CONFIG_USB_UHCI_HCD=m
131 CONFIG_USB_OHCI_HCD=m
132
133The SN9C103 controller also provides a built-in microphone interface. It is
134supported by the USB Audio driver thanks to the ALSA API:
135
136 # Sound
137 #
138 CONFIG_SOUND=y
139
140 # Advanced Linux Sound Architecture
141 #
142 CONFIG_SND=m
143
144 # USB devices
145 #
146 CONFIG_SND_USB_AUDIO=m
147
148And finally:
149
150 # USB Multimedia devices
151 #
152 CONFIG_USB_SN9C102=m
153
154
1556. Module loading
156=================
157To use the driver, it is necessary to load the "sn9c102" module into memory
158after every other module required: "videodev", "usbcore" and, depending on
159the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd".
160
161Loading can be done as shown below:
162
163 [root@localhost home]# modprobe sn9c102
164
165At this point the devices should be recognized. You can invoke "dmesg" to
166analyze kernel messages and verify that the loading process has gone well:
167
168 [user@localhost home]$ dmesg
169
170
1717. Module parameters
172====================
173Module parameters are listed below:
174-------------------------------------------------------------------------------
175Name: video_nr
176Type: short array (min = 0, max = 64)
177Syntax: <-1|n[,...]>
178Description: Specify V4L2 minor mode number:
179 -1 = use next available
180 n = use minor number n
181 You can specify up to 64 cameras this way.
182 For example:
183 video_nr=-1,2,-1 would assign minor number 2 to the second
184 recognized camera and use auto for the first one and for every
185 other camera.
186Default: -1
187-------------------------------------------------------------------------------
188Name: force_munmap
189Type: bool array (min = 0, max = 64)
190Syntax: <0|1[,...]>
191Description: Force the application to unmap previously mapped buffer memory
192 before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not
193 all the applications support this feature. This parameter is
194 specific for each detected camera.
195 0 = do not force memory unmapping
196 1 = force memory unmapping (save memory)
197Default: 0
198-------------------------------------------------------------------------------
199Name: frame_timeout
200Type: uint array (min = 0, max = 64)
201Syntax: <n[,...]>
202Description: Timeout for a video frame in seconds. This parameter is
203 specific for each detected camera. This parameter can be
204 changed at runtime thanks to the /sys filesystem interface.
205Default: 2
206-------------------------------------------------------------------------------
207Name: debug
208Type: ushort
209Syntax: <n>
210Description: Debugging information level, from 0 to 3:
211 0 = none (use carefully)
212 1 = critical errors
213 2 = significant informations
214 3 = more verbose messages
215 Level 3 is useful for testing only, when only one device
216 is used. It also shows some more informations about the
217 hardware being detected. This parameter can be changed at
218 runtime thanks to the /sys filesystem interface.
219Default: 2
220-------------------------------------------------------------------------------
221
222
2238. Optional device control through "sysfs" [1]
224==========================================
225If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
226it is possible to read and write both the SN9C10x and the image sensor
227registers by using the "sysfs" filesystem interface.
228
229Every time a supported device is recognized, a write-only file named "green" is
230created in the /sys/class/video4linux/videoX directory. You can set the green
231channel's gain by writing the desired value to it. The value may range from 0
232to 15 for SN9C101 or SN9C102 bridges, from 0 to 127 for SN9C103 bridges.
233Similarly, only for SN9C103 controllers, blue and red gain control files are
234available in the same directory, for which accepted values may range from 0 to
235127.
236
237There are other four entries in the directory above for each registered camera:
238"reg", "val", "i2c_reg" and "i2c_val". The first two files control the
239SN9C10x bridge, while the other two control the sensor chip. "reg" and
240"i2c_reg" hold the values of the current register index where the following
241reading/writing operations are addressed at through "val" and "i2c_val". Their
242use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not
243be created if the sensor does not actually support the standard I2C protocol or
244its registers are not 8-bit long. Also, remember that you must be logged in as
245root before writing to them.
246
247As an example, suppose we were to want to read the value contained in the
248register number 1 of the sensor register table - which is usually the product
249identifier - of the camera registered as "/dev/video0":
250
251 [root@localhost #] cd /sys/class/video4linux/video0
252 [root@localhost #] echo 1 > i2c_reg
253 [root@localhost #] cat i2c_val
254
255Note that "cat" will fail if sensor registers cannot be read.
256
257Now let's set the green gain's register of the SN9C101 or SN9C102 chips to 2:
258
259 [root@localhost #] echo 0x11 > reg
260 [root@localhost #] echo 2 > val
261
262Note that the SN9C10x always returns 0 when some of its registers are read.
263To avoid race conditions, all the I/O accesses to the above files are
264serialized.
265
266The sysfs interface also provides the "frame_header" entry, which exports the
267frame header of the most recent requested and captured video frame. The header
268is always 18-bytes long and is appended to every video frame by the SN9C10x
269controllers. As an example, this additional information can be used by the user
270application for implementing auto-exposure features via software.
271
272The following table describes the frame header:
273
274Byte # Value Description
275------ ----- -----------
2760x00 0xFF Frame synchronisation pattern.
2770x01 0xFF Frame synchronisation pattern.
2780x02 0x00 Frame synchronisation pattern.
2790x03 0xC4 Frame synchronisation pattern.
2800x04 0xC4 Frame synchronisation pattern.
2810x05 0x96 Frame synchronisation pattern.
2820x06 0xXX Unknown meaning. The exact value depends on the chip;
283 possible values are 0x00, 0x01 and 0x20.
2840x07 0xXX Variable value, whose bits are ff00uzzc, where ff is a
285 frame counter, u is unknown, zz is a size indicator
286 (00 = VGA, 01 = SIF, 10 = QSIF) and c stands for
287 "compression enabled" (1 = yes, 0 = no).
2880x08 0xXX Brightness sum inside Auto-Exposure area (low-byte).
2890x09 0xXX Brightness sum inside Auto-Exposure area (high-byte).
290 For a pure white image, this number will be equal to 500
291 times the area of the specified AE area. For images
292 that are not pure white, the value scales down according
293 to relative whiteness.
2940x0A 0xXX Brightness sum outside Auto-Exposure area (low-byte).
2950x0B 0xXX Brightness sum outside Auto-Exposure area (high-byte).
296 For a pure white image, this number will be equal to 125
297 times the area outside of the specified AE area. For
298 images that are not pure white, the value scales down
299 according to relative whiteness.
300 according to relative whiteness.
301
302The following bytes are used by the SN9C103 bridge only:
303
3040x0C 0xXX Unknown meaning
3050x0D 0xXX Unknown meaning
3060x0E 0xXX Unknown meaning
3070x0F 0xXX Unknown meaning
3080x10 0xXX Unknown meaning
3090x11 0xXX Unknown meaning
310
311The AE area (sx, sy, ex, ey) in the active window can be set by programming the
312registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C10x controllers, where one unit
313corresponds to 32 pixels.
314
315[1] Part of the meaning of the frame header has been documented by Bertrik
316 Sikken.
317
318
3199. Supported devices
320====================
321None of the names of the companies as well as their products will be mentioned
322here. They have never collaborated with the author, so no advertising.
323
324From the point of view of a driver, what unambiguously identify a device are
325its vendor and product USB identifiers. Below is a list of known identifiers of
326devices mounting the SN9C10x PC camera controllers:
327
328Vendor ID Product ID
329--------- ----------
3300x0c45 0x6001
3310x0c45 0x6005
3320x0c45 0x6007
3330x0c45 0x6009
3340x0c45 0x600d
3350x0c45 0x6024
3360x0c45 0x6025
3370x0c45 0x6028
3380x0c45 0x6029
3390x0c45 0x602a
3400x0c45 0x602b
3410x0c45 0x602c
3420x0c45 0x602d
3430x0c45 0x602e
3440x0c45 0x6030
3450x0c45 0x6080
3460x0c45 0x6082
3470x0c45 0x6083
3480x0c45 0x6088
3490x0c45 0x608a
3500x0c45 0x608b
3510x0c45 0x608c
3520x0c45 0x608e
3530x0c45 0x608f
3540x0c45 0x60a0
3550x0c45 0x60a2
3560x0c45 0x60a3
3570x0c45 0x60a8
3580x0c45 0x60aa
3590x0c45 0x60ab
3600x0c45 0x60ac
3610x0c45 0x60ae
3620x0c45 0x60af
3630x0c45 0x60b0
3640x0c45 0x60b2
3650x0c45 0x60b3
3660x0c45 0x60b8
3670x0c45 0x60ba
3680x0c45 0x60bb
3690x0c45 0x60bc
3700x0c45 0x60be
371
372The list above does not imply that all those devices work with this driver: up
373until now only the ones that mount the following image sensors are supported;
374kernel messages will always tell you whether this is the case:
375
376Model Manufacturer
377----- ------------
378HV7131D Hynix Semiconductor, Inc.
379MI-0343 Micron Technology, Inc.
380OV7630 OmniVision Technologies, Inc.
381PAS106B PixArt Imaging, Inc.
382PAS202BCA PixArt Imaging, Inc.
383PAS202BCB PixArt Imaging, Inc.
384TAS5110C1B Taiwan Advanced Sensor Corporation
385TAS5130D1B Taiwan Advanced Sensor Corporation
386
387All the available control settings of each image sensor are supported through
388the V4L2 interface.
389
390Donations of new models for further testing and support would be much
391appreciated. Non-available hardware will not be supported by the author of this
392driver.
393
394
39510. Notes for V4L2 application developers
396=========================================
397This driver follows the V4L2 API specifications. In particular, it enforces two
398rules:
399
400- exactly one I/O method, either "mmap" or "read", is associated with each
401file descriptor. Once it is selected, the application must close and reopen the
402device to switch to the other I/O method;
403
404- although it is not mandatory, previously mapped buffer memory should always
405be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
406The same number of buffers as before will be allocated again to match the size
407of the new video frames, so you have to map the buffers again before any I/O
408attempts on them.
409
410Consistently with the hardware limits, this driver also supports image
411downscaling with arbitrary scaling factors from 1, 2 and 4 in both directions.
412However, the V4L2 API specifications don't correctly define how the scaling
413factor can be chosen arbitrarily by the "negotiation" of the "source" and
414"target" rectangles. To work around this flaw, we have added the convention
415that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the
416scaling factor is restored to 1.
417
418This driver supports two different video formats: the first one is the "8-bit
419Sequential Bayer" format and can be used to obtain uncompressed video data
420from the device through the current I/O method, while the second one provides
421"raw" compressed video data (without frame headers not related to the
422compressed data). The compression quality may vary from 0 to 1 and can be
423selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP V4L2
424ioctl's. For maximum flexibility, both the default active video format and the
425default compression quality depend on how the image sensor being used is
426initialized (as described in the documentation of the API for the image sensors
427supplied by this driver).
428
429
43011. Video frame formats [1]
431=======================
432The SN9C10x PC Camera Controllers can send images in two possible video
433formats over the USB: either native "Sequential RGB Bayer" or Huffman
434compressed. The latter is used to achieve high frame rates. The current video
435format may be selected or queried from the user application by calling the
436VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API
437specifications.
438
439The name "Sequential Bayer" indicates the organization of the red, green and
440blue pixels in one video frame. Each pixel is associated with a 8-bit long
441value and is disposed in memory according to the pattern shown below:
442
443B[0] G[1] B[2] G[3] ... B[m-2] G[m-1]
444G[m] R[m+1] G[m+2] R[m+2] ... G[2m-2] R[2m-1]
445...
446... B[(n-1)(m-2)] G[(n-1)(m-1)]
447... G[n(m-2)] R[n(m-1)]
448
449The above matrix also represents the sequential or progressive read-out mode of
450the (n, m) Bayer color filter array used in many CCD/CMOS image sensors.
451
452One compressed video frame consists of a bitstream that encodes for every R, G,
453or B pixel the difference between the value of the pixel itself and some
454reference pixel value. Pixels are organised in the Bayer pattern and the Bayer
455sub-pixels are tracked individually and alternatingly. For example, in the
456first line values for the B and G1 pixels are alternatingly encoded, while in
457the second line values for the G2 and R pixels are alternatingly encoded.
458
459The pixel reference value is calculated as follows:
460- the 4 top left pixels are encoded in raw uncompressed 8-bit format;
461- the value in the top two rows is the value of the pixel left of the current
462 pixel;
463- the value in the left column is the value of the pixel above the current
464 pixel;
465- for all other pixels, the reference value is the average of the value of the
466 pixel on the left and the value of the pixel above the current pixel;
467- there is one code in the bitstream that specifies the value of a pixel
468 directly (in 4-bit resolution);
469- pixel values need to be clamped inside the range [0..255] for proper
470 decoding.
471
472The algorithm purely describes the conversion from compressed Bayer code used
473in the SN9C10x chips to uncompressed Bayer. Additional steps are required to
474convert this to a color image (i.e. a color interpolation algorithm).
475
476The following Huffman codes have been found:
4770: +0 (relative to reference pixel value)
478100: +4
479101: -4?
4801110xxxx: set absolute value to xxxx.0000
4811101: +11
4821111: -11
48311001: +20
484110000: -20
485110001: ??? - these codes are apparently not used
486
487[1] The Huffman compression algorithm has been reverse-engineered and
488 documented by Bertrik Sikken.
489
490
49112. Contact information
492=======================
493The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
494
495GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is
496'FCE635A4'; the public 1024-bit key should be available at any keyserver;
497the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
498
499
50013. Credits
501===========
502Many thanks to following persons for their contribute (listed in alphabetical
503order):
504
505- Luca Capello for the donation of a webcam;
506- Philippe Coval for having helped testing the PAS202BCA image sensor;
507- Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the
508 donation of a webcam;
509- Jon Hollstrom for the donation of a webcam;
510- Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB
511 image sensor;
512- Stefano Mozzi, who donated 45 EU;
513- Andrew Pearce for the donation of a webcam;
514- Bertrik Sikken, who reverse-engineered and documented the Huffman compression
515 algorithm used in the SN9C10x controllers and implemented the first decoder;
516- Mizuno Takafumi for the donation of a webcam;
517- an "anonymous" donator (who didn't want his name to be revealed) for the
518 donation of a webcam.
diff --git a/Documentation/video4linux/stv680.txt b/Documentation/video4linux/stv680.txt
new file mode 100644
index 000000000000..4f8946f32f51
--- /dev/null
+++ b/Documentation/video4linux/stv680.txt
@@ -0,0 +1,53 @@
1Linux driver for STV0680 based USB cameras
2
3Copyright, 2001, Kevin Sisson
4
5
6INTRODUCTION:
7
8STMicroelectronics produces the STV0680B chip, which comes in two
9types, -001 and -003. The -003 version allows the recording and downloading
10of sound clips from the camera, and allows a flash attachment. Otherwise,
11it uses the same commands as the -001 version. Both versions support a
12variety of SDRAM sizes and sensors, allowing for a maximum of 26 VGA or 20
13CIF pictures. The STV0680 supports either a serial or a usb interface, and
14video is possible through the usb interface.
15
16The following cameras are known to work with this driver, although any
17camera with Vendor/Product codes of 0553/0202 should work:
18
19Aiptek Pencam (various models)
20Nisis QuickPix 2
21Radio Shack 'Kid's digital camera' (#60-1207)
22At least one Trust Spycam model
23Several other European brand models
24
25WHAT YOU NEED:
26
27- USB support
28- VIDEO4LINUX support
29
30More information about USB support for linux can be found at:
31http://www.linux-usb.org
32
33
34MODULE OPTIONS:
35
36When the driver is compiled as a module, you can set a "swapRGB=1"
37option, if necessary, for those applications that require it
38(such as xawtv). However, the driver should detect and set this
39automatically, so this option should not normally be used.
40
41
42KNOWN PROBLEMS:
43
44The driver seems to work better with the usb-ohci than the usb-uhci host
45controller driver.
46
47HELP:
48
49The latest info on this driver can be found at:
50http://personal.clt.bellsouth.net/~kjsisson or at
51http://stv0680-usb.sourceforge.net
52
53Any 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 000000000000..3b704f2aae6d
--- /dev/null
+++ b/Documentation/video4linux/w9968cf.txt
@@ -0,0 +1,461 @@
1
2 W996[87]CF JPEG USB Dual Mode Camera Chip
3 Driver for Linux 2.6 (basic version)
4 =========================================
5
6 - Documentation -
7
8
9Index
10=====
111. Copyright
122. Disclaimer
133. License
144. Overview
155. Supported devices
166. Module dependencies
177. Module loading
188. Module paramaters
199. Contact information
2010. Credits
21
22
231. Copyright
24============
25Copyright (C) 2002-2004 by Luca Risolia <luca.risolia@studio.unibo.it>
26
27
282. Disclaimer
29=============
30Winbond is a trademark of Winbond Electronics Corporation.
31This software is not sponsored or developed by Winbond.
32
33
343. License
35==========
36This program is free software; you can redistribute it and/or modify
37it under the terms of the GNU General Public License as published by
38the Free Software Foundation; either version 2 of the License, or
39(at your option) any later version.
40
41This program is distributed in the hope that it will be useful,
42but WITHOUT ANY WARRANTY; without even the implied warranty of
43MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
44GNU General Public License for more details.
45
46You should have received a copy of the GNU General Public License
47along with this program; if not, write to the Free Software
48Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
49
50
514. Overview
52===========
53This driver supports the video streaming capabilities of the devices mounting
54Winbond W9967CF and Winbond W9968CF JPEG USB Dual Mode Camera Chips. OV681
55based cameras should be supported as well.
56
57The driver is divided into two modules: the basic one, "w9968cf", is needed for
58the supported devices to work; the second one, "w9968cf-vpp", is an optional
59module, which provides some useful video post-processing functions like video
60decoding, up-scaling and colour conversions.
61
62Note that the official kernels do neither include nor support the second
63module for performance purposes. Therefore, it is always recommended to
64download and install the latest and complete release of the driver,
65replacing the existing one, if present.
66
67The latest and full-featured version of the W996[87]CF driver can be found at:
68http://www.linux-projects.org. Please refer to the documentation included in
69that package, if you are going to use it.
70
71Up to 32 cameras can be handled at the same time. They can be connected and
72disconnected from the host many times without turning off the computer, if
73your system supports the hotplug facility.
74
75To change the default settings for each camera, many parameters can be passed
76through command line when the module is loaded into memory.
77
78The driver relies on the Video4Linux, USB and I2C core modules. It has been
79designed to run properly on SMP systems as well. An additional module,
80"ovcamchip", is mandatory; it provides support for some OmniVision image
81sensors connected to the W996[87]CF chips; if found in the system, the module
82will be automatically loaded by default (provided that the kernel has been
83compiled with the automatic module loading option).
84
85
865. Supported devices
87====================
88At the moment, known W996[87]CF and OV681 based devices are:
89- Aroma Digi Pen VGA Dual Mode ADG-5000 (unknown image sensor)
90- AVerMedia AVerTV USB (SAA7111A, Philips FI1216Mk2 tuner, PT2313L audio chip)
91- Creative Labs Video Blaster WebCam Go (OmniVision OV7610 sensor)
92- Creative Labs Video Blaster WebCam Go Plus (OmniVision OV7620 sensor)
93- Lebon LDC-035A (unknown image sensor)
94- Ezonics EZ-802 EZMega Cam (OmniVision OV8610C sensor)
95- OmniVision OV8610-EDE (OmniVision OV8610 sensor)
96- OPCOM Digi Pen VGA Dual Mode Pen Camera (unknown image sensor)
97- Pretec Digi Pen-II (OmniVision OV7620 sensor)
98- Pretec DigiPen-480 (OmniVision OV8610 sensor)
99
100If you know any other W996[87]CF or OV681 based cameras, please contact me.
101
102The list above does not imply that all those devices work with this driver: up
103until now only webcams that have an image sensor supported by the "ovcamchip"
104module work. Kernel messages will always tell you whether this is case.
105
106Possible external microcontrollers of those webcams are not supported: this
107means that still images cannot be downloaded from the device memory.
108
109Furthermore, it's worth to note that I was only able to run tests on my
110"Creative Labs Video Blaster WebCam Go". Donations of other models, for
111additional testing and full support, would be much appreciated.
112
113
1146. Module dependencies
115======================
116For it to work properly, the driver needs kernel support for Video4Linux, USB
117and I2C, and the "ovcamchip" module for the image sensor. Make sure you are not
118actually using any external "ovcamchip" module, given that the W996[87]CF
119driver depends on the version of the module present in the official kernels.
120
121The following options of the kernel configuration file must be enabled and
122corresponding modules must be compiled:
123
124 # Multimedia devices
125 #
126 CONFIG_VIDEO_DEV=m
127
128 # I2C support
129 #
130 CONFIG_I2C=m
131
132The I2C core module can be compiled statically in the kernel as well.
133
134 # OmniVision Camera Chip support
135 #
136 CONFIG_VIDEO_OVCAMCHIP=m
137
138 # USB support
139 #
140 CONFIG_USB=m
141
142In addition, depending on the hardware being used, only one of the modules
143below is necessary:
144
145 # USB Host Controller Drivers
146 #
147 CONFIG_USB_EHCI_HCD=m
148 CONFIG_USB_UHCI_HCD=m
149 CONFIG_USB_OHCI_HCD=m
150
151And finally:
152
153 # USB Multimedia devices
154 #
155 CONFIG_USB_W9968CF=m
156
157
1587. Module loading
159=================
160To use the driver, it is necessary to load the "w9968cf" module into memory
161after every other module required.
162
163Loading can be done this way, from root:
164
165 [root@localhost home]# modprobe usbcore
166 [root@localhost home]# modprobe i2c-core
167 [root@localhost home]# modprobe videodev
168 [root@localhost home]# modprobe w9968cf
169
170At this point the pertinent devices should be recognized: "dmesg" can be used
171to analyze kernel messages:
172
173 [user@localhost home]$ dmesg
174
175There are a lot of parameters the module can use to change the default
176settings for each device. To list every possible parameter with a brief
177explanation about them and which syntax to use, it is recommended to run the
178"modinfo" command:
179
180 [root@locahost home]# modinfo w9968cf
181
182
1838. Module parameters
184====================
185Module parameters are listed below:
186-------------------------------------------------------------------------------
187Name: ovmod_load
188Type: bool
189Syntax: <0|1>
190Description: Automatic 'ovcamchip' module loading: 0 disabled, 1 enabled.
191 If enabled, 'insmod' searches for the required 'ovcamchip'
192 module in the system, according to its configuration, and
193 loads that module automatically. This action is performed as
194 once soon as the 'w9968cf' module is loaded into memory.
195Default: 1
196Note: The kernel must be compiled with the CONFIG_KMOD option
197 enabled for the 'ovcamchip' module to be loaded and for
198 this parameter to be present.
199-------------------------------------------------------------------------------
200Name: simcams
201Type: int
202Syntax: <n>
203Description: Number of cameras allowed to stream simultaneously.
204 n may vary from 0 to 32.
205Default: 32
206-------------------------------------------------------------------------------
207Name: video_nr
208Type: int array (min = 0, max = 32)
209Syntax: <-1|n[,...]>
210Description: Specify V4L minor mode number.
211 -1 = use next available
212 n = use minor number n
213 You can specify up to 32 cameras this way.
214 For example:
215 video_nr=-1,2,-1 would assign minor number 2 to the second
216 recognized camera and use auto for the first one and for every
217 other camera.
218Default: -1
219-------------------------------------------------------------------------------
220Name: packet_size
221Type: int array (min = 0, max = 32)
222Syntax: <n[,...]>
223Description: Specify the maximum data payload size in bytes for alternate
224 settings, for each device. n is scaled between 63 and 1023.
225Default: 1023
226-------------------------------------------------------------------------------
227Name: max_buffers
228Type: int array (min = 0, max = 32)
229Syntax: <n[,...]>
230Description: For advanced users.
231 Specify the maximum number of video frame buffers to allocate
232 for each device, from 2 to 32.
233Default: 2
234-------------------------------------------------------------------------------
235Name: double_buffer
236Type: bool array (min = 0, max = 32)
237Syntax: <0|1[,...]>
238Description: Hardware double buffering: 0 disabled, 1 enabled.
239 It should be enabled if you want smooth video output: if you
240 obtain out of sync. video, disable it, or try to
241 decrease the 'clockdiv' module parameter value.
242Default: 1 for every device.
243-------------------------------------------------------------------------------
244Name: clamping
245Type: bool array (min = 0, max = 32)
246Syntax: <0|1[,...]>
247Description: Video data clamping: 0 disabled, 1 enabled.
248Default: 0 for every device.
249-------------------------------------------------------------------------------
250Name: filter_type
251Type: int array (min = 0, max = 32)
252Syntax: <0|1|2[,...]>
253Description: Video filter type.
254 0 none, 1 (1-2-1) 3-tap filter, 2 (2-3-6-3-2) 5-tap filter.
255 The filter is used to reduce noise and aliasing artifacts
256 produced by the CCD or CMOS image sensor.
257Default: 0 for every device.
258-------------------------------------------------------------------------------
259Name: largeview
260Type: bool array (min = 0, max = 32)
261Syntax: <0|1[,...]>
262Description: Large view: 0 disabled, 1 enabled.
263Default: 1 for every device.
264-------------------------------------------------------------------------------
265Name: upscaling
266Type: bool array (min = 0, max = 32)
267Syntax: <0|1[,...]>
268Description: Software scaling (for non-compressed video only):
269 0 disabled, 1 enabled.
270 Disable it if you have a slow CPU or you don't have enough
271 memory.
272Default: 0 for every device.
273Note: If 'w9968cf-vpp' is not present, this parameter is set to 0.
274-------------------------------------------------------------------------------
275Name: decompression
276Type: int array (min = 0, max = 32)
277Syntax: <0|1|2[,...]>
278Description: Software video decompression:
279 0 = disables decompression
280 (doesn't allow formats needing decompression).
281 1 = forces decompression
282 (allows formats needing decompression only).
283 2 = allows any permitted formats.
284 Formats supporting (de)compressed video are YUV422P and
285 YUV420P/YUV420 in any resolutions where width and height are
286 multiples of 16.
287Default: 2 for every device.
288Note: If 'w9968cf-vpp' is not present, forcing decompression is not
289 allowed; in this case this parameter is set to 2.
290-------------------------------------------------------------------------------
291Name: force_palette
292Type: int array (min = 0, max = 32)
293Syntax: <0|9|10|13|15|8|7|1|6|3|4|5[,...]>
294Description: Force picture palette.
295 In order:
296 0 = Off - allows any of the following formats:
297 9 = UYVY 16 bpp - Original video, compression disabled
298 10 = YUV420 12 bpp - Original video, compression enabled
299 13 = YUV422P 16 bpp - Original video, compression enabled
300 15 = YUV420P 12 bpp - Original video, compression enabled
301 8 = YUVY 16 bpp - Software conversion from UYVY
302 7 = YUV422 16 bpp - Software conversion from UYVY
303 1 = GREY 8 bpp - Software conversion from UYVY
304 6 = RGB555 16 bpp - Software conversion from UYVY
305 3 = RGB565 16 bpp - Software conversion from UYVY
306 4 = RGB24 24 bpp - Software conversion from UYVY
307 5 = RGB32 32 bpp - Software conversion from UYVY
308 When not 0, this parameter will override 'decompression'.
309Default: 0 for every device. Initial palette is 9 (UYVY).
310Note: If 'w9968cf-vpp' is not present, this parameter is set to 9.
311-------------------------------------------------------------------------------
312Name: force_rgb
313Type: bool array (min = 0, max = 32)
314Syntax: <0|1[,...]>
315Description: Read RGB video data instead of BGR:
316 1 = use RGB component ordering.
317 0 = use BGR component ordering.
318 This parameter has effect when using RGBX palettes only.
319Default: 0 for every device.
320-------------------------------------------------------------------------------
321Name: autobright
322Type: bool array (min = 0, max = 32)
323Syntax: <0|1[,...]>
324Description: Image sensor automatically changes brightness:
325 0 = no, 1 = yes
326Default: 0 for every device.
327-------------------------------------------------------------------------------
328Name: autoexp
329Type: bool array (min = 0, max = 32)
330Syntax: <0|1[,...]>
331Description: Image sensor automatically changes exposure:
332 0 = no, 1 = yes
333Default: 1 for every device.
334-------------------------------------------------------------------------------
335Name: lightfreq
336Type: int array (min = 0, max = 32)
337Syntax: <50|60[,...]>
338Description: Light frequency in Hz:
339 50 for European and Asian lighting, 60 for American lighting.
340Default: 50 for every device.
341-------------------------------------------------------------------------------
342Name: bandingfilter
343Type: bool array (min = 0, max = 32)
344Syntax: <0|1[,...]>
345Description: Banding filter to reduce effects of fluorescent
346 lighting:
347 0 disabled, 1 enabled.
348 This filter tries to reduce the pattern of horizontal
349 light/dark bands caused by some (usually fluorescent) lighting.
350Default: 0 for every device.
351-------------------------------------------------------------------------------
352Name: clockdiv
353Type: int array (min = 0, max = 32)
354Syntax: <-1|n[,...]>
355Description: Force pixel clock divisor to a specific value (for experts):
356 n may vary from 0 to 127.
357 -1 for automatic value.
358 See also the 'double_buffer' module parameter.
359Default: -1 for every device.
360-------------------------------------------------------------------------------
361Name: backlight
362Type: bool array (min = 0, max = 32)
363Syntax: <0|1[,...]>
364Description: Objects are lit from behind:
365 0 = no, 1 = yes
366Default: 0 for every device.
367-------------------------------------------------------------------------------
368Name: mirror
369Type: bool array (min = 0, max = 32)
370Syntax: <0|1[,...]>
371Description: Reverse image horizontally:
372 0 = no, 1 = yes
373Default: 0 for every device.
374-------------------------------------------------------------------------------
375Name: monochrome
376Type: bool array (min = 0, max = 32)
377Syntax: <0|1[,...]>
378Description: The image sensor is monochrome:
379 0 = no, 1 = yes
380Default: 0 for every device.
381-------------------------------------------------------------------------------
382Name: brightness
383Type: long array (min = 0, max = 32)
384Syntax: <n[,...]>
385Description: Set picture brightness (0-65535).
386 This parameter has no effect if 'autobright' is enabled.
387Default: 31000 for every device.
388-------------------------------------------------------------------------------
389Name: hue
390Type: long array (min = 0, max = 32)
391Syntax: <n[,...]>
392Description: Set picture hue (0-65535).
393Default: 32768 for every device.
394-------------------------------------------------------------------------------
395Name: colour
396Type: long array (min = 0, max = 32)
397Syntax: <n[,...]>
398Description: Set picture saturation (0-65535).
399Default: 32768 for every device.
400-------------------------------------------------------------------------------
401Name: contrast
402Type: long array (min = 0, max = 32)
403Syntax: <n[,...]>
404Description: Set picture contrast (0-65535).
405Default: 50000 for every device.
406-------------------------------------------------------------------------------
407Name: whiteness
408Type: long array (min = 0, max = 32)
409Syntax: <n[,...]>
410Description: Set picture whiteness (0-65535).
411Default: 32768 for every device.
412-------------------------------------------------------------------------------
413Name: debug
414Type: int
415Syntax: <n>
416Description: Debugging information level, from 0 to 6:
417 0 = none (use carefully)
418 1 = critical errors
419 2 = significant informations
420 3 = configuration or general messages
421 4 = warnings
422 5 = called functions
423 6 = function internals
424 Level 5 and 6 are useful for testing only, when only one
425 device is used.
426Default: 2
427-------------------------------------------------------------------------------
428Name: specific_debug
429Type: bool
430Syntax: <0|1>
431Description: Enable or disable specific debugging messages:
432 0 = print messages concerning every level <= 'debug' level.
433 1 = print messages concerning the level indicated by 'debug'.
434Default: 0
435-------------------------------------------------------------------------------
436
437
4389. Contact information
439======================
440I may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
441
442I can accept GPG/PGP encrypted e-mail. My GPG key ID is 'FCE635A4'.
443My public 1024-bit key should be available at your keyserver; the fingerprint
444is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
445
446
44710. Credits
448==========
449The development would not have proceed much further without having looked at
450the source code of other drivers and without the help of several persons; in
451particular:
452
453- the I2C interface to kernel and high-level image sensor control routines have
454 been taken from the OV511 driver by Mark McClelland;
455
456- memory management code has been copied from the bttv driver by Ralph Metzler,
457 Marcus Metzler and Gerd Knorr;
458
459- the low-level I2C read function has been written by Frederic Jouault;
460
461- 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 000000000000..f55262c6733b
--- /dev/null
+++ b/Documentation/video4linux/zc0301.txt
@@ -0,0 +1,254 @@
1
2 ZC0301 Image Processor and Control Chip
3 Driver for Linux
4 =======================================
5
6 - Documentation -
7
8
9Index
10=====
111. Copyright
122. Disclaimer
133. License
144. Overview and features
155. Module dependencies
166. Module loading
177. Module parameters
188. Supported devices
199. Notes for V4L2 application developers
2010. Contact information
2111. Credits
22
23
241. Copyright
25============
26Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it>
27
28
292. Disclaimer
30=============
31This software is not developed or sponsored by Z-Star Microelectronics Corp.
32Trademarks are property of their respective owner.
33
34
353. License
36==========
37This program is free software; you can redistribute it and/or modify
38it under the terms of the GNU General Public License as published by
39the Free Software Foundation; either version 2 of the License, or
40(at your option) any later version.
41
42This program is distributed in the hope that it will be useful,
43but WITHOUT ANY WARRANTY; without even the implied warranty of
44MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
45GNU General Public License for more details.
46
47You should have received a copy of the GNU General Public License
48along with this program; if not, write to the Free Software
49Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
50
51
524. Overview and features
53========================
54This driver supports the video interface of the devices mounting the ZC0301
55Image Processor and Control Chip.
56
57The driver relies on the Video4Linux2 and USB core modules. It has been
58designed to run properly on SMP systems as well.
59
60The latest version of the ZC0301 driver can be found at the following URL:
61http://www.linux-projects.org/
62
63Some of the features of the driver are:
64
65- full compliance with the Video4Linux2 API (see also "Notes for V4L2
66 application developers" paragraph);
67- available mmap or read/poll methods for video streaming through isochronous
68 data transfers;
69- automatic detection of image sensor;
70- video format is standard JPEG;
71- dynamic driver control thanks to various module parameters (see "Module
72 parameters" paragraph);
73- up to 64 cameras can be handled at the same time; they can be connected and
74 disconnected from the host many times without turning off the computer, if
75 the system supports hotplugging;
76
77
785. Module dependencies
79======================
80For it to work properly, the driver needs kernel support for Video4Linux and
81USB.
82
83The following options of the kernel configuration file must be enabled and
84corresponding modules must be compiled:
85
86 # Multimedia devices
87 #
88 CONFIG_VIDEO_DEV=m
89
90 # USB support
91 #
92 CONFIG_USB=m
93
94In addition, depending on the hardware being used, the modules below are
95necessary:
96
97 # USB Host Controller Drivers
98 #
99 CONFIG_USB_EHCI_HCD=m
100 CONFIG_USB_UHCI_HCD=m
101 CONFIG_USB_OHCI_HCD=m
102
103The ZC0301 controller also provides a built-in microphone interface. It is
104supported by the USB Audio driver thanks to the ALSA API:
105
106 # Sound
107 #
108 CONFIG_SOUND=y
109
110 # Advanced Linux Sound Architecture
111 #
112 CONFIG_SND=m
113
114 # USB devices
115 #
116 CONFIG_SND_USB_AUDIO=m
117
118And finally:
119
120 # USB Multimedia devices
121 #
122 CONFIG_USB_ZC0301=m
123
124
1256. Module loading
126=================
127To use the driver, it is necessary to load the "zc0301" module into memory
128after every other module required: "videodev", "usbcore" and, depending on
129the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd".
130
131Loading can be done as shown below:
132
133 [root@localhost home]# modprobe zc0301
134
135At this point the devices should be recognized. You can invoke "dmesg" to
136analyze kernel messages and verify that the loading process has gone well:
137
138 [user@localhost home]$ dmesg
139
140
1417. Module parameters
142====================
143Module parameters are listed below:
144-------------------------------------------------------------------------------
145Name: video_nr
146Type: short array (min = 0, max = 64)
147Syntax: <-1|n[,...]>
148Description: Specify V4L2 minor mode number:
149 -1 = use next available
150 n = use minor number n
151 You can specify up to 64 cameras this way.
152 For example:
153 video_nr=-1,2,-1 would assign minor number 2 to the second
154 registered camera and use auto for the first one and for every
155 other camera.
156Default: -1
157-------------------------------------------------------------------------------
158Name: force_munmap
159Type: bool array (min = 0, max = 64)
160Syntax: <0|1[,...]>
161Description: Force the application to unmap previously mapped buffer memory
162 before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not
163 all the applications support this feature. This parameter is
164 specific for each detected camera.
165 0 = do not force memory unmapping
166 1 = force memory unmapping (save memory)
167Default: 0
168-------------------------------------------------------------------------------
169Name: frame_timeout
170Type: uint array (min = 0, max = 64)
171Syntax: <n[,...]>
172Description: Timeout for a video frame in seconds. This parameter is
173 specific for each detected camera. This parameter can be
174 changed at runtime thanks to the /sys filesystem interface.
175Default: 2
176-------------------------------------------------------------------------------
177Name: debug
178Type: ushort
179Syntax: <n>
180Description: Debugging information level, from 0 to 3:
181 0 = none (use carefully)
182 1 = critical errors
183 2 = significant informations
184 3 = more verbose messages
185 Level 3 is useful for testing only, when only one device
186 is used at the same time. It also shows some more informations
187 about the hardware being detected. This module parameter can be
188 changed at runtime thanks to the /sys filesystem interface.
189Default: 2
190-------------------------------------------------------------------------------
191
192
1938. Supported devices
194====================
195None of the names of the companies as well as their products will be mentioned
196here. They have never collaborated with the author, so no advertising.
197
198From the point of view of a driver, what unambiguously identify a device are
199its vendor and product USB identifiers. Below is a list of known identifiers of
200devices mounting the ZC0301 Image Processor and Control Chips:
201
202Vendor ID Product ID
203--------- ----------
2040x041e 0x4017
2050x041e 0x401c
2060x041e 0x401e
2070x041e 0x4034
2080x041e 0x4035
2090x046d 0x08ae
2100x0ac8 0x0301
2110x10fd 0x8050
212
213The list above does not imply that all those devices work with this driver: up
214until now only the ones that mount the following image sensors are supported;
215kernel messages will always tell you whether this is the case:
216
217Model Manufacturer
218----- ------------
219PAS202BCB PixArt Imaging, Inc.
220
221
2229. Notes for V4L2 application developers
223========================================
224This driver follows the V4L2 API specifications. In particular, it enforces two
225rules:
226
227- exactly one I/O method, either "mmap" or "read", is associated with each
228file descriptor. Once it is selected, the application must close and reopen the
229device to switch to the other I/O method;
230
231- although it is not mandatory, previously mapped buffer memory should always
232be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
233The same number of buffers as before will be allocated again to match the size
234of the new video frames, so you have to map the buffers again before any I/O
235attempts on them.
236
237
23810. Contact information
239=======================
240The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
241
242GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is
243'FCE635A4'; the public 1024-bit key should be available at any keyserver;
244the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.
245
246
24711. Credits
248===========
249- Informations about the chip internals needed to enable the I2C protocol have
250 been taken from the documentation of the ZC030x Video4Linux1 driver written
251 by Andrew Birkett <andy@nobugs.org>;
252- The initialization values of the ZC0301 controller connected to the PAS202BCB
253 image sensor have been taken from the SPCA5XX driver maintained by
254 Michel Xhaard <mxhaard@magic.fr>.
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-21 13:23:39 -0500