LICENCE.go7007

   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.