]>
Commit | Line | Data |
---|---|---|
88512c91 HV |
1 | The README file from the original package from Micronas appears below. Only |
2 | the part about the firmware redistribution in section 0 is relevant, all | |
3 | other sections are completely obsolete. | |
4 | ||
5 | --------------------------------------------------------------------------- | |
6 | WIS GO7007SB Public Linux Driver | |
7 | --------------------------------------------------------------------------- | |
8 | ||
9 | ||
10 | *** Please see the file RELEASE-NOTES for important last-minute updates *** | |
11 | ||
12 | ||
13 | 0. OVERVIEW AND LICENSING/DISCLAIMER | |
14 | ||
15 | ||
16 | This driver kit contains Linux drivers for the WIS GO7007SB multi-format | |
17 | video encoder. Only kernel version 2.6.x is supported. The video stream | |
18 | is available through the Video4Linux2 API and the audio stream is available | |
19 | through the ALSA API (or the OSS emulation layer of the ALSA system). | |
20 | ||
21 | The files in kernel/ and hotplug/ are licensed under the GNU General Public | |
22 | License Version 2 from the Free Software Foundation. A copy of the license | |
23 | is included in the file COPYING. | |
24 | ||
25 | The example applications in apps/ and C header files in include/ are | |
26 | licensed under a permissive license included in the source files which | |
27 | allows copying, modification and redistribution for any purpose without | |
28 | attribution. | |
29 | ||
30 | The firmware files included in the firmware/ directory may be freely | |
31 | redistributed only in conjunction with this document; but modification, | |
32 | tampering and reverse engineering are prohibited. | |
33 | ||
34 | MICRONAS USA, INC., MAKES NO WARRANTIES TO ANY PERSON OR ENTITY WITH | |
35 | RESPECT TO THE SOFTWARE OR ANY DERIVATIVES THEREOF OR ANY SERVICES OR | |
36 | LICENSES AND DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION | |
37 | WARRANTIES OF MERCHANTABILITY, SUPPORT, AND FITNESS FOR A PARTICULAR | |
38 | PURPOSE AND NON-INFRINGEMENT. | |
39 | ||
40 | ||
41 | 1. SYSTEM REQUIREMENTS | |
42 | ||
43 | ||
44 | This driver requires Linux kernel 2.6. Kernel 2.4 is not supported. Using | |
45 | kernel 2.6.10 or later is recommended, as earlier kernels are known to have | |
46 | unstable USB 2.0 support. | |
47 | ||
48 | A fully built kernel source tree must be available. Typically this will be | |
49 | linked from "/lib/modules/<KERNEL VERSION>/build" for convenience. If this | |
50 | link does not exist, an extra parameter will need to be passed to the | |
51 | `make` command. | |
52 | ||
53 | All vendor-built kernels should already be configured properly. However, | |
54 | for custom-built kernels, the following options need to be enabled in the | |
55 | kernel as built-in or modules: | |
56 | ||
57 | CONFIG_HOTPLUG - Support for hot-pluggable devices | |
58 | CONFIG_MODULES - Enable loadable module support | |
59 | CONFIG_KMOD - Automatic kernel module loading | |
60 | CONFIG_FW_LOADER - Hotplug firmware loading support | |
61 | CONFIG_I2C - I2C support | |
62 | CONFIG_VIDEO_DEV - Video For Linux | |
63 | CONFIG_SOUND - Sound card support | |
64 | CONFIG_SND - Advanced Linux Sound Architecture | |
65 | CONFIG_USB - Support for Host-side USB | |
66 | CONFIG_USB_DEVICEFS - USB device filesystem | |
67 | CONFIG_USB_EHCI_HCD - EHCI HCD (USB 2.0) support | |
68 | ||
69 | Additionally, to use the example application, the following options need to | |
70 | be enabled in the ALSA section: | |
71 | ||
72 | CONFIG_SND_MIXER_OSS - OSS Mixer API | |
73 | CONFIG_SND_PCM_OSS - OSS PCM (digital audio) API | |
74 | ||
75 | The hotplug scripts, along with the fxload utility, must also be installed. | |
76 | These scripts can be obtained from <http://linux-hotplug.sourceforge.net/>. | |
77 | Hotplugging is used for loading firmware into the Cypruss EZ-USB chip using | |
78 | fxload and for loading firmware into the driver using the firmware agent. | |
79 | ||
80 | ||
81 | 2. COMPILING AND INSTALLING THE DRIVER | |
82 | ||
83 | ||
84 | Most users should be able to compile the driver by simply running: | |
85 | ||
86 | $ make | |
87 | ||
88 | in the top-level directory of the driver kit. First the kernel modules | |
89 | will be built, followed by the example applications. | |
90 | ||
91 | If the build system is unable to locate the kernel source tree for the | |
92 | currently-running kernel, or if the module should be built for a kernel | |
93 | other than the currently-running kernel, an additional parameter will need | |
94 | to be passed to make to specify the appropriate kernel source directory: | |
95 | ||
96 | $ make KERNELSRC=/usr/src/linux-2.6.10-custom3 | |
97 | ||
98 | Once the compile completes, the driver and firmware files should be | |
99 | installed by running: | |
100 | ||
101 | $ make install | |
102 | ||
103 | The kernel modules will be placed in "/lib/modules/<KERNEL VERSION>/extra" | |
104 | and the firmware files will be placed in the appropriate hotplug firmware | |
105 | directory, usually /lib/firmware. In addition, USB maps and scripts will | |
106 | be placed in /etc/hotplug/usb to enable fxload to initialize the EZ-USB | |
107 | control chip when the device is connected. | |
108 | ||
109 | ||
110 | 3. PAL/SECAM TUNER CONFIGURATION (TV402U-EU only) | |
111 | ||
112 | ||
113 | The PAL model of the Plextor ConvertX TV402U may require additional | |
114 | configuration to correctly select the appropriate TV frequency band and | |
115 | audio subchannel. | |
116 | ||
117 | Users with a device other than the Plextor ConvertX TV402U-EU should skip | |
118 | this section. | |
119 | ||
120 | The wide variety of PAL TV systems used in Europe requires that additional | |
121 | information about the local TV standards be passed to the driver in order | |
122 | to properly tune TV channels. The two necessary parameters are (a) the PAL | |
123 | TV band, and (b) the audio subchannel format in use. | |
124 | ||
125 | In many cases, the appropriate TV band selection is passed to the driver | |
126 | from applications. However, in some cases, the application only specifies | |
127 | that the driver should use PAL but not the specific information about the | |
128 | appropriate TV band. To work around this issue, the correct TV band may be | |
129 | specified in the "force_band" parameter to the wis-sony-tuner module: | |
130 | ||
131 | TV band force_band | |
132 | ------- ---------- | |
133 | PAL B/G B | |
134 | PAL I I | |
135 | PAL D/K D | |
136 | SECAM L L | |
137 | ||
138 | If the "force_band" parameter is specified, the driver will ignore any TV | |
139 | band specified by applications and will always use the band provided in the | |
140 | module parameter. | |
141 | ||
142 | The other parameter that can be specified is the audio subchannel format. | |
143 | There are several stereo audio carrier systems in use, including NICAM and | |
144 | three varieties of A2. To receive audio broadcast on one of these stereo | |
145 | carriers, the "force_mpx_mode" parameter must be specified to the | |
146 | wis-sony-tuner module. | |
147 | ||
148 | TV band Audio subcarrier force_mpx_mode | |
149 | ------- ---------------- -------------- | |
150 | PAL B/G Mono (default) 1 | |
151 | PAL B/G A2 2 | |
152 | PAL B/G NICAM 3 | |
153 | PAL I Mono (default) 4 | |
154 | PAL I NICAM 5 | |
155 | PAL D/K Mono (default) 6 | |
156 | PAL D/K A2 (1) 7 | |
157 | PAL D/K A2 (2) 8 | |
158 | PAL D/K A2 (3) 9 | |
159 | PAL D/K NICAM 10 | |
160 | SECAM L Mono (default) 11 | |
161 | SECAM L NICAM 12 | |
162 | ||
163 | If the "force_mpx_mode" parameter is not specified, the correct mono-only | |
164 | mode will be chosen based on the TV band. However, the tuner will not | |
165 | receive stereo audio or bilingual broadcasts correctly. | |
166 | ||
167 | To pass the "force_band" or "force_mpx_mode" parameters to the | |
168 | wis-sony-tuner module, the following line must be added to the modprobe | |
169 | configuration file, which varies from one Linux distribution to another. | |
170 | ||
171 | options wis-sony-tuner force_band=B force_mpx_mode=2 | |
172 | ||
173 | The above example would force the tuner to the PAL B/G TV band and receive | |
174 | stereo audio broadcasts on the A2 carrier. | |
175 | ||
176 | To verify that the configuration has been placed in the correct location, | |
177 | execute: | |
178 | ||
179 | $ modprobe -c | grep wis-sony-tuner | |
180 | ||
181 | If the configuration line appears, then modprobe will pass the parameters | |
182 | correctly the next time the wis-sony-tuner module is loaded into the | |
183 | kernel. | |
184 | ||
185 | ||
186 | 4. TESTING THE DRIVER | |
187 | ||
188 | ||
189 | Because few Linux applications are able to correctly capture from | |
190 | Video4Linux2 devices with only compressed formats supported, the new driver | |
191 | should be tested with the "gorecord" application in the apps/ directory. | |
192 | ||
193 | First connect a video source to the device, such as a DVD player or VCR. | |
194 | This will be captured to a file for testing the driver. If an input source | |
195 | is unavailable, a test file can still be captured, but the video will be | |
196 | black and the audio will be silent. | |
197 | ||
198 | This application will auto-detect the V4L2 and ALSA/OSS device names of the | |
199 | hardware and will record video and audio to an AVI file for a specified | |
200 | number of seconds. For example: | |
201 | ||
202 | $ apps/gorecord -duration 60 capture.avi | |
203 | ||
204 | If this application does not successfully record an AVI file, the error | |
205 | messages produced by gorecord and recorded in the system log (usually in | |
206 | /var/log/messages) should provide information to help resolve the problem. | |
207 | ||
208 | Supplying no parameters to gorecord will cause it to probe the available | |
209 | devices and exit. Use the -help flag for usage information. | |
210 | ||
211 | ||
212 | 5. USING THE DRIVER | |
213 | ||
214 | ||
215 | The V4L2 device implemented by the driver provides a standard compressed | |
216 | format API, within the following criteria: | |
217 | ||
218 | * Applications that only support the original Video4Linux1 API will not | |
219 | be able to communicate with this driver at all. | |
220 | ||
221 | * No raw video modes are supported, so applications like xawtv that | |
222 | expect only uncompressed video will not function. | |
223 | ||
224 | * Supported compression formats are: Motion-JPEG, MPEG1, MPEG2 and MPEG4. | |
225 | ||
226 | * MPEG video formats are delivered as Video Elementary Streams only. | |
227 | Program Stream (PS), Transport Stream (TS) and Packetized Elementary | |
228 | Stream (PES) formats are not supported. | |
229 | ||
230 | * Video parameters such as format and input port may not be changed while | |
231 | the encoder is active. | |
232 | ||
233 | * The audio capture device only functions when the video encoder is | |
234 | actively capturing video. Attempts to read from the audio device when | |
235 | the encoder is inactive will result in an I/O error. | |
236 | ||
237 | * The native format of the audio device is 48Khz 2-channel 16-bit | |
238 | little-endian PCM, delivered through the ALSA system. No audio | |
239 | compression is implemented in the hardware. ALSA may convert to other | |
240 | uncompressed formats on the fly. | |
241 | ||
242 | The include/ directory contains a C header file describing non-standard | |
243 | features of the GO7007SB encoder, which are described below: | |
244 | ||
245 | ||
246 | GO7007IOC_S_COMP_PARAMS, GO7007IOC_G_COMP_PARAMS | |
247 | ||
248 | These ioctls are used to negotiate general compression parameters. | |
249 | ||
250 | To query the current parameters, call the GO7007IOC_G_COMP_PARAMS ioctl | |
251 | with a pointer to a struct go7007_comp_params. If the driver is not | |
252 | set to MPEG format, the EINVAL error code will be returned. | |
253 | ||
254 | To change the current parameters, initialize all fields of a struct | |
255 | go7007_comp_params and call the GO7007_IOC_S_COMP_PARAMS ioctl with a | |
256 | pointer to this structure. The driver will return the current | |
257 | parameters with any necessary changes to conform to the limitations of | |
258 | the hardware or current compression mode. Any or all fields can be set | |
259 | to zero to request a reasonable default value. If the driver is not | |
260 | set to MPEG format, the EINVAL error code will be returned. When I/O | |
261 | is in progress, the EBUSY error code will be returned. | |
262 | ||
263 | Fields in struct go7007_comp_params: | |
264 | ||
265 | __u32 The maximum number of frames in each | |
266 | gop_size Group Of Pictures; i.e. the maximum | |
267 | number of frames minus one between | |
268 | each key frame. | |
269 | ||
270 | __u32 The maximum number of sequential | |
271 | max_b_frames bidirectionally-predicted frames. | |
272 | (B-frames are not yet supported.) | |
273 | ||
274 | enum go7007_aspect_ratio The aspect ratio to be encoded in the | |
275 | aspect_ratio meta-data of the compressed format. | |
276 | ||
277 | Choices are: | |
278 | GO7007_ASPECT_RATIO_1_1 | |
279 | GO7007_ASPECT_RATIO_4_3_NTSC | |
280 | GO7007_ASPECT_RATIO_4_3_PAL | |
281 | GO7007_ASPECT_RATIO_16_9_NTSC | |
282 | GO7007_ASPECT_RATIO_16_9_PAL | |
283 | ||
284 | __u32 Bit-wise OR of control flags (below) | |
285 | flags | |
286 | ||
287 | Flags in struct go7007_comp_params: | |
288 | ||
289 | GO7007_COMP_CLOSED_GOP Only produce self-contained GOPs, used | |
290 | to produce streams appropriate for | |
291 | random seeking. | |
292 | ||
293 | GO7007_COMP_OMIT_SEQ_HEADER Omit the stream sequence header. | |
294 | ||
295 | ||
296 | GO7007IOC_S_MPEG_PARAMS, GO7007IOC_G_MPEG_PARAMS | |
297 | ||
298 | These ioctls are used to negotiate MPEG-specific stream parameters when | |
299 | the pixelformat has been set to V4L2_PIX_FMT_MPEG. | |
300 | ||
301 | To query the current parameters, call the GO7007IOC_G_MPEG_PARAMS ioctl | |
302 | with a pointer to a struct go7007_mpeg_params. If the driver is not | |
303 | set to MPEG format, the EINVAL error code will be returned. | |
304 | ||
305 | To change the current parameters, initialize all fields of a struct | |
306 | go7007_mpeg_params and call the GO7007_IOC_S_MPEG_PARAMS ioctl with a | |
307 | pointer to this structure. The driver will return the current | |
308 | parameters with any necessary changes to conform to the limitations of | |
309 | the hardware or selected MPEG mode. Any or all fields can be set to | |
310 | zero to request a reasonable default value. If the driver is not set | |
311 | to MPEG format, the EINVAL error code will be returned. When I/O is in | |
312 | progress, the EBUSY error code will be returned. | |
313 | ||
314 | Fields in struct go7007_mpeg_params: | |
315 | ||
316 | enum go7007_mpeg_video_standard | |
317 | mpeg_video_standard The MPEG video standard in which to | |
318 | compress the video. | |
319 | ||
320 | Choices are: | |
321 | GO7007_MPEG_VIDEO_MPEG1 | |
322 | GO7007_MPEG_VIDEO_MPEG2 | |
323 | GO7007_MPEG_VIDEO_MPEG4 | |
324 | ||
325 | __u32 Bit-wise OR of control flags (below) | |
326 | flags | |
327 | ||
328 | __u32 The profile and level indication to be | |
329 | pali stored in the sequence header. This | |
330 | is only used as an indicator to the | |
331 | decoder, and does not affect the MPEG | |
332 | features used in the video stream. | |
333 | Not valid for MPEG1. | |
334 | ||
335 | Choices for MPEG2 are: | |
336 | GO7007_MPEG2_PROFILE_MAIN_MAIN | |
337 | ||
338 | Choices for MPEG4 are: | |
339 | GO7007_MPEG4_PROFILE_S_L0 | |
340 | GO7007_MPEG4_PROFILE_S_L1 | |
341 | GO7007_MPEG4_PROFILE_S_L2 | |
342 | GO7007_MPEG4_PROFILE_S_L3 | |
343 | GO7007_MPEG4_PROFILE_ARTS_L1 | |
344 | GO7007_MPEG4_PROFILE_ARTS_L2 | |
345 | GO7007_MPEG4_PROFILE_ARTS_L3 | |
346 | GO7007_MPEG4_PROFILE_ARTS_L4 | |
347 | GO7007_MPEG4_PROFILE_AS_L0 | |
348 | GO7007_MPEG4_PROFILE_AS_L1 | |
349 | GO7007_MPEG4_PROFILE_AS_L2 | |
350 | GO7007_MPEG4_PROFILE_AS_L3 | |
351 | GO7007_MPEG4_PROFILE_AS_L4 | |
352 | GO7007_MPEG4_PROFILE_AS_L5 | |
353 | ||
354 | Flags in struct go7007_mpeg_params: | |
355 | ||
356 | GO7007_MPEG_FORCE_DVD_MODE Force all compression parameters and | |
357 | bitrate control settings to comply | |
358 | with DVD MPEG2 stream requirements. | |
359 | This overrides most compression and | |
360 | bitrate settings! | |
361 | ||
362 | GO7007_MPEG_OMIT_GOP_HEADER Omit the GOP header. | |
363 | ||
364 | GO7007_MPEG_REPEAT_SEQHEADER Repeat the MPEG sequence header at | |
365 | the start of each GOP. | |
366 | ||
367 | ||
368 | GO7007IOC_S_BITRATE, GO7007IOC_G_BITRATE | |
369 | ||
370 | These ioctls are used to set and query the target bitrate value for the | |
371 | compressed video stream. The bitrate may be selected by storing the | |
372 | target bits per second in an int and calling GO7007IOC_S_BITRATE with a | |
373 | pointer to the int. The bitrate may be queried by calling | |
374 | GO7007IOC_G_BITRATE with a pointer to an int where the current bitrate | |
375 | will be stored. | |
376 | ||
377 | Note that this is the primary means of controlling the video quality | |
378 | for all compression modes, including V4L2_PIX_FMT_MJPEG. The | |
379 | VIDIOC_S_JPEGCOMP ioctl is not supported. | |
380 | ||
381 | ||
382 | ---------------------------------------------------------------------------- | |
383 | Installing the WIS PCI Voyager Driver | |
384 | --------------------------------------------------------------------------- | |
385 | ||
386 | The WIS PCI Voyager driver requires several patches to the Linux 2.6.11.x | |
387 | kernel source tree before compiling the driver. These patches update the | |
388 | in-kernel SAA7134 driver to the newest development version and patch bugs | |
389 | in the TDA8290/TDA8275 tuner driver. | |
390 | ||
391 | The following patches must be downloaded from Gerd Knorr's website and | |
392 | applied in the order listed: | |
393 | ||
394 | http://dl.bytesex.org/patches/2.6.11-2/i2c-tuner | |
395 | http://dl.bytesex.org/patches/2.6.11-2/i2c-tuner2 | |
396 | http://dl.bytesex.org/patches/2.6.11-2/v4l2-api-mpeg | |
397 | http://dl.bytesex.org/patches/2.6.11-2/saa7134-update | |
398 | ||
399 | The following patches are included with this SDK and can be applied in any | |
400 | order: | |
401 | ||
402 | patches/2.6.11/saa7134-voyager.diff | |
403 | patches/2.6.11/tda8275-newaddr.diff | |
404 | patches/2.6.11/tda8290-ntsc.diff | |
405 | ||
406 | Check to make sure the CONFIG_VIDEO_SAA7134 option is enabled in the kernel | |
407 | configuration, and build and install the kernel. | |
408 | ||
409 | After rebooting into the new kernel, the GO7007 driver can be compiled and | |
410 | installed: | |
411 | ||
412 | $ make SAA7134_BUILD=y | |
413 | $ make install | |
414 | $ modprobe saa7134-go7007 | |
415 | ||
416 | There will be two V4L video devices associated with the PCI Voyager. The | |
417 | first device (most likely /dev/video0) provides access to the raw video | |
418 | capture mode of the SAA7133 device and is used to configure the source | |
419 | video parameters and tune the TV tuner. This device can be used with xawtv | |
420 | or other V4L(2) video software as a standard uncompressed device. | |
421 | ||
422 | The second device (most likely /dev/video1) provides access to the | |
423 | compression functions of the GO7007. It can be tested using the gorecord | |
424 | application in the apps/ directory of this SDK: | |
425 | ||
426 | $ apps/gorecord -vdevice /dev/video1 -noaudio test.avi | |
427 | ||
428 | Currently the frame resolution is fixed at 720x480 (NTSC) or 720x576 (PAL), | |
429 | and the video standard must be specified to both the raw and the compressed | |
430 | video devices (xawtv and gorecord, for example). | |
431 | ||
432 | ||
433 | -------------------------------------------------------------------------- | |
434 | RELEASE NOTES FOR WIS GO7007SB LINUX DRIVER | |
435 | --------------------------------------------------------------------------- | |
436 | ||
437 | Last updated: 5 November 2005 | |
438 | ||
439 | - Release 0.9.7 includes new support for using udev to run fxload. The | |
440 | install script should automatically detect whether the old hotplug | |
441 | scripts or the new udev rules should be used. To force the use of | |
442 | hotplug, run "make install USE_UDEV=n". To force the use of udev, run | |
443 | "make install USE_UDEV=y". | |
444 | ||
445 | - Motion detection is supported but undocumented. Try the `modet` app | |
446 | for a demonstration of how to use the facility. | |
447 | ||
448 | - Using USB2.0 devices such as the TV402U with USB1.1 HCDs or hubs can | |
449 | cause buffer overruns and frame drops, even at low framerates, due to | |
450 | inconsistency in the bitrate control mechanism. | |
451 | ||
452 | - On devices with an SAA7115, including the Plextor ConvertX, video height | |
453 | values of 96, 128, 160, 192, 256, 320, and 384 do not work in NTSC mode. | |
454 | All valid heights up to 512 work correctly in PAL mode. | |
455 | ||
456 | - The WIS Star Trek and PCI Voyager boards have no support yet for audio | |
457 | or the TV tuner. |