drivers/staging/go7007/go7007.txt

   1 This is a driver for the WIS GO7007SB multi-format video encoder.
   2
   3 Pete Eberlein <pete@sensoray.com>
   4
   5 The driver was orignally 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.
   8
   9 I've modified the driver to support the following Video4Linux2 MPEG
  10 controls, with acceptable values:
  11
  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
  22
  23 These should be used instead of the non-standard GO7007 ioctls described
  24 below.
  25
  26
  27 The 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
  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).
  44
  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.
  48
  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
  52 attribution.
  53
  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.
  57
  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.
  63
  64
  65   1. SYSTEM REQUIREMENTS
  66
  67
  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.
  71
  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
  75 `make` command.
  76
  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:
  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
  93 Additionally, to use the example application, the following options need to
  94 be 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
  99 The hotplug scripts, along with the fxload utility, must also be installed.
 100 These scripts can be obtained from <http://linux-hotplug.sourceforge.net/>.
 101 Hotplugging is used for loading firmware into the Cypruss EZ-USB chip using
 102 fxload and for loading firmware into the driver using the firmware agent.
 103
 104
 105   2. COMPILING AND INSTALLING THE DRIVER
 106
 107
 108 Most users should be able to compile the driver by simply running:
 109
 110         $ make
 111
 112 in the top-level directory of the driver kit.  First the kernel modules
 113 will be built, followed by the example applications.
 114
 115 If the build system is unable to locate the kernel source tree for the
 116 currently-running kernel, or if the module should be built for a kernel
 117 other than the currently-running kernel, an additional parameter will need
 118 to be passed to make to specify the appropriate kernel source directory:
 119
 120         $ make KERNELSRC=/usr/src/linux-2.6.10-custom3
 121
 122 Once the compile completes, the driver and firmware files should be
 123 installed by running:
 124
 125         $ make install
 126
 127 The kernel modules will be placed in "/lib/modules/<KERNEL VERSION>/extra"
 128 and the firmware files will be placed in the appropriate hotplug firmware
 129 directory, usually /lib/firmware.  In addition, USB maps and scripts will
 130 be placed in /etc/hotplug/usb to enable fxload to initialize the EZ-USB
 131 control chip when the device is connected.
 132
 133
 134   3. PAL/SECAM TUNER CONFIGURATION (TV402U-EU only)
 135
 136
 137 The PAL model of the Plextor ConvertX TV402U may require additional
 138 configuration to correctly select the appropriate TV frequency band and
 139 audio subchannel.
 140
 141 Users with a device other than the Plextor ConvertX TV402U-EU should skip
 142 this section.
 143
 144 The wide variety of PAL TV systems used in Europe requires that additional
 145 information about the local TV standards be passed to the driver in order
 146 to properly tune TV channels.  The two necessary parameters are (a) the PAL
 147 TV band, and (b) the audio subchannel format in use.
 148
 149 In many cases, the appropriate TV band selection is passed to the driver
 150 from applications.  However, in some cases, the application only specifies
 151 that the driver should use PAL but not the specific information about the
 152 appropriate TV band.  To work around this issue, the correct TV band may be
 153 specified 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
 162 If the "force_band" parameter is specified, the driver will ignore any TV
 163 band specified by applications and will always use the band provided in the
 164 module parameter.
 165
 166 The other parameter that can be specified is the audio subchannel format.
 167 There are several stereo audio carrier systems in use, including NICAM and
 168 three varieties of A2.  To receive audio broadcast on one of these stereo
 169 carriers, the "force_mpx_mode" parameter must be specified to the
 170 wis-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
 187 If the "force_mpx_mode" parameter is not specified, the correct mono-only
 188 mode will be chosen based on the TV band.  However, the tuner will not
 189 receive stereo audio or bilingual broadcasts correctly.
 190
 191 To pass the "force_band" or "force_mpx_mode" parameters to the
 192 wis-sony-tuner module, the following line must be added to the modprobe
 193 configuration file, which varies from one Linux distribution to another.
 194
 195      options wis-sony-tuner force_band=B force_mpx_mode=2
 196
 197 The above example would force the tuner to the PAL B/G TV band and receive
 198 stereo audio broadcasts on the A2 carrier.
 199
 200 To verify that the configuration has been placed in the correct location,
 201 execute:
 202
 203         $ modprobe -c | grep wis-sony-tuner
 204
 205 If the configuration line appears, then modprobe will pass the parameters
 206 correctly the next time the wis-sony-tuner module is loaded into the
 207 kernel.
 208
 209
 210   4. TESTING THE DRIVER
 211
 212
 213 Because few Linux applications are able to correctly capture from
 214 Video4Linux2 devices with only compressed formats supported, the new driver
 215 should be tested with the "gorecord" application in the apps/ directory.
 216
 217 First connect a video source to the device, such as a DVD player or VCR.
 218 This will be captured to a file for testing the driver.  If an input source
 219 is unavailable, a test file can still be captured, but the video will be
 220 black and the audio will be silent.
 221
 222 This application will auto-detect the V4L2 and ALSA/OSS device names of the
 223 hardware and will record video and audio to an AVI file for a specified
 224 number of seconds.  For example:
 225
 226         $ apps/gorecord -duration 60 capture.avi
 227
 228 If this application does not successfully record an AVI file, the error
 229 messages produced by gorecord and recorded in the system log (usually in
 230 /var/log/messages) should provide information to help resolve the problem.
 231
 232 Supplying no parameters to gorecord will cause it to probe the available
 233 devices and exit.  Use the -help flag for usage information.
 234
 235
 236   5. USING THE DRIVER
 237
 238
 239 The V4L2 device implemented by the driver provides a standard compressed
 240 format 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
 266 The include/ directory contains a C header file describing non-standard
 267 features 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
 410 The WIS PCI Voyager driver requires several patches to the Linux 2.6.11.x
 411 kernel source tree before compiling the driver.  These patches update the
 412 in-kernel SAA7134 driver to the newest development version and patch bugs
 413 in the TDA8290/TDA8275 tuner driver.
 414
 415 The following patches must be downloaded from Gerd Knorr's website and
 416 applied 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
 423 The following patches are included with this SDK and can be applied in any
 424 order:
 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
 430 Check to make sure the CONFIG_VIDEO_SAA7134 option is enabled in the kernel
 431 configuration, and build and install the kernel.
 432
 433 After rebooting into the new kernel, the GO7007 driver can be compiled and
 434 installed:
 435
 436         $ make SAA7134_BUILD=y
 437         $ make install
 438         $ modprobe saa7134-go7007
 439
 440 There will be two V4L video devices associated with the PCI Voyager.  The
 441 first device (most likely /dev/video0) provides access to the raw video
 442 capture mode of the SAA7133 device and is used to configure the source
 443 video parameters and tune the TV tuner.  This device can be used with xawtv
 444 or other V4L(2) video software as a standard uncompressed device.
 445
 446 The second device (most likely /dev/video1) provides access to the
 447 compression functions of the GO7007.  It can be tested using the gorecord
 448 application in the apps/ directory of this SDK:
 449
 450         $ apps/gorecord -vdevice /dev/video1 -noaudio test.avi
 451
 452 Currently the frame resolution is fixed at 720x480 (NTSC) or 720x576 (PAL),
 453 and the video standard must be specified to both the raw and the compressed
 454 video devices (xawtv and gorecord, for example).
 455
 456
 457 --------------------------------------------------------------------------
 458 RELEASE NOTES FOR WIS GO7007SB LINUX DRIVER
 459 ---------------------------------------------------------------------------
 460
 461 Last 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.