diff options
Diffstat (limited to 'Documentation/video4linux/sn9c102.txt')
| -rw-r--r-- | Documentation/video4linux/sn9c102.txt | 246 |
1 files changed, 152 insertions, 94 deletions
diff --git a/Documentation/video4linux/sn9c102.txt b/Documentation/video4linux/sn9c102.txt index 8cda472db36..2913da3d087 100644 --- a/Documentation/video4linux/sn9c102.txt +++ b/Documentation/video4linux/sn9c102.txt @@ -1,5 +1,5 @@ - SN9C10x PC Camera Controllers + SN9C1xx PC Camera Controllers Driver for Linux ============================= @@ -53,20 +53,14 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 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, -because 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: @@ -85,11 +79,11 @@ 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 instance, 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); @@ -130,8 +124,8 @@ necessary: 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 # @@ -155,18 +149,27 @@ And finally: 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 ==================== @@ -198,10 +201,11 @@ Default: 0 ------------------------------------------------------------------------------- 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 @@ -223,20 +227,21 @@ Default: 2 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 @@ -259,61 +264,84 @@ Now let's set the green gain's register of the SN9C101 or SN9C102 chips to 2: [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 @@ -323,15 +351,19 @@ here. They have never collaborated with the author, so no advertising. 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 @@ -342,6 +374,7 @@ Vendor ID Product ID 0x0c45 0x602d 0x0c45 0x602e 0x0c45 0x6030 +0x0c45 0x603f 0x0c45 0x6080 0x0c45 0x6082 0x0c45 0x6083 @@ -368,24 +401,40 @@ Vendor ID Product ID 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 @@ -429,12 +478,15 @@ supplied by this driver). 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 @@ -447,14 +499,14 @@ G[m] R[m+1] G[m+2] R[m+2] ... G[2m-2] R[2m-1] ... 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; @@ -470,8 +522,9 @@ The pixel reference value is calculated as follows: 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) @@ -506,13 +559,18 @@ order): - 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. |