]>
Commit | Line | Data |
---|---|---|
60f78052 | 1 | |
0230185d LR |
2 | ZC0301 and ZC0301P Image Processor and Control Chip |
3 | Driver for Linux | |
4 | =================================================== | |
60f78052 | 5 | |
0230185d | 6 | - Documentation - |
60f78052 LR |
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. Supported devices | |
19 | 9. Notes for V4L2 application developers | |
20 | 10. Contact information | |
21 | 11. Credits | |
22 | ||
23 | ||
24 | 1. Copyright | |
25 | ============ | |
7e3a0660 | 26 | Copyright (C) 2006-2007 by Luca Risolia <luca.risolia@studio.unibo.it> |
60f78052 LR |
27 | |
28 | ||
29 | 2. Disclaimer | |
30 | ============= | |
31 | This software is not developed or sponsored by Z-Star Microelectronics Corp. | |
32 | Trademarks are property of their respective owner. | |
33 | ||
34 | ||
35 | 3. License | |
36 | ========== | |
37 | This program is free software; you can redistribute it and/or modify | |
38 | it under the terms of the GNU General Public License as published by | |
39 | the Free Software Foundation; either version 2 of the License, or | |
40 | (at your option) any later version. | |
41 | ||
42 | This program is distributed in the hope that it will be useful, | |
43 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
44 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
45 | GNU General Public License for more details. | |
46 | ||
47 | You should have received a copy of the GNU General Public License | |
48 | along with this program; if not, write to the Free Software | |
49 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. | |
50 | ||
51 | ||
52 | 4. Overview and features | |
53 | ======================== | |
0230185d LR |
54 | This driver supports the video interface of the devices mounting the ZC0301 or |
55 | ZC0301P Image Processors and Control Chips. | |
60f78052 LR |
56 | |
57 | The driver relies on the Video4Linux2 and USB core modules. It has been | |
58 | designed to run properly on SMP systems as well. | |
59 | ||
0230185d | 60 | The latest version of the ZC0301[P] driver can be found at the following URL: |
60f78052 LR |
61 | http://www.linux-projects.org/ |
62 | ||
63 | Some 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; | |
9e47a52b | 70 | - video format is standard JPEG; |
60f78052 LR |
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 | ||
78 | 5. Module dependencies | |
79 | ====================== | |
80 | For it to work properly, the driver needs kernel support for Video4Linux and | |
81 | USB. | |
82 | ||
83 | The following options of the kernel configuration file must be enabled and | |
84 | corresponding modules must be compiled: | |
85 | ||
86 | # Multimedia devices | |
87 | # | |
88 | CONFIG_VIDEO_DEV=m | |
89 | ||
90 | # USB support | |
91 | # | |
92 | CONFIG_USB=m | |
93 | ||
94 | In addition, depending on the hardware being used, the modules below are | |
95 | necessary: | |
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 | ||
103 | The ZC0301 controller also provides a built-in microphone interface. It is | |
104 | supported 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 | ||
118 | And finally: | |
119 | ||
0230185d | 120 | # V4L USB devices |
60f78052 LR |
121 | # |
122 | CONFIG_USB_ZC0301=m | |
123 | ||
124 | ||
125 | 6. Module loading | |
126 | ================= | |
127 | To use the driver, it is necessary to load the "zc0301" module into memory | |
7e3a0660 LR |
128 | after 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". | |
60f78052 LR |
131 | |
132 | Loading can be done as shown below: | |
133 | ||
134 | [root@localhost home]# modprobe zc0301 | |
135 | ||
136 | At this point the devices should be recognized. You can invoke "dmesg" to | |
137 | analyze kernel messages and verify that the loading process has gone well: | |
138 | ||
139 | [user@localhost home]$ dmesg | |
140 | ||
141 | ||
142 | 7. Module parameters | |
143 | ==================== | |
144 | Module parameters are listed below: | |
145 | ------------------------------------------------------------------------------- | |
146 | Name: video_nr | |
147 | Type: short array (min = 0, max = 64) | |
148 | Syntax: <-1|n[,...]> | |
149 | Description: Specify V4L2 minor mode number: | |
0230185d LR |
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. | |
60f78052 LR |
157 | Default: -1 |
158 | ------------------------------------------------------------------------------- | |
159 | Name: force_munmap | |
160 | Type: bool array (min = 0, max = 64) | |
161 | Syntax: <0|1[,...]> | |
162 | Description: Force the application to unmap previously mapped buffer memory | |
0230185d LR |
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) | |
60f78052 LR |
168 | Default: 0 |
169 | ------------------------------------------------------------------------------- | |
a8474239 LR |
170 | Name: frame_timeout |
171 | Type: uint array (min = 0, max = 64) | |
172 | Syntax: <n[,...]> | |
173 | Description: Timeout for a video frame in seconds. This parameter is | |
0230185d LR |
174 | specific for each detected camera. This parameter can be |
175 | changed at runtime thanks to the /sys filesystem interface. | |
a8474239 LR |
176 | Default: 2 |
177 | ------------------------------------------------------------------------------- | |
60f78052 LR |
178 | Name: debug |
179 | Type: ushort | |
180 | Syntax: <n> | |
181 | Description: Debugging information level, from 0 to 3: | |
0230185d LR |
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. | |
60f78052 LR |
190 | Default: 2 |
191 | ------------------------------------------------------------------------------- | |
192 | ||
193 | ||
194 | 8. Supported devices | |
195 | ==================== | |
196 | None of the names of the companies as well as their products will be mentioned | |
197 | here. They have never collaborated with the author, so no advertising. | |
198 | ||
199 | From the point of view of a driver, what unambiguously identify a device are | |
200 | its vendor and product USB identifiers. Below is a list of known identifiers of | |
201 | devices mounting the ZC0301 Image Processor and Control Chips: | |
202 | ||
203 | Vendor ID Product ID | |
204 | --------- ---------- | |
6e0755a4 LR |
205 | 0x041e 0x4017 |
206 | 0x041e 0x401c | |
207 | 0x041e 0x401e | |
0230185d LR |
208 | 0x041e 0x401f |
209 | 0x041e 0x4022 | |
6e0755a4 LR |
210 | 0x041e 0x4034 |
211 | 0x041e 0x4035 | |
0230185d LR |
212 | 0x041e 0x4036 |
213 | 0x041e 0x403a | |
214 | 0x0458 0x7007 | |
7e3a0660 | 215 | 0x0458 0x700c |
0230185d LR |
216 | 0x0458 0x700f |
217 | 0x046d 0x08ae | |
218 | 0x055f 0xd003 | |
219 | 0x055f 0xd004 | |
a8474239 | 220 | 0x0ac8 0x0301 |
0230185d LR |
221 | 0x0ac8 0x301b |
222 | 0x0ac8 0x303b | |
223 | 0x10fd 0x0128 | |
6e0755a4 | 224 | 0x10fd 0x8050 |
0230185d | 225 | 0x10fd 0x804e |
60f78052 | 226 | |
a8474239 LR |
227 | The list above does not imply that all those devices work with this driver: up |
228 | until now only the ones that mount the following image sensors are supported; | |
229 | kernel messages will always tell you whether this is the case: | |
60f78052 LR |
230 | |
231 | Model Manufacturer | |
232 | ----- ------------ | |
233 | PAS202BCB PixArt Imaging, Inc. | |
0230185d | 234 | PB-0330 Photobit Corporation |
60f78052 | 235 | |
60f78052 LR |
236 | |
237 | 9. Notes for V4L2 application developers | |
238 | ======================================== | |
239 | This driver follows the V4L2 API specifications. In particular, it enforces two | |
240 | rules: | |
241 | ||
242 | - exactly one I/O method, either "mmap" or "read", is associated with each | |
243 | file descriptor. Once it is selected, the application must close and reopen the | |
244 | device to switch to the other I/O method; | |
245 | ||
246 | - although it is not mandatory, previously mapped buffer memory should always | |
247 | be unmapped before calling any "VIDIOC_S_CROP" or "VIDIOC_S_FMT" ioctl's. | |
248 | The same number of buffers as before will be allocated again to match the size | |
249 | of the new video frames, so you have to map the buffers again before any I/O | |
250 | attempts on them. | |
251 | ||
60f78052 LR |
252 | |
253 | 10. Contact information | |
254 | ======================= | |
255 | The author may be contacted by e-mail at <luca.risolia@studio.unibo.it>. | |
256 | ||
257 | GPG/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; | |
259 | the fingerprint is: '88E8 F32F 7244 68BA 3958 5D40 99DA 5D2A FCE6 35A4'. | |
260 | ||
261 | ||
262 | 11. Credits | |
263 | =========== | |
9e47a52b LR |
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>; | |
a8474239 | 267 | - The initialization values of the ZC0301 controller connected to the PAS202BCB |
0230185d LR |
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. |