1 2 ZC0301 and ZC0301P Image Processor and Control Chip 3 Driver for Linux 4 =================================================== 5 6 - Documentation - 7 8 9Index 10===== 111. Copyright 122. Disclaimer 133. License 144. Overview and features 155. Module dependencies 166. Module loading 177. Module parameters 188. Supported devices 199. Notes for V4L2 application developers 2010. Contact information 2111. Credits 22 23 241. Copyright 25============ 26Copyright (C) 2006-2007 by Luca Risolia <luca.risolia@studio.unibo.it> 27 28 292. Disclaimer 30============= 31This software is not developed or sponsored by Z-Star Microelectronics Corp. 32Trademarks are property of their respective owner. 33 34 353. License 36========== 37This program is free software; you can redistribute it and/or modify 38it under the terms of the GNU General Public License as published by 39the Free Software Foundation; either version 2 of the License, or 40(at your option) any later version. 41 42This program is distributed in the hope that it will be useful, 43but WITHOUT ANY WARRANTY; without even the implied warranty of 44MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 45GNU General Public License for more details. 46 47You should have received a copy of the GNU General Public License 48along with this program; if not, write to the Free Software 49Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 50 51 524. Overview and features 53======================== 54This driver supports the video interface of the devices mounting the ZC0301 or 55ZC0301P Image Processors and Control Chips. 56 57The driver relies on the Video4Linux2 and USB core modules. It has been 58designed to run properly on SMP systems as well. 59 60The latest version of the ZC0301[P] driver can be found at the following URL: 61http://www.linux-projects.org/ 62 63Some of the features of the driver are: 64 65- full compliance with the Video4Linux2 API (see also "Notes for V4L2 66 application developers" paragraph); 67- available mmap or read/poll methods for video streaming through isochronous 68 data transfers; 69- automatic detection of image sensor; 70- video format is standard JPEG; 71- dynamic driver control thanks to various module parameters (see "Module 72 parameters" paragraph); 73- up to 64 cameras can be handled at the same time; they can be connected and 74 disconnected from the host many times without turning off the computer, if 75 the system supports hotplugging; 76 77 785. Module dependencies 79====================== 80For it to work properly, the driver needs kernel support for Video4Linux and 81USB. 82 83The following options of the kernel configuration file must be enabled and 84corresponding modules must be compiled: 85 86 # Multimedia devices 87 # 88 CONFIG_VIDEO_DEV=m 89 90 # USB support 91 # 92 CONFIG_USB=m 93 94In addition, depending on the hardware being used, the modules below are 95necessary: 96 97 # USB Host Controller Drivers 98 # 99 CONFIG_USB_EHCI_HCD=m 100 CONFIG_USB_UHCI_HCD=m 101 CONFIG_USB_OHCI_HCD=m 102 103The ZC0301 controller also provides a built-in microphone interface. It is 104supported by the USB Audio driver thanks to the ALSA API: 105 106 # Sound 107 # 108 CONFIG_SOUND=y 109 110 # Advanced Linux Sound Architecture 111 # 112 CONFIG_SND=m 113 114 # USB devices 115 # 116 CONFIG_SND_USB_AUDIO=m 117 118And finally: 119 120 # V4L USB devices 121 # 122 CONFIG_USB_ZC0301=m 123 124 1256. Module loading 126================= 127To use the driver, it is necessary to load the "zc0301" module into memory 128after every other module required: "videodev", "v4l2_common", "compat_ioctl32", 129"usbcore" and, depending on the USB host controller you have, "ehci-hcd", 130"uhci-hcd" or "ohci-hcd". 131 132Loading can be done as shown below: 133 134 [root@localhost home]# modprobe zc0301 135 136At this point the devices should be recognized. You can invoke "dmesg" to 137analyze kernel messages and verify that the loading process has gone well: 138 139 [user@localhost home]$ dmesg 140 141 1427. Module parameters 143==================== 144Module parameters are listed below: 145------------------------------------------------------------------------------- 146Name: video_nr 147Type: short array (min = 0, max = 64) 148Syntax: <-1|n[,...]> 149Description: Specify V4L2 minor mode number: 150 -1 = use next available 151 n = use minor number n 152 You can specify up to 64 cameras this way. 153 For example: 154 video_nr=-1,2,-1 would assign minor number 2 to the second 155 registered camera and use auto for the first one and for every 156 other camera. 157Default: -1 158------------------------------------------------------------------------------- 159Name: force_munmap 160Type: bool array (min = 0, max = 64) 161Syntax: <0|1[,...]> 162Description: Force the application to unmap previously mapped buffer memory 163 before calling any VIDIOC_S_CROP or VIDIOC_S_FMT ioctl's. Not 164 all the applications support this feature. This parameter is 165 specific for each detected camera. 166 0 = do not force memory unmapping 167 1 = force memory unmapping (save memory) 168Default: 0 169------------------------------------------------------------------------------- 170Name: frame_timeout 171Type: uint array (min = 0, max = 64) 172Syntax: <n[,...]> 173Description: Timeout for a video frame in seconds. This parameter is 174 specific for each detected camera. This parameter can be 175 changed at runtime thanks to the /sys filesystem interface. 176Default: 2 177------------------------------------------------------------------------------- 178Name: debug 179Type: ushort 180Syntax: <n> 181Description: Debugging information level, from 0 to 3: 182 0 = none (use carefully) 183 1 = critical errors 184 2 = significant informations 185 3 = more verbose messages 186 Level 3 is useful for testing only, when only one device 187 is used at the same time. It also shows some more informations 188 about the hardware being detected. This module parameter can be 189 changed at runtime thanks to the /sys filesystem interface. 190Default: 2 191------------------------------------------------------------------------------- 192 193 1948. Supported devices 195==================== 196None of the names of the companies as well as their products will be mentioned 197here. They have never collaborated with the author, so no advertising. 198 199From the point of view of a driver, what unambiguously identify a device are 200its vendor and product USB identifiers. Below is a list of known identifiers of 201devices mounting the ZC0301 Image Processor and Control Chips: 202 203Vendor ID Product ID 204--------- ---------- 2050x041e 0x4017 2060x041e 0x401c 2070x041e 0x401e 2080x041e 0x401f 2090x041e 0x4022 2100x041e 0x4034 2110x041e 0x4035 2120x041e 0x4036 2130x041e 0x403a 2140x0458 0x7007 2150x0458 0x700c 2160x0458 0x700f 2170x046d 0x08ae 2180x055f 0xd003 2190x055f 0xd004 2200x0ac8 0x0301 2210x0ac8 0x301b 2220x0ac8 0x303b 2230x10fd 0x0128 2240x10fd 0x8050 2250x10fd 0x804e 226 227The list above does not imply that all those devices work with this driver: up 228until now only the ones that mount the following image sensors are supported; 229kernel messages will always tell you whether this is the case: 230 231Model Manufacturer 232----- ------------ 233PAS202BCB PixArt Imaging, Inc. 234PB-0330 Photobit Corporation 235 236 2379. Notes for V4L2 application developers 238======================================== 239This driver follows the V4L2 API specifications. In particular, it enforces two 240rules: 241 242- exactly one I/O method, either "mmap" or "read", is associated with each 243file descriptor. Once it is selected, the application must close and reopen the 244device to switch to the other I/O method; 245 246- although it is not mandatory, previously mapped buffer memory should always 247be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. 248The same number of buffers as before will be allocated again to match the size 249of the new video frames, so you have to map the buffers again before any I/O 250attempts on them. 251 252 25310. Contact information 254======================= 255The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. 256 257GPG/PGP encrypted e-mail's are accepted. The GPG key ID of the author is 258'FCE635A4'; the public 1024-bit key should be available at any keyserver; 259the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. 260 261 26211. Credits 263=========== 264- Informations about the chip internals needed to enable the I2C protocol have 265 been taken from the documentation of the ZC030x Video4Linux1 driver written 266 by Andrew Birkett <andy@nobugs.org>; 267- The initialization values of the ZC0301 controller connected to the PAS202BCB 268 and PB-0330 image sensors have been taken from the SPCA5XX driver maintained 269 by Michel Xhaard <mxhaard@magic.fr>; 270- Stanislav Lechev donated one camera. 271