- SN9C10x PC Camera Controllers
+ SN9C1xx PC Camera Controllers
Driver for Linux
=============================
4. Overview and features
========================
-This driver attempts to support the video interface of the devices mounting the
-SONiX SN9C101, SN9C102 and SN9C103 PC Camera Controllers.
-
-It's worth to note that SONiX has never collaborated with the author during the
-development of this project, despite several requests for enough detailed
-specifications of the register tables, compression engine and video data format
-of the above chips. Nevertheless, these informations are no longer necessary,
-becouse all the aspects related to these chips are known and have been
-described in detail in this documentation.
+This driver attempts to support the video interface of the devices assembling
+the SONiX SN9C101, SN9C102, SN9C103, SN9C105 and SN9C120 PC Camera Controllers
+("SN9C1xx" from now on).
The driver relies on the Video4Linux2 and USB core modules. It has been
designed to run properly on SMP systems as well.
-The latest version of the SN9C10x driver can be found at the following URL:
+The latest version of the SN9C1xx driver can be found at the following URL:
http://www.linux-projects.org/
Some of the features of the driver are:
high compression quality (see also "Notes for V4L2 application developers"
and "Video frame formats" paragraphs);
- full support for the capabilities of many of the possible image sensors that
- can be connected to the SN9C10x bridges, including, for istance, red, green,
+ can be connected to the SN9C1xx bridges, including, for instance, red, green,
blue and global gain adjustments and exposure (see "Supported devices"
paragraph for details);
- use of default color settings for sunlight conditions;
-- dynamic I/O interface for both SN9C10x and image sensor control and
+- dynamic I/O interface for both SN9C1xx and image sensor control and
monitoring (see "Optional device control through 'sysfs'" paragraph);
- dynamic driver control thanks to various module parameters (see "Module
parameters" paragraph);
CONFIG_USB_UHCI_HCD=m
CONFIG_USB_OHCI_HCD=m
-The SN9C103 controller also provides a built-in microphone interface. It is
-supported by the USB Audio driver thanks to the ALSA API:
+The SN9C103, SN9c105 and SN9C120 controllers also provide a built-in microphone
+interface. It is supported by the USB Audio driver thanks to the ALSA API:
# Sound
#
6. Module loading
=================
To use the driver, it is necessary to load the "sn9c102" module into memory
-after every other module required: "videodev", "usbcore" and, depending on
-the USB host controller you have, "ehci-hcd", "uhci-hcd" or "ohci-hcd".
+after every other module required: "videodev", "v4l2_common", "compat_ioctl32",
+"usbcore" and, depending on the USB host controller you have, "ehci-hcd",
+"uhci-hcd" or "ohci-hcd".
Loading can be done as shown below:
[root@localhost home]# modprobe sn9c102
-At this point the devices should be recognized. You can invoke "dmesg" to
-analyze kernel messages and verify that the loading process has gone well:
+Note that the module is called "sn9c102" for historic reasons, althought it
+does not just support the SN9C102.
+
+At this point all the devices supported by the driver and connected to the USB
+ports should be recognized. You can invoke "dmesg" to analyze kernel messages
+and verify that the loading process has gone well:
[user@localhost home]$ dmesg
+or, to isolate all the kernel messages generated by the driver:
+
+ [user@localhost home]$ dmesg | grep sn9c102
+
7. Module parameters
====================
-------------------------------------------------------------------------------
Name: frame_timeout
Type: uint array (min = 0, max = 64)
-Syntax: <n[,...]>
-Description: Timeout for a video frame in seconds. This parameter is
- specific for each detected camera. This parameter can be
- changed at runtime thanks to the /sys filesystem interface.
+Syntax: <0|n[,...]>
+Description: Timeout for a video frame in seconds before returning an I/O
+ error; 0 for infinity. This parameter is specific for each
+ detected camera and can be changed at runtime thanks to the
+ /sys filesystem interface.
Default: 2
-------------------------------------------------------------------------------
Name: debug
8. Optional device control through "sysfs" [1]
==========================================
If the kernel has been compiled with the CONFIG_VIDEO_ADV_DEBUG option enabled,
-it is possible to read and write both the SN9C10x and the image sensor
+it is possible to read and write both the SN9C1xx and the image sensor
registers by using the "sysfs" filesystem interface.
Every time a supported device is recognized, a write-only file named "green" is
created in the /sys/class/video4linux/videoX directory. You can set the green
channel's gain by writing the desired value to it. The value may range from 0
-to 15 for SN9C101 or SN9C102 bridges, from 0 to 127 for SN9C103 bridges.
-Similarly, only for SN9C103 controllers, blue and red gain control files are
-available in the same directory, for which accepted values may range from 0 to
-127.
+to 15 for the SN9C101 or SN9C102 bridges, from 0 to 127 for the SN9C103,
+SN9C105 and SN9C120 bridges.
+Similarly, only for the SN9C103, SN9C105 and SN9120 controllers, blue and red
+gain control files are available in the same directory, for which accepted
+values may range from 0 to 127.
There are other four entries in the directory above for each registered camera:
"reg", "val", "i2c_reg" and "i2c_val". The first two files control the
-SN9C10x bridge, while the other two control the sensor chip. "reg" and
+SN9C1xx bridge, while the other two control the sensor chip. "reg" and
"i2c_reg" hold the values of the current register index where the following
reading/writing operations are addressed at through "val" and "i2c_val". Their
use is not intended for end-users. Note that "i2c_reg" and "i2c_val" will not
[root@localhost #] echo 0x11 > reg
[root@localhost #] echo 2 > val
-Note that the SN9C10x always returns 0 when some of its registers are read.
+Note that the SN9C1xx always returns 0 when some of its registers are read.
To avoid race conditions, all the I/O accesses to the above files are
serialized.
-
The sysfs interface also provides the "frame_header" entry, which exports the
frame header of the most recent requested and captured video frame. The header
-is always 18-bytes long and is appended to every video frame by the SN9C10x
+is always 18-bytes long and is appended to every video frame by the SN9C1xx
controllers. As an example, this additional information can be used by the user
application for implementing auto-exposure features via software.
-The following table describes the frame header:
-
-Byte # Value Description
------- ----- -----------
-0x00 0xFF Frame synchronisation pattern.
-0x01 0xFF Frame synchronisation pattern.
-0x02 0x00 Frame synchronisation pattern.
-0x03 0xC4 Frame synchronisation pattern.
-0x04 0xC4 Frame synchronisation pattern.
-0x05 0x96 Frame synchronisation pattern.
-0x06 0xXX Unknown meaning. The exact value depends on the chip;
- possible values are 0x00, 0x01 and 0x20.
-0x07 0xXX Variable value, whose bits are ff00uzzc, where ff is a
- frame counter, u is unknown, zz is a size indicator
- (00 = VGA, 01 = SIF, 10 = QSIF) and c stands for
- "compression enabled" (1 = yes, 0 = no).
-0x08 0xXX Brightness sum inside Auto-Exposure area (low-byte).
-0x09 0xXX Brightness sum inside Auto-Exposure area (high-byte).
- For a pure white image, this number will be equal to 500
- times the area of the specified AE area. For images
- that are not pure white, the value scales down according
- to relative whiteness.
-0x0A 0xXX Brightness sum outside Auto-Exposure area (low-byte).
-0x0B 0xXX Brightness sum outside Auto-Exposure area (high-byte).
- For a pure white image, this number will be equal to 125
- times the area outside of the specified AE area. For
- images that are not pure white, the value scales down
- according to relative whiteness.
- according to relative whiteness.
-
-The following bytes are used by the SN9C103 bridge only:
-
-0x0C 0xXX Unknown meaning
-0x0D 0xXX Unknown meaning
-0x0E 0xXX Unknown meaning
-0x0F 0xXX Unknown meaning
-0x10 0xXX Unknown meaning
-0x11 0xXX Unknown meaning
+The following table describes the frame header exported by the SN9C101 and
+SN9C102:
+
+Byte # Value or bits Description
+------ ------------- -----------
+0x00 0xFF Frame synchronisation pattern
+0x01 0xFF Frame synchronisation pattern
+0x02 0x00 Frame synchronisation pattern
+0x03 0xC4 Frame synchronisation pattern
+0x04 0xC4 Frame synchronisation pattern
+0x05 0x96 Frame synchronisation pattern
+0x06 [3:0] Read channel gain control = (1+R_GAIN/8)
+ [7:4] Blue channel gain control = (1+B_GAIN/8)
+0x07 [ 0 ] Compression mode. 0=No compression, 1=Compression enabled
+ [2:1] Maximum scale factor for compression
+ [ 3 ] 1 = USB fifo(2K bytes) is full
+ [ 4 ] 1 = Digital gain is finish
+ [ 5 ] 1 = Exposure is finish
+ [7:6] Frame index
+0x08 [7:0] Y sum inside Auto-Exposure area (low-byte)
+0x09 [7:0] Y sum inside Auto-Exposure area (high-byte)
+ where Y sum = (R/4 + 5G/16 + B/8) / 32
+0x0A [7:0] Y sum outside Auto-Exposure area (low-byte)
+0x0B [7:0] Y sum outside Auto-Exposure area (high-byte)
+ where Y sum = (R/4 + 5G/16 + B/8) / 128
+0x0C 0xXX Not used
+0x0D 0xXX Not used
+0x0E 0xXX Not used
+0x0F 0xXX Not used
+0x10 0xXX Not used
+0x11 0xXX Not used
+
+The following table describes the frame header exported by the SN9C103:
+
+Byte # Value or bits Description
+------ ------------- -----------
+0x00 0xFF Frame synchronisation pattern
+0x01 0xFF Frame synchronisation pattern
+0x02 0x00 Frame synchronisation pattern
+0x03 0xC4 Frame synchronisation pattern
+0x04 0xC4 Frame synchronisation pattern
+0x05 0x96 Frame synchronisation pattern
+0x06 [6:0] Read channel gain control = (1/2+R_GAIN/64)
+0x07 [6:0] Blue channel gain control = (1/2+B_GAIN/64)
+ [7:4]
+0x08 [ 0 ] Compression mode. 0=No compression, 1=Compression enabled
+ [2:1] Maximum scale factor for compression
+ [ 3 ] 1 = USB fifo(2K bytes) is full
+ [ 4 ] 1 = Digital gain is finish
+ [ 5 ] 1 = Exposure is finish
+ [7:6] Frame index
+0x09 [7:0] Y sum inside Auto-Exposure area (low-byte)
+0x0A [7:0] Y sum inside Auto-Exposure area (high-byte)
+ where Y sum = (R/4 + 5G/16 + B/8) / 32
+0x0B [7:0] Y sum outside Auto-Exposure area (low-byte)
+0x0C [7:0] Y sum outside Auto-Exposure area (high-byte)
+ where Y sum = (R/4 + 5G/16 + B/8) / 128
+0x0D [1:0] Audio frame number
+ [ 2 ] 1 = Audio is recording
+0x0E [7:0] Audio summation (low-byte)
+0x0F [7:0] Audio summation (high-byte)
+0x10 [7:0] Audio sample count
+0x11 [7:0] Audio peak data in audio frame
The AE area (sx, sy, ex, ey) in the active window can be set by programming the
-registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C10x controllers, where one unit
+registers 0x1c, 0x1d, 0x1e and 0x1f of the SN9C1xx controllers, where one unit
corresponds to 32 pixels.
-[1] Part of the meaning of the frame header has been documented by Bertrik
- Sikken.
+[1] The frame headers exported by the SN9C105 and SN9C120 are not described.
9. Supported devices
From the point of view of a driver, what unambiguously identify a device are
its vendor and product USB identifiers. Below is a list of known identifiers of
-devices mounting the SN9C10x PC camera controllers:
+devices assembling the SN9C1xx PC camera controllers:
Vendor ID Product ID
--------- ----------
+0x0471 0x0327
+0x0471 0x0328
0x0c45 0x6001
0x0c45 0x6005
0x0c45 0x6007
0x0c45 0x6009
0x0c45 0x600d
+0x0c45 0x6011
+0x0c45 0x6019
0x0c45 0x6024
0x0c45 0x6025
0x0c45 0x6028
0x0c45 0x602d
0x0c45 0x602e
0x0c45 0x6030
+0x0c45 0x603f
0x0c45 0x6080
0x0c45 0x6082
0x0c45 0x6083
0x0c45 0x60bb
0x0c45 0x60bc
0x0c45 0x60be
+0x0c45 0x60c0
+0x0c45 0x60c8
+0x0c45 0x60cc
+0x0c45 0x60ea
+0x0c45 0x60ec
+0x0c45 0x60fa
+0x0c45 0x60fb
+0x0c45 0x60fc
+0x0c45 0x60fe
+0x0c45 0x6130
+0x0c45 0x613a
+0x0c45 0x613b
+0x0c45 0x613c
+0x0c45 0x613e
The list above does not imply that all those devices work with this driver: up
-until now only the ones that mount the following image sensors are supported;
-kernel messages will always tell you whether this is the case:
+until now only the ones that assemble the following image sensors are
+supported; kernel messages will always tell you whether this is the case (see
+"Module loading" paragraph):
Model Manufacturer
----- ------------
HV7131D Hynix Semiconductor, Inc.
MI-0343 Micron Technology, Inc.
OV7630 OmniVision Technologies, Inc.
+OV7660 OmniVision Technologies, Inc.
PAS106B PixArt Imaging, Inc.
PAS202BCA PixArt Imaging, Inc.
PAS202BCB PixArt Imaging, Inc.
TAS5110C1B Taiwan Advanced Sensor Corporation
TAS5130D1B Taiwan Advanced Sensor Corporation
-All the available control settings of each image sensor are supported through
-the V4L2 interface.
+Some of the available control settings of each image sensor are supported
+through the V4L2 interface.
Donations of new models for further testing and support would be much
appreciated. Non-available hardware will not be supported by the author of this
11. Video frame formats [1]
=======================
-The SN9C10x PC Camera Controllers can send images in two possible video
-formats over the USB: either native "Sequential RGB Bayer" or Huffman
-compressed. The latter is used to achieve high frame rates. The current video
-format may be selected or queried from the user application by calling the
-VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2 API
-specifications.
+The SN9C1xx PC Camera Controllers can send images in two possible video
+formats over the USB: either native "Sequential RGB Bayer" or compressed.
+The compression is used to achieve high frame rates. With regard to the
+SN9C101, SN9C102 and SN9C103, the compression is based on the Huffman encoding
+algorithm described below, while the SN9C105 and SN9C120 the compression is
+based on the JPEG standard.
+The current video format may be selected or queried from the user application
+by calling the VIDIOC_S_FMT or VIDIOC_G_FMT ioctl's, as described in the V4L2
+API specifications.
The name "Sequential Bayer" indicates the organization of the red, green and
blue pixels in one video frame. Each pixel is associated with a 8-bit long
... G[n(m-2)] R[n(m-1)]
The above matrix also represents the sequential or progressive read-out mode of
-the (n, m) Bayer color filter array used in many CCD/CMOS image sensors.
+the (n, m) Bayer color filter array used in many CCD or CMOS image sensors.
-One compressed video frame consists of a bitstream that encodes for every R, G,
-or B pixel the difference between the value of the pixel itself and some
-reference pixel value. Pixels are organised in the Bayer pattern and the Bayer
-sub-pixels are tracked individually and alternatingly. For example, in the
-first line values for the B and G1 pixels are alternatingly encoded, while in
-the second line values for the G2 and R pixels are alternatingly encoded.
+The Huffman compressed video frame consists of a bitstream that encodes for
+every R, G, or B pixel the difference between the value of the pixel itself and
+some reference pixel value. Pixels are organised in the Bayer pattern and the
+Bayer sub-pixels are tracked individually and alternatingly. For example, in
+the first line values for the B and G1 pixels are alternatingly encoded, while
+in the second line values for the G2 and R pixels are alternatingly encoded.
The pixel reference value is calculated as follows:
- the 4 top left pixels are encoded in raw uncompressed 8-bit format;
decoding.
The algorithm purely describes the conversion from compressed Bayer code used
-in the SN9C10x chips to uncompressed Bayer. Additional steps are required to
-convert this to a color image (i.e. a color interpolation algorithm).
+in the SN9C101, SN9C102 and SN9C103 chips to uncompressed Bayer. Additional
+steps are required to convert this to a color image (i.e. a color interpolation
+algorithm).
The following Huffman codes have been found:
0: +0 (relative to reference pixel value)
- Philippe Coval for having helped testing the PAS202BCA image sensor;
- Joao Rodrigo Fuzaro, Joao Limirio, Claudio Filho and Caio Begotti for the
donation of a webcam;
+- Dennis Heitmann for the donation of a webcam;
- Jon Hollstrom for the donation of a webcam;
+- Nick McGill for the donation of a webcam;
- Carlos Eduardo Medaglia Dyonisio, who added the support for the PAS202BCB
image sensor;
- Stefano Mozzi, who donated 45 EU;
- Andrew Pearce for the donation of a webcam;
+- John Pullan for the donation of a webcam;
- Bertrik Sikken, who reverse-engineered and documented the Huffman compression
- algorithm used in the SN9C10x controllers and implemented the first decoder;
+ algorithm used in the SN9C101, SN9C102 and SN9C103 controllers and
+ implemented the first decoder;
- Mizuno Takafumi for the donation of a webcam;
- an "anonymous" donator (who didn't want his name to be revealed) for the
donation of a webcam.
+- an anonymous donator for the donation of four webcams.
git.samba.org / sfrench / cifs-2.6.git / blobdiff