About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / et61x251.txt


Based on kernel version 3.8. Page generated on 2013-02-20 22:07 EST.

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-2007 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 instance, 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", "v4l2_common", "compat_ioctl32",
139	"usbcore" and, depending on the USB host controller you have, "ehci-hcd",
140	"uhci-hcd" or "ohci-hcd".
141	
142	Loading can be done as shown below:
143	
144		[root@localhost home]# modprobe et61x251
145	
146	At this point the devices should be recognized. You can invoke "dmesg" to
147	analyze kernel messages and verify that the loading process has gone well:
148	
149		[user@localhost home]$ dmesg
150	
151	
152	7. Module parameters
153	====================
154	Module parameters are listed below:
155	-------------------------------------------------------------------------------
156	Name:           video_nr
157	Type:           short array (min = 0, max = 64)
158	Syntax:         <-1|n[,...]>
159	Description:    Specify V4L2 minor mode number:
160			-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.
167	Default:        -1
168	-------------------------------------------------------------------------------
169	Name:           force_munmap
170	Type:           bool array (min = 0, max = 64)
171	Syntax:         <0|1[,...]>
172	Description:    Force the application to unmap previously mapped buffer memory
173			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)
178	Default:        0
179	-------------------------------------------------------------------------------
180	Name:           frame_timeout
181	Type:           uint array (min = 0, max = 64)
182	Syntax:         <n[,...]>
183	Description:    Timeout for a video frame in seconds. This parameter is
184			specific for each detected camera. This parameter can be
185			changed at runtime thanks to the /sys filesystem interface.
186	Default:        2
187	-------------------------------------------------------------------------------
188	Name:           debug
189	Type:           ushort
190	Syntax:         <n>
191	Description:    Debugging information level, from 0 to 3:
192			0 = none (use carefully)
193			1 = critical errors
194			2 = significant information
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 information
198			about the hardware being detected. This module parameter can be
199			changed at runtime thanks to the /sys filesystem interface.
200	Default:        2
201	-------------------------------------------------------------------------------
202	
203	
204	8. Optional device control through "sysfs"
205	==========================================
206	If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
207	it is possible to read and write both the ET61X[12]51 and the image sensor
208	registers by using the "sysfs" filesystem interface.
209	
210	There are four files in the /sys/class/video4linux/videoX directory for each
211	registered camera: "reg", "val", "i2c_reg" and "i2c_val". The first two files
212	control 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
214	following 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
216	are doing. Remember that you must be logged in as root before writing to them.
217	
218	As an example, suppose we were to want to read the value contained in the
219	register number 1 of the sensor register table - which is usually the product
220	identifier - 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	
226	Note that if the sensor registers cannot be read, "cat" will fail.
227	To avoid race conditions, all the I/O accesses to the files are serialized.
228	
229	
230	9. Supported devices
231	====================
232	None of the names of the companies as well as their products will be mentioned
233	here. They have never collaborated with the author, so no advertising.
234	
235	From the point of view of a driver, what unambiguously identify a device are
236	its vendor and product USB identifiers. Below is a list of known identifiers of
237	devices mounting the ET61X[12]51 PC camera controllers:
238	
239	Vendor ID  Product ID
240	---------  ----------
241	0x102c     0x6151
242	0x102c     0x6251
243	0x102c     0x6253
244	0x102c     0x6254
245	0x102c     0x6255
246	0x102c     0x6256
247	0x102c     0x6257
248	0x102c     0x6258
249	0x102c     0x6259
250	0x102c     0x625a
251	0x102c     0x625b
252	0x102c     0x625c
253	0x102c     0x625d
254	0x102c     0x625e
255	0x102c     0x625f
256	0x102c     0x6260
257	0x102c     0x6261
258	0x102c     0x6262
259	0x102c     0x6263
260	0x102c     0x6264
261	0x102c     0x6265
262	0x102c     0x6266
263	0x102c     0x6267
264	0x102c     0x6268
265	0x102c     0x6269
266	
267	The following image sensors are supported:
268	
269	Model       Manufacturer
270	-----       ------------
271	TAS5130D1B  Taiwan Advanced Sensor Corporation
272	
273	All the available control settings of each image sensor are supported through
274	the V4L2 interface.
275	
276	
277	10. Notes for V4L2 application developers
278	=========================================
279	This driver follows the V4L2 API specifications. In particular, it enforces two
280	rules:
281	
282	- exactly one I/O method, either "mmap" or "read", is associated with each
283	file descriptor. Once it is selected, the application must close and reopen the
284	device to switch to the other I/O method;
285	
286	- although it is not mandatory, previously mapped buffer memory should always
287	be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's.
288	The same number of buffers as before will be allocated again to match the size
289	of the new video frames, so you have to map the buffers again before any I/O
290	attempts on them.
291	
292	Consistently with the hardware limits, this driver also supports image
293	downscaling with arbitrary scaling factors from 1 and 2 in both directions.
294	However, the V4L2 API specifications don't correctly define how the scaling
295	factor can be chosen arbitrarily by the "negotiation" of the "source" and
296	"target" rectangles. To work around this flaw, we have added the convention
297	that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the
298	scaling factor is restored to 1.
299	
300	This driver supports two different video formats: the first one is the "8-bit
301	Sequential Bayer" format and can be used to obtain uncompressed video data
302	from 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
304	compressed data). The current compression quality may vary from 0 to 1 and can
305	be selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP
306	V4L2 ioctl's.
307	
308	
309	11. Contact information
310	=======================
311	The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>.
312	
313	GPG/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;
315	the fingerprint is: '88E8 F32F 7244 68BA 3958  5D40 99DA 5D2A FCE6 35A4'.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog