tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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'.