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