Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | SN9C10x 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. How to add plug-in's for new image sensors | |
21 | 11. Notes for V4L2 application developers | |
22 | 12. Video frame formats | |
23 | 13. Contact information | |
24 | 14. Credits | |
25 | ||
26 | ||
27 | 1. Copyright | |
28 | ============ | |
29 | Copyright (C) 2004-2005 by Luca Risolia <luca.risolia@studio.unibo.it> | |
30 | ||
31 | ||
32 | 2. Disclaimer | |
33 | ============= | |
34 | SONiX is a trademark of SONiX Technology Company Limited, inc. | |
35 | This software is not sponsored or developed by SONiX. | |
36 | ||
37 | ||
38 | 3. License | |
39 | ========== | |
40 | This program is free software; you can redistribute it and/or modify | |
41 | it under the terms of the GNU General Public License as published by | |
42 | the Free Software Foundation; either version 2 of the License, or | |
43 | (at your option) any later version. | |
44 | ||
45 | This program is distributed in the hope that it will be useful, | |
46 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
47 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
48 | GNU General Public License for more details. | |
49 | ||
50 | You should have received a copy of the GNU General Public License | |
51 | along with this program; if not, write to the Free Software | |
52 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
53 | ||
54 | ||
55 | 4. Overview and features | |
56 | ======================== | |
57 | This driver attempts to support the video and audio streaming capabilities of | |
58 | the devices mounting the SONiX SN9C101, SN9C102 and SN9C103 PC Camera | |
59 | Controllers. | |
60 | ||
61 | It's worth to note that SONiX has never collaborated with the author during the | |
62 | development of this project, despite several requests for enough detailed | |
63 | specifications of the register tables, compression engine and video data format | |
64 | of the above chips. Nevertheless, these informations are no longer necessary, | |
65 | becouse all the aspects related to these chips are known and have been | |
66 | described in detail in this documentation. | |
67 | ||
68 | The driver relies on the Video4Linux2 and USB core modules. It has been | |
69 | designed to run properly on SMP systems as well. | |
70 | ||
71 | The latest version of the SN9C10x driver can be found at the following URL: | |
72 | http://www.linux-projects.org/ | |
73 | ||
74 | Some of the features of the driver are: | |
75 | ||
76 | - full compliance with the Video4Linux2 API (see also "Notes for V4L2 | |
77 | application developers" paragraph); | |
78 | - available mmap or read/poll methods for video streaming through isochronous | |
79 | data transfers; | |
80 | - automatic detection of image sensor; | |
81 | - support for any window resolutions and optional panning within the maximum | |
82 | pixel area of image sensor; | |
83 | - image downscaling with arbitrary scaling factors from 1, 2 and 4 in both | |
84 | directions (see "Notes for V4L2 application developers" paragraph); | |
85 | - two different video formats for uncompressed or compressed data in low or | |
86 | high compression quality (see also "Notes for V4L2 application developers" | |
87 | and "Video frame formats" paragraphs); | |
88 | - full support for the capabilities of many of the possible image sensors that | |
89 | can be connected to the SN9C10x bridges, including, for istance, red, green, | |
90 | blue and global gain adjustments and exposure (see "Supported devices" | |
91 | paragraph for details); | |
92 | - use of default color settings for sunlight conditions; | |
93 | - dynamic I/O interface for both SN9C10x and image sensor control and | |
94 | monitoring (see "Optional device control through 'sysfs'" paragraph); | |
95 | - dynamic driver control thanks to various module parameters (see "Module | |
96 | parameters" paragraph); | |
97 | - up to 64 cameras can be handled at the same time; they can be connected and | |
98 | disconnected from the host many times without turning off the computer, if | |
99 | your system supports hotplugging; | |
100 | - no known bugs. | |
101 | ||
102 | ||
103 | 5. Module dependencies | |
104 | ====================== | |
105 | For it to work properly, the driver needs kernel support for Video4Linux and | |
106 | USB. | |
107 | ||
108 | The following options of the kernel configuration file must be enabled and | |
109 | corresponding modules must be compiled: | |
110 | ||
111 | # Multimedia devices | |
112 | # | |
113 | CONFIG_VIDEO_DEV=m | |
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_SN9C102=m | |
133 | ||
134 | ||
135 | 6. Module loading | |
136 | ================= | |
137 | To use the driver, it is necessary to load the "sn9c102" 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 sn9c102 | |
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: int 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 | recognized 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: int | |
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. It also shows some more informations about the | |
189 | hardware being detected. This parameter can be changed at | |
190 | runtime thanks to the /sys filesystem. | |
191 | Default: 2 | |
192 | ------------------------------------------------------------------------------- | |
193 | ||
194 | ||
195 | 8. Optional device control through "sysfs" [1] | |
196 | ========================================== | |
197 | It is possible to read and write both the SN9C10x and the image sensor | |
198 | registers by using the "sysfs" filesystem interface. | |
199 | ||
200 | Every time a supported device is recognized, a write-only file named "green" is | |
201 | created in the /sys/class/video4linux/videoX directory. You can set the green | |
202 | channel's gain by writing the desired value to it. The value may range from 0 | |
203 | to 15 for SN9C101 or SN9C102 bridges, from 0 to 127 for SN9C103 bridges. | |
204 | Similarly, only for SN9C103 controllers, blue and red gain control files are | |
205 | available in the same directory, for which accepted values may range from 0 to | |
206 | 127. | |
207 | ||
208 | There are other four entries in the directory above for each registered camera: | |
209 | "reg", "val", "i2c_reg" and "i2c_val". The first two files control the | |
210 | SN9C10x bridge, while the other two control the sensor chip. "reg" and | |
211 | "i2c_reg" hold the values of the current register index where the following | |
212 | reading/writing operations are addressed at through "val" and "i2c_val". Their | |
213 | use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not | |
214 | be created if the sensor does not actually support the standard I2C protocol or | |
215 | its registers are not 8-bit long. Also, remember that you must be logged in as | |
216 | 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 "cat" will fail if sensor registers cannot be read. | |
227 | ||
228 | Now let's set the green gain's register of the SN9C101 or SN9C102 chips to 2: | |
229 | ||
230 | [root@localhost #] echo 0x11 > reg | |
231 | [root@localhost #] echo 2 > val | |
232 | ||
233 | Note that the SN9C10x always returns 0 when some of its registers are read. | |
234 | To avoid race conditions, all the I/O accesses to the above files are | |
235 | serialized. | |
236 | ||
237 | The sysfs interface also provides the "frame_header" entry, which exports the | |
238 | frame header of the most recent requested and captured video frame. The header | |
239 | is 12-bytes long and is appended to every video frame by the SN9C10x | |
240 | controllers. As an example, this additional information can be used by the user | |
241 | application for implementing auto-exposure features via software. | |
242 | ||
243 | The following table describes the frame header: | |
244 | ||
245 | Byte # Value Description | |
246 | ------ ----- ----------- | |
247 | 0x00 0xFF Frame synchronisation pattern. | |
248 | 0x01 0xFF Frame synchronisation pattern. | |
249 | 0x02 0x00 Frame synchronisation pattern. | |
250 | 0x03 0xC4 Frame synchronisation pattern. | |
251 | 0x04 0xC4 Frame synchronisation pattern. | |
252 | 0x05 0x96 Frame synchronisation pattern. | |
253 | 0x06 0x00 or 0x01 Unknown meaning. The exact value depends on the chip. | |
254 | 0x07 0xXX Variable value, whose bits are ff00uzzc, where ff is a | |
255 | frame counter, u is unknown, zz is a size indicator | |
256 | (00 = VGA, 01 = SIF, 10 = QSIF) and c stands for | |
257 | "compression enabled" (1 = yes, 0 = no). | |
258 | 0x08 0xXX Brightness sum inside Auto-Exposure area (low-byte). | |
259 | 0x09 0xXX Brightness sum inside Auto-Exposure area (high-byte). | |
260 | For a pure white image, this number will be equal to 500 | |
261 | times the area of the specified AE area. For images | |
262 | that are not pure white, the value scales down according | |
263 | to relative whiteness. | |
264 | 0x0A 0xXX Brightness sum outside Auto-Exposure area (low-byte). | |
265 | 0x0B 0xXX Brightness sum outside Auto-Exposure area (high-byte). | |
266 | For a pure white image, this number will be equal to 125 | |
267 | times the area outside of the specified AE area. For | |
268 | images that are not pure white, the value scales down | |
269 | according to relative whiteness. | |
270 | ||
271 | The AE area (sx, sy, ex, ey) in the active window can be set by programming the | |
272 | registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C10x controllers, where one unit | |
273 | corresponds to 32 pixels. | |
274 | ||
275 | [1] The frame header has been documented by Bertrik Sikken. | |
276 | ||
277 | ||
278 | 9. Supported devices | |
279 | ==================== | |
280 | None of the names of the companies as well as their products will be mentioned | |
281 | here. They have never collaborated with the author, so no advertising. | |
282 | ||
283 | From the point of view of a driver, what unambiguously identify a device are | |
284 | its vendor and product USB identifiers. Below is a list of known identifiers of | |
285 | devices mounting the SN9C10x PC camera controllers: | |
286 | ||
287 | Vendor ID Product ID | |
288 | --------- ---------- | |
289 | 0x0c45 0x6001 | |
290 | 0x0c45 0x6005 | |
291 | 0x0c45 0x6009 | |
292 | 0x0c45 0x600d | |
293 | 0x0c45 0x6024 | |
294 | 0x0c45 0x6025 | |
295 | 0x0c45 0x6028 | |
296 | 0x0c45 0x6029 | |
297 | 0x0c45 0x602a | |
298 | 0x0c45 0x602b | |
299 | 0x0c45 0x602c | |
300 | 0x0c45 0x6030 | |
301 | 0x0c45 0x6080 | |
302 | 0x0c45 0x6082 | |
303 | 0x0c45 0x6083 | |
304 | 0x0c45 0x6088 | |
305 | 0x0c45 0x608a | |
306 | 0x0c45 0x608b | |
307 | 0x0c45 0x608c | |
308 | 0x0c45 0x608e | |
309 | 0x0c45 0x608f | |
310 | 0x0c45 0x60a0 | |
311 | 0x0c45 0x60a2 | |
312 | 0x0c45 0x60a3 | |
313 | 0x0c45 0x60a8 | |
314 | 0x0c45 0x60aa | |
315 | 0x0c45 0x60ab | |
316 | 0x0c45 0x60ac | |
317 | 0x0c45 0x60ae | |
318 | 0x0c45 0x60af | |
319 | 0x0c45 0x60b0 | |
320 | 0x0c45 0x60b2 | |
321 | 0x0c45 0x60b3 | |
322 | 0x0c45 0x60b8 | |
323 | 0x0c45 0x60ba | |
324 | 0x0c45 0x60bb | |
325 | 0x0c45 0x60bc | |
326 | 0x0c45 0x60be | |
327 | ||
328 | The list above does not imply that all those devices work with this driver: up | |
329 | until now only the ones that mount the following image sensors are supported; | |
330 | kernel messages will always tell you whether this is the case: | |
331 | ||
332 | Model Manufacturer | |
333 | ----- ------------ | |
334 | HV7131D Hynix Semiconductor, Inc. | |
335 | MI-0343 Micron Technology, Inc. | |
336 | PAS106B PixArt Imaging, Inc. | |
337 | PAS202BCB PixArt Imaging, Inc. | |
338 | TAS5110C1B Taiwan Advanced Sensor Corporation | |
339 | TAS5130D1B Taiwan Advanced Sensor Corporation | |
340 | ||
341 | All the available control settings of each image sensor are supported through | |
342 | the V4L2 interface. | |
343 | ||
344 | Donations of new models for further testing and support would be much | |
345 | appreciated. Non-available hardware will not be supported by the author of this | |
346 | driver. | |
347 | ||
348 | ||
349 | 10. How to add plug-in's for new image sensors | |
350 | ============================================== | |
351 | It should be easy to write plug-in's for new sensors by using the small API | |
352 | that has been created for this purpose, which is present in "sn9c102_sensor.h" | |
353 | (documentation is included there). As an example, have a look at the code in | |
354 | "sn9c102_pas106b.c", which uses the mentioned interface. | |
355 | ||
356 | At the moment, possible unsupported image sensors are: CIS-VF10 (VGA), | |
357 | OV7620 (VGA), OV7630 (VGA). | |
358 | ||
359 | ||
360 | 11. Notes for V4L2 application developers | |
361 | ========================================= | |
362 | This driver follows the V4L2 API specifications. In particular, it enforces two | |
363 | rules: | |
364 | ||
365 | - exactly one I/O method, either "mmap" or "read", is associated with each | |
366 | file descriptor. Once it is selected, the application must close and reopen the | |
367 | device to switch to the other I/O method; | |
368 | ||
369 | - although it is not mandatory, previously mapped buffer memory should always | |
370 | be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. | |
371 | The same number of buffers as before will be allocated again to match the size | |
372 | of the new video frames, so you have to map the buffers again before any I/O | |
373 | attempts on them. | |
374 | ||
375 | Consistently with the hardware limits, this driver also supports image | |
376 | downscaling with arbitrary scaling factors from 1, 2 and 4 in both directions. | |
377 | However, the V4L2 API specifications don't correctly define how the scaling | |
378 | factor can be chosen arbitrarily by the "negotiation" of the "source" and | |
379 | "target" rectangles. To work around this flaw, we have added the convention | |
380 | that, during the negotiation, whenever the "VIDIOC_S_CROP" ioctl is issued, the | |
381 | scaling factor is restored to 1. | |
382 | ||
383 | This driver supports two different video formats: the first one is the "8-bit | |
384 | Sequential Bayer" format and can be used to obtain uncompressed video data | |
385 | from the device through the current I/O method, while the second one provides | |
386 | "raw" compressed video data (without frame headers not related to the | |
387 | compressed data). The compression quality may vary from 0 to 1 and can be | |
388 | selected or queried thanks to the VIDIOC_S_JPEGCOMP and VIDIOC_G_JPEGCOMP V4L2 | |
389 | ioctl's. For maximum flexibility, both the default active video format and the | |
390 | default compression quality depend on how the image sensor being used is | |
391 | initialized (as described in the documentation of the API for the image sensors | |
392 | supplied by this driver). | |
393 | ||
394 | ||
395 | 12. Video frame formats [1] | |
396 | ======================= | |
397 | The SN9C10x PC Camera Controllers can send images in two possible video | |
398 | formats over the USB: either native "Sequential RGB Bayer" or Huffman | |
399 | compressed. The latter is used to achieve high frame rates. The current video | |
400 | format may be selected or queried from the user application by calling the | |
401 | VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API | |
402 | specifications. | |
403 | ||
404 | The name "Sequential Bayer" indicates the organization of the red, green and | |
405 | blue pixels in one video frame. Each pixel is associated with a 8-bit long | |
406 | value and is disposed in memory according to the pattern shown below: | |
407 | ||
408 | B[0] G[1] B[2] G[3] ... B[m-2] G[m-1] | |
409 | G[m] R[m+1] G[m+2] R[m+2] ... G[2m-2] R[2m-1] | |
410 | ... | |
411 | ... B[(n-1)(m-2)] G[(n-1)(m-1)] | |
412 | ... G[n(m-2)] R[n(m-1)] | |
413 | ||
414 | The above matrix also represents the sequential or progressive read-out mode of | |
415 | the (n, m) Bayer color filter array used in many CCD/CMOS image sensors. | |
416 | ||
417 | One compressed video frame consists of a bitstream that encodes for every R, G, | |
418 | or B pixel the difference between the value of the pixel itself and some | |
419 | reference pixel value. Pixels are organised in the Bayer pattern and the Bayer | |
420 | sub-pixels are tracked individually and alternatingly. For example, in the | |
421 | first line values for the B and G1 pixels are alternatingly encoded, while in | |
422 | the second line values for the G2 and R pixels are alternatingly encoded. | |
423 | ||
424 | The pixel reference value is calculated as follows: | |
425 | - the 4 top left pixels are encoded in raw uncompressed 8-bit format; | |
426 | - the value in the top two rows is the value of the pixel left of the current | |
427 | pixel; | |
428 | - the value in the left column is the value of the pixel above the current | |
429 | pixel; | |
430 | - for all other pixels, the reference value is the average of the value of the | |
431 | pixel on the left and the value of the pixel above the current pixel; | |
432 | - there is one code in the bitstream that specifies the value of a pixel | |
433 | directly (in 4-bit resolution); | |
434 | - pixel values need to be clamped inside the range [0..255] for proper | |
435 | decoding. | |
436 | ||
437 | The algorithm purely describes the conversion from compressed Bayer code used | |
438 | in the SN9C10x chips to uncompressed Bayer. Additional steps are required to | |
439 | convert this to a color image (i.e. a color interpolation algorithm). | |
440 | ||
441 | The following Huffman codes have been found: | |
442 | 0: +0 (relative to reference pixel value) | |
443 | 100: +4 | |
444 | 101: -4? | |
445 | 1110xxxx: set absolute value to xxxx.0000 | |
446 | 1101: +11 | |
447 | 1111: -11 | |
448 | 11001: +20 | |
449 | 110000: -20 | |
450 | 110001: ??? - these codes are apparently not used | |
451 | ||
452 | [1] The Huffman compression algorithm has been reverse-engineered and | |
453 | documented by Bertrik Sikken. | |
454 | ||
455 | ||
456 | 13. Contact information | |
457 | ======================= | |
458 | The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. | |
459 | ||
460 | GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is | |
461 | 'FCE635A4'; the public 1024-bit key should be available at any keyserver; | |
462 | the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. | |
463 | ||
464 | ||
465 | 14. Credits | |
466 | =========== | |
467 | Many thanks to following persons for their contribute (listed in alphabetical | |
468 | order): | |
469 | ||
470 | - Luca Capello for the donation of a webcam; | |
471 | - Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the | |
472 | donation of a webcam; | |
473 | - Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB | |
474 | image sensor; | |
475 | - Stefano Mozzi, who donated 45 EU; | |
476 | - Bertrik Sikken, who reverse-engineered and documented the Huffman compression | |
477 | algorithm used in the SN9C10x controllers and implemented the first decoder; | |
478 | - Mizuno Takafumi for the donation of a webcam; | |
479 | - An "anonymous" donator (who didn't want his name to be revealed) for the | |
480 | donation of a webcam. |