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