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