]>
Commit | Line | Data |
---|---|---|
7ce08c93 LR |
1 | |
2 | ET61X[12]51 PC Camera Controllers | |
3 | Driver for Linux | |
4 | ================================= | |
5 | ||
6 | - Documentation - | |
7 | ||
8 | ||
9 | Index | |
10 | ===== | |
11 | 1. Copyright | |
12 | 2. Disclaimer | |
13 | 3. License | |
14 | 4. Overview and features | |
15 | 5. Module dependencies | |
16 | 6. Module loading | |
17 | 7. Module parameters | |
18 | 8. Optional device control through "sysfs" | |
19 | 9. Supported devices | |
20 | 10. Notes for V4L2 application developers | |
21 | 11. Contact information | |
22 | ||
23 | ||
24 | 1. Copyright | |
25 | ============ | |
26 | Copyright (C) 2006 by Luca Risolia <luca.risolia@studio.unibo.it> | |
27 | ||
28 | ||
29 | 2. Disclaimer | |
30 | ============= | |
31 | Etoms is a trademark of Etoms Electronics Corp. | |
32 | This software is not developed or sponsored by Etoms Electronics. | |
33 | ||
34 | ||
35 | 3. License | |
36 | ========== | |
37 | This program is free software; you can redistribute it and/or modify | |
38 | it under the terms of the GNU General Public License as published by | |
39 | the Free Software Foundation; either version 2 of the License, or | |
40 | (at your option) any later version. | |
41 | ||
42 | This program is distributed in the hope that it will be useful, | |
43 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
44 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
45 | GNU General Public License for more details. | |
46 | ||
47 | You should have received a copy of the GNU General Public License | |
48 | along with this program; if not, write to the Free Software | |
49 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
50 | ||
51 | ||
52 | 4. Overview and features | |
53 | ======================== | |
54 | This driver supports the video interface of the devices mounting the ET61X151 | |
55 | or ET61X251 PC Camera Controllers. | |
56 | ||
57 | It's worth to note that Etoms Electronics has never collaborated with the | |
58 | author during the development of this project; despite several requests, | |
59 | Etoms Electronics also refused to release enough detailed specifications of | |
60 | the video compression engine. | |
61 | ||
62 | The driver relies on the Video4Linux2 and USB core modules. It has been | |
63 | designed to run properly on SMP systems as well. | |
64 | ||
65 | The latest version of the ET61X[12]51 driver can be found at the following URL: | |
66 | http://www.linux-projects.org/ | |
67 | ||
68 | Some 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 | ||
97 | 5. Module dependencies | |
98 | ====================== | |
99 | For it to work properly, the driver needs kernel support for Video4Linux and | |
100 | USB. | |
101 | ||
102 | The following options of the kernel configuration file must be enabled and | |
103 | corresponding modules must be compiled: | |
104 | ||
105 | # Multimedia devices | |
106 | # | |
107 | CONFIG_VIDEO_DEV=m | |
108 | ||
109 | To 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 | ||
119 | In addition, depending on the hardware being used, the modules below are | |
120 | necessary: | |
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 | ||
128 | And finally: | |
129 | ||
130 | # USB Multimedia devices | |
131 | # | |
132 | CONFIG_USB_ET61X251=m | |
133 | ||
134 | ||
135 | 6. Module loading | |
136 | ================= | |
137 | To use the driver, it is necessary to load the "et61x251" module into memory | |
138 | after every other module required: "videodev", "usbcore" and, depending on | |
139 | the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd". | |
140 | ||
141 | Loading can be done as shown below: | |
142 | ||
143 | [root@localhost home]# modprobe et61x251 | |
144 | ||
145 | At this point the devices should be recognized. You can invoke "dmesg" to | |
146 | analyze kernel messages and verify that the loading process has gone well: | |
147 | ||
148 | [user@localhost home]$ dmesg | |
149 | ||
150 | ||
151 | 7. Module parameters | |
152 | ==================== | |
153 | Module parameters are listed below: | |
154 | ------------------------------------------------------------------------------- | |
155 | Name: video_nr | |
156 | Type: short array (min = 0, max = 64) | |
157 | Syntax: <-1|n[,...]> | |
158 | Description: 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. | |
166 | Default: -1 | |
167 | ------------------------------------------------------------------------------- | |
168 | Name: force_munmap | |
169 | Type: bool array (min = 0, max = 64) | |
170 | Syntax: <0|1[,...]> | |
171 | Description: 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) | |
177 | Default: 0 | |
178 | ------------------------------------------------------------------------------- | |
179 | Name: debug | |
180 | Type: ushort | |
181 | Syntax: <n> | |
182 | Description: 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. | |
191 | Default: 2 | |
192 | ------------------------------------------------------------------------------- | |
193 | ||
194 | ||
195 | 8. Optional device control through "sysfs" | |
196 | ========================================== | |
197 | If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled, | |
198 | it is possible to read and write both the ET61X[12]51 and the image sensor | |
199 | registers by using the "sysfs" filesystem interface. | |
200 | ||
201 | There are four files in the /sys/class/video4linux/videoX directory for each | |
202 | registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files | |
203 | control 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 | |
205 | following 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 | |
207 | are doing. Remember that you must be logged in as root before writing to them. | |
208 | ||
209 | As an example, suppose we were to want to read the value contained in the | |
210 | register number 1 of the sensor register table - which is usually the product | |
211 | identifier - 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 | ||
217 | Note that if the sensor registers can not be read, "cat" will fail. | |
218 | To avoid race conditions, all the I/O accesses to the files are serialized. | |
219 | ||
220 | ||
221 | 9. Supported devices | |
222 | ==================== | |
223 | None of the names of the companies as well as their products will be mentioned | |
224 | here. They have never collaborated with the author, so no advertising. | |
225 | ||
226 | From the point of view of a driver, what unambiguously identify a device are | |
227 | its vendor and product USB identifiers. Below is a list of known identifiers of | |
228 | devices mounting the ET61X[12]51 PC camera controllers: | |
229 | ||
230 | Vendor ID Product ID | |
231 | --------- ---------- | |
232 | 0x102c 0x6151 | |
233 | 0x102c 0x6251 | |
234 | 0x102c 0x6253 | |
235 | 0x102c 0x6254 | |
236 | 0x102c 0x6255 | |
237 | 0x102c 0x6256 | |
238 | 0x102c 0x6257 | |
239 | 0x102c 0x6258 | |
240 | 0x102c 0x6259 | |
241 | 0x102c 0x625a | |
242 | 0x102c 0x625b | |
243 | 0x102c 0x625c | |
244 | 0x102c 0x625d | |
245 | 0x102c 0x625e | |
246 | 0x102c 0x625f | |
247 | 0x102c 0x6260 | |
248 | 0x102c 0x6261 | |
249 | 0x102c 0x6262 | |
250 | 0x102c 0x6263 | |
251 | 0x102c 0x6264 | |
252 | 0x102c 0x6265 | |
253 | 0x102c 0x6266 | |
254 | 0x102c 0x6267 | |
255 | 0x102c 0x6268 | |
256 | 0x102c 0x6269 | |
257 | ||
258 | The following image sensors are supported: | |
259 | ||
260 | Model Manufacturer | |
261 | ----- ------------ | |
262 | TAS5130D1B Taiwan Advanced Sensor Corporation | |
263 | ||
264 | All the available control settings of each image sensor are supported through | |
265 | the V4L2 interface. | |
266 | ||
267 | ||
268 | 10. Notes for V4L2 application developers | |
269 | ======================================== | |
270 | This driver follows the V4L2 API specifications. In particular, it enforces two | |
271 | rules: | |
272 | ||
273 | - exactly one I/O method, either "mmap" or "read", is associated with each | |
274 | file descriptor. Once it is selected, the application must close and reopen the | |
275 | device to switch to the other I/O method; | |
276 | ||
277 | - although it is not mandatory, previously mapped buffer memory should always | |
278 | be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. | |
279 | The same number of buffers as before will be allocated again to match the size | |
280 | of the new video frames, so you have to map the buffers again before any I/O | |
281 | attempts on them. | |
282 | ||
283 | Consistently with the hardware limits, this driver also supports image | |
284 | downscaling with arbitrary scaling factors from 1 and 2 in both directions. | |
285 | However, the V4L2 API specifications don't correctly define how the scaling | |
286 | factor can be chosen arbitrarily by the "negotiation" of the "source" and | |
287 | "target" rectangles. To work around this flaw, we have added the convention | |
288 | that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the | |
289 | scaling factor is restored to 1. | |
290 | ||
291 | This driver supports two different video formats: the first one is the "8-bit | |
292 | Sequential Bayer" format and can be used to obtain uncompressed video data | |
293 | from 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 | |
295 | compressed data). The current compression quality may vary from 0 to 1 and can | |
296 | be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP | |
297 | V4L2 ioctl's. | |
298 | ||
299 | ||
300 | 11. Contact information | |
301 | ======================= | |
302 | The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. | |
303 | ||
304 | GPG/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; | |
306 | the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. |