diff options
author | Michael Krufky <mkrufky@linuxtv.org> | 2006-04-02 01:14:11 -0500 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@infradead.org> | 2006-04-02 03:55:56 -0400 |
commit | 1864cfb1537e108c2fe7a8e178b28bffde5a5439 (patch) | |
tree | f25083dd3fb3781670ee4a37b52240a34dbfb67f /Documentation/video4linux/et61x251.txt | |
parent | cc33668b1eed1eac43f00cec639066047323b01d (diff) |
V4L/DVB (3653h): Move usb v4l docs into Documentation/video4linux
- Move documentation for usb v4l devices from
Documentation/usb to Documentation/video4linux.
- Removed trailing whitespace.
- Update Kconfig help text links to reflect the new file locations.
Signed-off-by: Michael Krufky <mkrufky@linuxtv.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@infradead.org>
Diffstat (limited to 'Documentation/video4linux/et61x251.txt')
-rw-r--r-- | Documentation/video4linux/et61x251.txt | 314 |
1 files changed, 314 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 | |||
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: frame_timeout | ||
180 | Type: uint array (min = 0, max = 64) | ||
181 | Syntax: <n[,...]> | ||
182 | Description: 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. | ||
185 | Default: 2 | ||
186 | ------------------------------------------------------------------------------- | ||
187 | Name: debug | ||
188 | Type: ushort | ||
189 | Syntax: <n> | ||
190 | Description: 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. | ||
199 | Default: 2 | ||
200 | ------------------------------------------------------------------------------- | ||
201 | |||
202 | |||
203 | 8. Optional device control through "sysfs" | ||
204 | ========================================== | ||
205 | If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled, | ||
206 | it is possible to read and write both the ET61X[12]51 and the image sensor | ||
207 | registers by using the "sysfs" filesystem interface. | ||
208 | |||
209 | There are four files in the /sys/class/video4linux/videoX directory for each | ||
210 | registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files | ||
211 | control 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 | ||
213 | following 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 | ||
215 | are doing. Remember that you must be logged in as root before writing to them. | ||
216 | |||
217 | As an example, suppose we were to want to read the value contained in the | ||
218 | register number 1 of the sensor register table - which is usually the product | ||
219 | identifier - 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 | |||
225 | Note that if the sensor registers can not be read, "cat" will fail. | ||
226 | To avoid race conditions, all the I/O accesses to the files are serialized. | ||
227 | |||
228 | |||
229 | 9. Supported devices | ||
230 | ==================== | ||
231 | None of the names of the companies as well as their products will be mentioned | ||
232 | here. They have never collaborated with the author, so no advertising. | ||
233 | |||
234 | From the point of view of a driver, what unambiguously identify a device are | ||
235 | its vendor and product USB identifiers. Below is a list of known identifiers of | ||
236 | devices mounting the ET61X[12]51 PC camera controllers: | ||
237 | |||
238 | Vendor ID Product ID | ||
239 | --------- ---------- | ||
240 | 0x102c 0x6151 | ||
241 | 0x102c 0x6251 | ||
242 | 0x102c 0x6253 | ||
243 | 0x102c 0x6254 | ||
244 | 0x102c 0x6255 | ||
245 | 0x102c 0x6256 | ||
246 | 0x102c 0x6257 | ||
247 | 0x102c 0x6258 | ||
248 | 0x102c 0x6259 | ||
249 | 0x102c 0x625a | ||
250 | 0x102c 0x625b | ||
251 | 0x102c 0x625c | ||
252 | 0x102c 0x625d | ||
253 | 0x102c 0x625e | ||
254 | 0x102c 0x625f | ||
255 | 0x102c 0x6260 | ||
256 | 0x102c 0x6261 | ||
257 | 0x102c 0x6262 | ||
258 | 0x102c 0x6263 | ||
259 | 0x102c 0x6264 | ||
260 | 0x102c 0x6265 | ||
261 | 0x102c 0x6266 | ||
262 | 0x102c 0x6267 | ||
263 | 0x102c 0x6268 | ||
264 | 0x102c 0x6269 | ||
265 | |||
266 | The following image sensors are supported: | ||
267 | |||
268 | Model Manufacturer | ||
269 | ----- ------------ | ||
270 | TAS5130D1B Taiwan Advanced Sensor Corporation | ||
271 | |||
272 | All the available control settings of each image sensor are supported through | ||
273 | the V4L2 interface. | ||
274 | |||
275 | |||
276 | 10. Notes for V4L2 application developers | ||
277 | ========================================= | ||
278 | This driver follows the V4L2 API specifications. In particular, it enforces two | ||
279 | rules: | ||
280 | |||
281 | - exactly one I/O method, either "mmap" or "read", is associated with each | ||
282 | file descriptor. Once it is selected, the application must close and reopen the | ||
283 | device to switch to the other I/O method; | ||
284 | |||
285 | - although it is not mandatory, previously mapped buffer memory should always | ||
286 | be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. | ||
287 | The same number of buffers as before will be allocated again to match the size | ||
288 | of the new video frames, so you have to map the buffers again before any I/O | ||
289 | attempts on them. | ||
290 | |||
291 | Consistently with the hardware limits, this driver also supports image | ||
292 | downscaling with arbitrary scaling factors from 1 and 2 in both directions. | ||
293 | However, the V4L2 API specifications don't correctly define how the scaling | ||
294 | factor can be chosen arbitrarily by the "negotiation" of the "source" and | ||
295 | "target" rectangles. To work around this flaw, we have added the convention | ||
296 | that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the | ||
297 | scaling factor is restored to 1. | ||
298 | |||
299 | This driver supports two different video formats: the first one is the "8-bit | ||
300 | Sequential Bayer" format and can be used to obtain uncompressed video data | ||
301 | from 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 | ||
303 | compressed data). The current compression quality may vary from 0 to 1 and can | ||
304 | be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP | ||
305 | V4L2 ioctl's. | ||
306 | |||
307 | |||
308 | 11. Contact information | ||
309 | ======================= | ||
310 | The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. | ||
311 | |||
312 | GPG/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; | ||
314 | the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. | ||