blob: 1247566c4de38211458144eb206432db0a8698d0 [file] [log] [blame]
Luca Risolia7ce08c92006-01-11 02:06:59 +00001
Michael Krufky6e204092006-05-23 17:41:31 -03002 ET61X[12]51 PC Camera Controllers
3 Driver for Linux
4 =================================
Luca Risolia7ce08c92006-01-11 02:06:59 +00005
Michael Krufky6e204092006-05-23 17:41:31 -03006 - Documentation -
Luca Risolia7ce08c92006-01-11 02:06:59 +00007
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============
Luca Risolia26563122007-01-08 11:38:36 -030026Copyright (C) 2006-2007 by Luca Risolia <luca.risolia@studio.unibo.it>
Luca Risolia7ce08c92006-01-11 02:06:59 +000027
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
Matt LaPlante2fe0ae72006-10-03 22:50:39 +020083 be connected to the ET61X[12]51 bridges, including, for instance, red, green,
Luca Risolia7ce08c92006-01-11 02:06:59 +000084 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
Luca Risolia26563122007-01-08 11:38:36 -0300138after every other module required: "videodev", "v4l2_common", "compat_ioctl32",
139"usbcore" and, depending on the USB host controller you have, "ehci-hcd",
140"uhci-hcd" or "ohci-hcd".
Luca Risolia7ce08c92006-01-11 02:06:59 +0000141
142Loading can be done as shown below:
143
144 [root@localhost home]# modprobe et61x251
145
146At this point the devices should be recognized. You can invoke "dmesg" to
147analyze kernel messages and verify that the loading process has gone well:
148
149 [user@localhost home]$ dmesg
150
151
1527. Module parameters
153====================
154Module parameters are listed below:
155-------------------------------------------------------------------------------
156Name: video_nr
157Type: short array (min = 0, max = 64)
158Syntax: <-1|n[,...]>
159Description: Specify V4L2 minor mode number:
Michael Krufky6e204092006-05-23 17:41:31 -0300160 -1 = use next available
161 n = use minor number n
162 You can specify up to 64 cameras this way.
163 For example:
164 video_nr=-1,2,-1 would assign minor number 2 to the second
165 registered camera and use auto for the first one and for every
166 other camera.
Luca Risolia7ce08c92006-01-11 02:06:59 +0000167Default: -1
168-------------------------------------------------------------------------------
169Name: force_munmap
170Type: bool array (min = 0, max = 64)
171Syntax: <0|1[,...]>
172Description: Force the application to unmap previously mapped buffer memory
Michael Krufky6e204092006-05-23 17:41:31 -0300173 before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not
174 all the applications support this feature. This parameter is
175 specific for each detected camera.
176 0 = do not force memory unmapping
177 1 = force memory unmapping (save memory)
Luca Risolia7ce08c92006-01-11 02:06:59 +0000178Default: 0
179-------------------------------------------------------------------------------
Luca Risoliaccad7782006-02-25 06:54:18 +0000180Name: frame_timeout
181Type: uint array (min = 0, max = 64)
182Syntax: <n[,...]>
183Description: Timeout for a video frame in seconds. This parameter is
Michael Krufky6e204092006-05-23 17:41:31 -0300184 specific for each detected camera. This parameter can be
185 changed at runtime thanks to the /sys filesystem interface.
Luca Risoliaccad7782006-02-25 06:54:18 +0000186Default: 2
187-------------------------------------------------------------------------------
Luca Risolia7ce08c92006-01-11 02:06:59 +0000188Name: debug
189Type: ushort
190Syntax: <n>
191Description: Debugging information level, from 0 to 3:
Michael Krufky6e204092006-05-23 17:41:31 -0300192 0 = none (use carefully)
193 1 = critical errors
194 2 = significant informations
195 3 = more verbose messages
196 Level 3 is useful for testing only, when only one device
197 is used at the same time. It also shows some more informations
198 about the hardware being detected. This module parameter can be
199 changed at runtime thanks to the /sys filesystem interface.
Luca Risolia7ce08c92006-01-11 02:06:59 +0000200Default: 2
201-------------------------------------------------------------------------------
202
203
2048. Optional device control through "sysfs"
205==========================================
206If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
207it is possible to read and write both the ET61X[12]51 and the image sensor
208registers by using the "sysfs" filesystem interface.
209
210There are four files in the /sys/class/video4linux/videoX directory for each
211registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files
212control the ET61X[12]51 bridge, while the other two control the sensor chip.
213"reg" and "i2c_reg" hold the values of the current register index where the
214following reading/writing operations are addressed at through "val" and
215"i2c_val". Their use is not intended for end-users, unless you know what you
216are doing. Remember that you must be logged in as root before writing to them.
217
218As an example, suppose we were to want to read the value contained in the
219register number 1 of the sensor register table - which is usually the product
220identifier - of the camera registered as "/dev/video0":
221
222 [root@localhost #] cd /sys/class/video4linux/video0
223 [root@localhost #] echo 1 > i2c_reg
224 [root@localhost #] cat i2c_val
225
Matt LaPlante84eb8d02006-10-03 22:53:09 +0200226Note that if the sensor registers cannot be read, "cat" will fail.
Luca Risolia7ce08c92006-01-11 02:06:59 +0000227To avoid race conditions, all the I/O accesses to the files are serialized.
228
229
2309. Supported devices
231====================
232None of the names of the companies as well as their products will be mentioned
233here. They have never collaborated with the author, so no advertising.
234
235From the point of view of a driver, what unambiguously identify a device are
236its vendor and product USB identifiers. Below is a list of known identifiers of
237devices mounting the ET61X[12]51 PC camera controllers:
238
239Vendor ID Product ID
240--------- ----------
2410x102c 0x6151
2420x102c 0x6251
2430x102c 0x6253
2440x102c 0x6254
2450x102c 0x6255
2460x102c 0x6256
2470x102c 0x6257
2480x102c 0x6258
2490x102c 0x6259
2500x102c 0x625a
2510x102c 0x625b
2520x102c 0x625c
2530x102c 0x625d
2540x102c 0x625e
2550x102c 0x625f
2560x102c 0x6260
2570x102c 0x6261
2580x102c 0x6262
2590x102c 0x6263
2600x102c 0x6264
2610x102c 0x6265
2620x102c 0x6266
2630x102c 0x6267
2640x102c 0x6268
2650x102c 0x6269
266
267The following image sensors are supported:
268
269Model Manufacturer
270----- ------------
271TAS5130D1B Taiwan Advanced Sensor Corporation
272
273All the available control settings of each image sensor are supported through
274the V4L2 interface.
275
276
27710. Notes for V4L2 application developers
Luca Risoliaccad7782006-02-25 06:54:18 +0000278=========================================
Luca Risolia7ce08c92006-01-11 02:06:59 +0000279This driver follows the V4L2 API specifications. In particular, it enforces two
280rules:
281
282- exactly one I/O method, either "mmap" or "read", is associated with each
283file descriptor. Once it is selected, the application must close and reopen the
284device to switch to the other I/O method;
285
286- although it is not mandatory, previously mapped buffer memory should always
287be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
288The same number of buffers as before will be allocated again to match the size
289of the new video frames, so you have to map the buffers again before any I/O
290attempts on them.
291
292Consistently with the hardware limits, this driver also supports image
293downscaling with arbitrary scaling factors from 1 and 2 in both directions.
294However, the V4L2 API specifications don't correctly define how the scaling
295factor can be chosen arbitrarily by the "negotiation" of the "source" and
296"target" rectangles. To work around this flaw, we have added the convention
297that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the
298scaling factor is restored to 1.
299
300This driver supports two different video formats: the first one is the "8-bit
301Sequential Bayer" format and can be used to obtain uncompressed video data
302from the device through the current I/O method, while the second one provides
303"raw" compressed video data (without frame headers not related to the
304compressed data). The current compression quality may vary from 0 to 1 and can
305be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP
306V4L2 ioctl's.
307
308
30911. Contact information
310=======================
311The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
312
313GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is
314'FCE635A4'; the public 1024-bit key should be available at any keyserver;
315the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'.