| This is a driver for the WIS GO7007SB multi-format video encoder. |
| |
| Pete Eberlein <pete@sensoray.com> |
| |
| The driver was originally released under the GPL and is currently hosted at: |
| http://nikosapi.org/wiki/index.php/WIS_Go7007_Linux_driver |
| The go7007 firmware can be acquired from the package on the site above. |
| |
| I've modified the driver to support the following Video4Linux2 MPEG |
| controls, with acceptable values: |
| |
| V4L2_CID_MPEG_STREAM_TYPE V4L2_MPEG_STREAM_TYPE_MPEG2_DVD |
| V4L2_MPEG_STREAM_TYPE_MPEG_ELEM |
| V4L2_CID_MPEG_VIDEO_ENCODING V4L2_MPEG_VIDEO_ENCODING_MPEG_1 |
| V4L2_MPEG_VIDEO_ENCODING_MPEG_2 |
| V4L2_MPEG_VIDEO_ENCODING_MPEG_4 |
| V4L2_CID_MPEG_VIDEO_ASPECT V4L2_MPEG_VIDEO_ASPECT_1x1 |
| V4L2_MPEG_VIDEO_ASPECT_4x3 |
| V4L2_MPEG_VIDEO_ASPECT_16x9 |
| V4L2_CID_MPEG_VIDEO_GOP_SIZE integer |
| V4L2_CID_MPEG_VIDEO_BITRATE 64000 .. 10000000 |
| |
| These should be used instead of the non-standard GO7007 ioctls described |
| below. |
| |
| |
| The README files from the orignal package appear below: |
| |
| --------------------------------------------------------------------------- |
| WIS GO7007SB Public Linux Driver |
| --------------------------------------------------------------------------- |
| |
| |
| *** Please see the file RELEASE-NOTES for important last-minute updates *** |
| |
| |
| 0. OVERVIEW AND LICENSING/DISCLAIMER |
| |
| |
| This driver kit contains Linux drivers for the WIS GO7007SB multi-format |
| video encoder. Only kernel version 2.6.x is supported. The video stream |
| is available through the Video4Linux2 API and the audio stream is available |
| through the ALSA API (or the OSS emulation layer of the ALSA system). |
| |
| The files in kernel/ and hotplug/ are licensed under the GNU General Public |
| License Version 2 from the Free Software Foundation. A copy of the license |
| is included in the file COPYING. |
| |
| The example applications in apps/ and C header files in include/ are |
| licensed under a permissive license included in the source files which |
| allows copying, modification and redistribution for any purpose without |
| attribution. |
| |
| The firmware files included in the firmware/ directory may be freely |
| redistributed only in conjunction with this document; but modification, |
| tampering and reverse engineering are prohibited. |
| |
| MICRONAS USA, INC., MAKES NO WARRANTIES TO ANY PERSON OR ENTITY WITH |
| RESPECT TO THE SOFTWARE OR ANY DERIVATIVES THEREOF OR ANY SERVICES OR |
| LICENSES AND DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION |
| WARRANTIES OF MERCHANTABILITY, SUPPORT, AND FITNESS FOR A PARTICULAR |
| PURPOSE AND NON-INFRINGEMENT. |
| |
| |
| 1. SYSTEM REQUIREMENTS |
| |
| |
| This driver requires Linux kernel 2.6. Kernel 2.4 is not supported. Using |
| kernel 2.6.10 or later is recommended, as earlier kernels are known to have |
| unstable USB 2.0 support. |
| |
| A fully built kernel source tree must be available. Typically this will be |
| linked from "/lib/modules/<KERNEL VERSION>/build" for convenience. If this |
| link does not exist, an extra parameter will need to be passed to the |
| `make` command. |
| |
| All vendor-built kernels should already be configured properly. However, |
| for custom-built kernels, the following options need to be enabled in the |
| kernel as built-in or modules: |
| |
| CONFIG_HOTPLUG - Support for hot-pluggable devices |
| CONFIG_MODULES - Enable loadable module support |
| CONFIG_KMOD - Automatic kernel module loading |
| CONFIG_FW_LOADER - Hotplug firmware loading support |
| CONFIG_I2C - I2C support |
| CONFIG_VIDEO_DEV - Video For Linux |
| CONFIG_SOUND - Sound card support |
| CONFIG_SND - Advanced Linux Sound Architecture |
| CONFIG_USB - Support for Host-side USB |
| CONFIG_USB_DEVICEFS - USB device filesystem |
| CONFIG_USB_EHCI_HCD - EHCI HCD (USB 2.0) support |
| |
| Additionally, to use the example application, the following options need to |
| be enabled in the ALSA section: |
| |
| CONFIG_SND_MIXER_OSS - OSS Mixer API |
| CONFIG_SND_PCM_OSS - OSS PCM (digital audio) API |
| |
| The hotplug scripts, along with the fxload utility, must also be installed. |
| These scripts can be obtained from <http://linux-hotplug.sourceforge.net/>. |
| Hotplugging is used for loading firmware into the Cypruss EZ-USB chip using |
| fxload and for loading firmware into the driver using the firmware agent. |
| |
| |
| 2. COMPILING AND INSTALLING THE DRIVER |
| |
| |
| Most users should be able to compile the driver by simply running: |
| |
| $ make |
| |
| in the top-level directory of the driver kit. First the kernel modules |
| will be built, followed by the example applications. |
| |
| If the build system is unable to locate the kernel source tree for the |
| currently-running kernel, or if the module should be built for a kernel |
| other than the currently-running kernel, an additional parameter will need |
| to be passed to make to specify the appropriate kernel source directory: |
| |
| $ make KERNELSRC=/usr/src/linux-2.6.10-custom3 |
| |
| Once the compile completes, the driver and firmware files should be |
| installed by running: |
| |
| $ make install |
| |
| The kernel modules will be placed in "/lib/modules/<KERNEL VERSION>/extra" |
| and the firmware files will be placed in the appropriate hotplug firmware |
| directory, usually /lib/firmware. In addition, USB maps and scripts will |
| be placed in /etc/hotplug/usb to enable fxload to initialize the EZ-USB |
| control chip when the device is connected. |
| |
| |
| 3. PAL/SECAM TUNER CONFIGURATION (TV402U-EU only) |
| |
| |
| The PAL model of the Plextor ConvertX TV402U may require additional |
| configuration to correctly select the appropriate TV frequency band and |
| audio subchannel. |
| |
| Users with a device other than the Plextor ConvertX TV402U-EU should skip |
| this section. |
| |
| The wide variety of PAL TV systems used in Europe requires that additional |
| information about the local TV standards be passed to the driver in order |
| to properly tune TV channels. The two necessary parameters are (a) the PAL |
| TV band, and (b) the audio subchannel format in use. |
| |
| In many cases, the appropriate TV band selection is passed to the driver |
| from applications. However, in some cases, the application only specifies |
| that the driver should use PAL but not the specific information about the |
| appropriate TV band. To work around this issue, the correct TV band may be |
| specified in the "force_band" parameter to the wis-sony-tuner module: |
| |
| TV band force_band |
| ------- ---------- |
| PAL B/G B |
| PAL I I |
| PAL D/K D |
| SECAM L L |
| |
| If the "force_band" parameter is specified, the driver will ignore any TV |
| band specified by applications and will always use the band provided in the |
| module parameter. |
| |
| The other parameter that can be specified is the audio subchannel format. |
| There are several stereo audio carrier systems in use, including NICAM and |
| three varieties of A2. To receive audio broadcast on one of these stereo |
| carriers, the "force_mpx_mode" parameter must be specified to the |
| wis-sony-tuner module. |
| |
| TV band Audio subcarrier force_mpx_mode |
| ------- ---------------- -------------- |
| PAL B/G Mono (default) 1 |
| PAL B/G A2 2 |
| PAL B/G NICAM 3 |
| PAL I Mono (default) 4 |
| PAL I NICAM 5 |
| PAL D/K Mono (default) 6 |
| PAL D/K A2 (1) 7 |
| PAL D/K A2 (2) 8 |
| PAL D/K A2 (3) 9 |
| PAL D/K NICAM 10 |
| SECAM L Mono (default) 11 |
| SECAM L NICAM 12 |
| |
| If the "force_mpx_mode" parameter is not specified, the correct mono-only |
| mode will be chosen based on the TV band. However, the tuner will not |
| receive stereo audio or bilingual broadcasts correctly. |
| |
| To pass the "force_band" or "force_mpx_mode" parameters to the |
| wis-sony-tuner module, the following line must be added to the modprobe |
| configuration file, which varies from one Linux distribution to another. |
| |
| options wis-sony-tuner force_band=B force_mpx_mode=2 |
| |
| The above example would force the tuner to the PAL B/G TV band and receive |
| stereo audio broadcasts on the A2 carrier. |
| |
| To verify that the configuration has been placed in the correct location, |
| execute: |
| |
| $ modprobe -c | grep wis-sony-tuner |
| |
| If the configuration line appears, then modprobe will pass the parameters |
| correctly the next time the wis-sony-tuner module is loaded into the |
| kernel. |
| |
| |
| 4. TESTING THE DRIVER |
| |
| |
| Because few Linux applications are able to correctly capture from |
| Video4Linux2 devices with only compressed formats supported, the new driver |
| should be tested with the "gorecord" application in the apps/ directory. |
| |
| First connect a video source to the device, such as a DVD player or VCR. |
| This will be captured to a file for testing the driver. If an input source |
| is unavailable, a test file can still be captured, but the video will be |
| black and the audio will be silent. |
| |
| This application will auto-detect the V4L2 and ALSA/OSS device names of the |
| hardware and will record video and audio to an AVI file for a specified |
| number of seconds. For example: |
| |
| $ apps/gorecord -duration 60 capture.avi |
| |
| If this application does not successfully record an AVI file, the error |
| messages produced by gorecord and recorded in the system log (usually in |
| /var/log/messages) should provide information to help resolve the problem. |
| |
| Supplying no parameters to gorecord will cause it to probe the available |
| devices and exit. Use the -help flag for usage information. |
| |
| |
| 5. USING THE DRIVER |
| |
| |
| The V4L2 device implemented by the driver provides a standard compressed |
| format API, within the following criteria: |
| |
| * Applications that only support the original Video4Linux1 API will not |
| be able to communicate with this driver at all. |
| |
| * No raw video modes are supported, so applications like xawtv that |
| expect only uncompressed video will not function. |
| |
| * Supported compression formats are: Motion-JPEG, MPEG1, MPEG2 and MPEG4. |
| |
| * MPEG video formats are delivered as Video Elementary Streams only. |
| Program Stream (PS), Transport Stream (TS) and Packetized Elementary |
| Stream (PES) formats are not supported. |
| |
| * Video parameters such as format and input port may not be changed while |
| the encoder is active. |
| |
| * The audio capture device only functions when the video encoder is |
| actively capturing video. Attempts to read from the audio device when |
| the encoder is inactive will result in an I/O error. |
| |
| * The native format of the audio device is 48Khz 2-channel 16-bit |
| little-endian PCM, delivered through the ALSA system. No audio |
| compression is implemented in the hardware. ALSA may convert to other |
| uncompressed formats on the fly. |
| |
| The include/ directory contains a C header file describing non-standard |
| features of the GO7007SB encoder, which are described below: |
| |
| |
| GO7007IOC_S_COMP_PARAMS, GO7007IOC_G_COMP_PARAMS |
| |
| These ioctls are used to negotiate general compression parameters. |
| |
| To query the current parameters, call the GO7007IOC_G_COMP_PARAMS ioctl |
| with a pointer to a struct go7007_comp_params. If the driver is not |
| set to MPEG format, the EINVAL error code will be returned. |
| |
| To change the current parameters, initialize all fields of a struct |
| go7007_comp_params and call the GO7007_IOC_S_COMP_PARAMS ioctl with a |
| pointer to this structure. The driver will return the current |
| parameters with any necessary changes to conform to the limitations of |
| the hardware or current compression mode. Any or all fields can be set |
| to zero to request a reasonable default value. If the driver is not |
| set to MPEG format, the EINVAL error code will be returned. When I/O |
| is in progress, the EBUSY error code will be returned. |
| |
| Fields in struct go7007_comp_params: |
| |
| __u32 The maximum number of frames in each |
| gop_size Group Of Pictures; i.e. the maximum |
| number of frames minus one between |
| each key frame. |
| |
| __u32 The maximum number of sequential |
| max_b_frames bidirectionally-predicted frames. |
| (B-frames are not yet supported.) |
| |
| enum go7007_aspect_ratio The aspect ratio to be encoded in the |
| aspect_ratio meta-data of the compressed format. |
| |
| Choices are: |
| GO7007_ASPECT_RATIO_1_1 |
| GO7007_ASPECT_RATIO_4_3_NTSC |
| GO7007_ASPECT_RATIO_4_3_PAL |
| GO7007_ASPECT_RATIO_16_9_NTSC |
| GO7007_ASPECT_RATIO_16_9_PAL |
| |
| __u32 Bit-wise OR of control flags (below) |
| flags |
| |
| Flags in struct go7007_comp_params: |
| |
| GO7007_COMP_CLOSED_GOP Only produce self-contained GOPs, used |
| to produce streams appropriate for |
| random seeking. |
| |
| GO7007_COMP_OMIT_SEQ_HEADER Omit the stream sequence header. |
| |
| |
| GO7007IOC_S_MPEG_PARAMS, GO7007IOC_G_MPEG_PARAMS |
| |
| These ioctls are used to negotiate MPEG-specific stream parameters when |
| the pixelformat has been set to V4L2_PIX_FMT_MPEG. |
| |
| To query the current parameters, call the GO7007IOC_G_MPEG_PARAMS ioctl |
| with a pointer to a struct go7007_mpeg_params. If the driver is not |
| set to MPEG format, the EINVAL error code will be returned. |
| |
| To change the current parameters, initialize all fields of a struct |
| go7007_mpeg_params and call the GO7007_IOC_S_MPEG_PARAMS ioctl with a |
| pointer to this structure. The driver will return the current |
| parameters with any necessary changes to conform to the limitations of |
| the hardware or selected MPEG mode. Any or all fields can be set to |
| zero to request a reasonable default value. If the driver is not set |
| to MPEG format, the EINVAL error code will be returned. When I/O is in |
| progress, the EBUSY error code will be returned. |
| |
| Fields in struct go7007_mpeg_params: |
| |
| enum go7007_mpeg_video_standard |
| mpeg_video_standard The MPEG video standard in which to |
| compress the video. |
| |
| Choices are: |
| GO7007_MPEG_VIDEO_MPEG1 |
| GO7007_MPEG_VIDEO_MPEG2 |
| GO7007_MPEG_VIDEO_MPEG4 |
| |
| __u32 Bit-wise OR of control flags (below) |
| flags |
| |
| __u32 The profile and level indication to be |
| pali stored in the sequence header. This |
| is only used as an indicator to the |
| decoder, and does not affect the MPEG |
| features used in the video stream. |
| Not valid for MPEG1. |
| |
| Choices for MPEG2 are: |
| GO7007_MPEG2_PROFILE_MAIN_MAIN |
| |
| Choices for MPEG4 are: |
| GO7007_MPEG4_PROFILE_S_L0 |
| GO7007_MPEG4_PROFILE_S_L1 |
| GO7007_MPEG4_PROFILE_S_L2 |
| GO7007_MPEG4_PROFILE_S_L3 |
| GO7007_MPEG4_PROFILE_ARTS_L1 |
| GO7007_MPEG4_PROFILE_ARTS_L2 |
| GO7007_MPEG4_PROFILE_ARTS_L3 |
| GO7007_MPEG4_PROFILE_ARTS_L4 |
| GO7007_MPEG4_PROFILE_AS_L0 |
| GO7007_MPEG4_PROFILE_AS_L1 |
| GO7007_MPEG4_PROFILE_AS_L2 |
| GO7007_MPEG4_PROFILE_AS_L3 |
| GO7007_MPEG4_PROFILE_AS_L4 |
| GO7007_MPEG4_PROFILE_AS_L5 |
| |
| Flags in struct go7007_mpeg_params: |
| |
| GO7007_MPEG_FORCE_DVD_MODE Force all compression parameters and |
| bitrate control settings to comply |
| with DVD MPEG2 stream requirements. |
| This overrides most compression and |
| bitrate settings! |
| |
| GO7007_MPEG_OMIT_GOP_HEADER Omit the GOP header. |
| |
| GO7007_MPEG_REPEAT_SEQHEADER Repeat the MPEG sequence header at |
| the start of each GOP. |
| |
| |
| GO7007IOC_S_BITRATE, GO7007IOC_G_BITRATE |
| |
| These ioctls are used to set and query the target bitrate value for the |
| compressed video stream. The bitrate may be selected by storing the |
| target bits per second in an int and calling GO7007IOC_S_BITRATE with a |
| pointer to the int. The bitrate may be queried by calling |
| GO7007IOC_G_BITRATE with a pointer to an int where the current bitrate |
| will be stored. |
| |
| Note that this is the primary means of controlling the video quality |
| for all compression modes, including V4L2_PIX_FMT_MJPEG. The |
| VIDIOC_S_JPEGCOMP ioctl is not supported. |
| |
| |
| ---------------------------------------------------------------------------- |
| Installing the WIS PCI Voyager Driver |
| --------------------------------------------------------------------------- |
| |
| The WIS PCI Voyager driver requires several patches to the Linux 2.6.11.x |
| kernel source tree before compiling the driver. These patches update the |
| in-kernel SAA7134 driver to the newest development version and patch bugs |
| in the TDA8290/TDA8275 tuner driver. |
| |
| The following patches must be downloaded from Gerd Knorr's website and |
| applied in the order listed: |
| |
| http://dl.bytesex.org/patches/2.6.11-2/i2c-tuner |
| http://dl.bytesex.org/patches/2.6.11-2/i2c-tuner2 |
| http://dl.bytesex.org/patches/2.6.11-2/v4l2-api-mpeg |
| http://dl.bytesex.org/patches/2.6.11-2/saa7134-update |
| |
| The following patches are included with this SDK and can be applied in any |
| order: |
| |
| patches/2.6.11/saa7134-voyager.diff |
| patches/2.6.11/tda8275-newaddr.diff |
| patches/2.6.11/tda8290-ntsc.diff |
| |
| Check to make sure the CONFIG_VIDEO_SAA7134 option is enabled in the kernel |
| configuration, and build and install the kernel. |
| |
| After rebooting into the new kernel, the GO7007 driver can be compiled and |
| installed: |
| |
| $ make SAA7134_BUILD=y |
| $ make install |
| $ modprobe saa7134-go7007 |
| |
| There will be two V4L video devices associated with the PCI Voyager. The |
| first device (most likely /dev/video0) provides access to the raw video |
| capture mode of the SAA7133 device and is used to configure the source |
| video parameters and tune the TV tuner. This device can be used with xawtv |
| or other V4L(2) video software as a standard uncompressed device. |
| |
| The second device (most likely /dev/video1) provides access to the |
| compression functions of the GO7007. It can be tested using the gorecord |
| application in the apps/ directory of this SDK: |
| |
| $ apps/gorecord -vdevice /dev/video1 -noaudio test.avi |
| |
| Currently the frame resolution is fixed at 720x480 (NTSC) or 720x576 (PAL), |
| and the video standard must be specified to both the raw and the compressed |
| video devices (xawtv and gorecord, for example). |
| |
| |
| -------------------------------------------------------------------------- |
| RELEASE NOTES FOR WIS GO7007SB LINUX DRIVER |
| --------------------------------------------------------------------------- |
| |
| Last updated: 5 November 2005 |
| |
| - Release 0.9.7 includes new support for using udev to run fxload. The |
| install script should automatically detect whether the old hotplug |
| scripts or the new udev rules should be used. To force the use of |
| hotplug, run "make install USE_UDEV=n". To force the use of udev, run |
| "make install USE_UDEV=y". |
| |
| - Motion detection is supported but undocumented. Try the `modet` app |
| for a demonstration of how to use the facility. |
| |
| - Using USB2.0 devices such as the TV402U with USB1.1 HCDs or hubs can |
| cause buffer overruns and frame drops, even at low framerates, due to |
| inconsistency in the bitrate control mechanism. |
| |
| - On devices with an SAA7115, including the Plextor ConvertX, video height |
| values of 96, 128, 160, 192, 256, 320, and 384 do not work in NTSC mode. |
| All valid heights up to 512 work correctly in PAL mode. |
| |
| - The WIS Star Trek and PCI Voyager boards have no support yet for audio |
| or the TV tuner. |
