aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/usb/et61x251.txt
diff options
context:
space:
mode:
authorLuca Risolia <luca.risolia@studio.unibo.it>2006-01-10 21:06:59 -0500
committerGreg Kroah-Hartman <gregkh@suse.de>2006-01-31 20:23:39 -0500
commit7ce08c93e388922e25a96a7d9895784182e4c72c (patch)
treea76883260255bd2d287dd9b5358e56cdddd11158 /Documentation/usb/et61x251.txt
parentcd6fcc555fe278263880abdb93352ab205099db9 (diff)
[PATCH] USB: Add ET61X[12]51 Video4Linux2 driver
This patch adds a Video4Linux2 driver giving support to ET61X151 and ET61X251 PC Camera Controllers made by Etoms Electronics. Signed-off-by: Luca Risolia <luca.risolia@studio.unibo.it> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation/usb/et61x251.txt')
-rw-r--r--Documentation/usb/et61x251.txt306
1 files changed, 306 insertions, 0 deletions
diff --git a/Documentation/usb/et61x251.txt b/Documentation/usb/et61x251.txt
new file mode 100644
index 000000000000..b44dda407ce2
--- /dev/null
+++ b/Documentation/usb/et61x251.txt
@@ -0,0 +1,306 @@
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: debug
180Type: ushort
181Syntax: <n>
182Description: Debugging information level, from 0 to 3:
183 0 = none (use carefully)
184 1 = critical errors
185 2 = significant informations
186 3 = more verbose messages
187 Level 3 is useful for testing only, when only one device
188 is used at the same time. It also shows some more informations
189 about the hardware being detected. This module parameter can be
190 changed at runtime thanks to the /sys filesystem interface.
191Default: 2
192-------------------------------------------------------------------------------
193
194
1958. Optional device control through "sysfs"
196==========================================
197If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
198it is possible to read and write both the ET61X[12]51 and the image sensor
199registers by using the "sysfs" filesystem interface.
200
201There are four files in the /sys/class/video4linux/videoX directory for each
202registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files
203control the ET61X[12]51 bridge, while the other two control the sensor chip.
204"reg" and "i2c_reg" hold the values of the current register index where the
205following reading/writing operations are addressed at through "val" and
206"i2c_val". Their use is not intended for end-users, unless you know what you
207are doing. Remember that you must be logged in as root before writing to them.
208
209As an example, suppose we were to want to read the value contained in the
210register number 1 of the sensor register table - which is usually the product
211identifier - of the camera registered as "/dev/video0":
212
213 [root@localhost #] cd /sys/class/video4linux/video0
214 [root@localhost #] echo 1 > i2c_reg
215 [root@localhost #] cat i2c_val
216
217Note that if the sensor registers can not be read, "cat" will fail.
218To avoid race conditions, all the I/O accesses to the files are serialized.
219
220
2219. Supported devices
222====================
223None of the names of the companies as well as their products will be mentioned
224here. They have never collaborated with the author, so no advertising.
225
226From the point of view of a driver, what unambiguously identify a device are
227its vendor and product USB identifiers. Below is a list of known identifiers of
228devices mounting the ET61X[12]51 PC camera controllers:
229
230Vendor ID Product ID
231--------- ----------
2320x102c 0x6151
2330x102c 0x6251
2340x102c 0x6253
2350x102c 0x6254
2360x102c 0x6255
2370x102c 0x6256
2380x102c 0x6257
2390x102c 0x6258
2400x102c 0x6259
2410x102c 0x625a
2420x102c 0x625b
2430x102c 0x625c
2440x102c 0x625d
2450x102c 0x625e
2460x102c 0x625f
2470x102c 0x6260
2480x102c 0x6261
2490x102c 0x6262
2500x102c 0x6263
2510x102c 0x6264
2520x102c 0x6265
2530x102c 0x6266
2540x102c 0x6267
2550x102c 0x6268
2560x102c 0x6269
257
258The following image sensors are supported:
259
260Model Manufacturer
261----- ------------
262TAS5130D1B Taiwan Advanced Sensor Corporation
263
264All the available control settings of each image sensor are supported through
265the V4L2 interface.
266
267
26810. Notes for V4L2 application developers
269========================================
270This driver follows the V4L2 API specifications. In particular, it enforces two
271rules:
272
273- exactly one I/O method, either "mmap" or "read", is associated with each
274file descriptor. Once it is selected, the application must close and reopen the
275device to switch to the other I/O method;
276
277- although it is not mandatory, previously mapped buffer memory should always
278be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
279The same number of buffers as before will be allocated again to match the size
280of the new video frames, so you have to map the buffers again before any I/O
281attempts on them.
282
283Consistently with the hardware limits, this driver also supports image
284downscaling with arbitrary scaling factors from 1 and 2 in both directions.
285However, the V4L2 API specifications don't correctly define how the scaling
286factor can be chosen arbitrarily by the "negotiation" of the "source" and
287"target" rectangles. To work around this flaw, we have added the convention
288that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the
289scaling factor is restored to 1.
290
291This driver supports two different video formats: the first one is the "8-bit
292Sequential Bayer" format and can be used to obtain uncompressed video data
293from the device through the current I/O method, while the second one provides
294"raw" compressed video data (without frame headers not related to the
295compressed data). The current compression quality may vary from 0 to 1 and can
296be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP
297V4L2 ioctl's.
298
299
30011. Contact information
301=======================
302The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
303
304GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is
305'FCE635A4'; the public 1024-bit key should be available at any keyserver;
306the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.