3Mike Isely <>
   5                            pvrusb2 driver
   9  This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
  10  is a USB 2.0 hosted TV Tuner.  This driver is a work in progress.
  11  Its history started with the reverse-engineering effort by Björn
  12  Danielsson <> whose web page can be found here:
  16  From there Aurelien Alleaume <> began an effort to
  17  create a video4linux compatible driver.  I began with Aurelien's
  18  last known snapshot and evolved the driver to the state it is in
  19  here.
  21  More information on this driver can be found at:
  26  This driver has a strong separation of layers.  They are very
  27  roughly:
  29  1a. Low level wire-protocol implementation with the device.
  31  1b. I2C adaptor implementation and corresponding I2C client drivers
  32      implemented elsewhere in V4L.
  34  1c. High level hardware driver implementation which coordinates all
  35      activities that ensure correct operation of the device.
  37  2.  A "context" layer which manages instancing of driver, setup,
  38      tear-down, arbitration, and interaction with high level
  39      interfaces appropriately as devices are hotplugged in the
  40      system.
  42  3.  High level interfaces which glue the driver to various published
  43      Linux APIs (V4L, sysfs, maybe DVB in the future).
  45  The most important shearing layer is between the top 2 layers.  A
  46  lot of work went into the driver to ensure that any kind of
  47  conceivable API can be laid on top of the core driver.  (Yes, the
  48  driver internally leverages V4L to do its work but that really has
  49  nothing to do with the API published by the driver to the outside
  50  world.)  The architecture allows for different APIs to
  51  simultaneously access the driver.  I have a strong sense of fairness
  52  about APIs and also feel that it is a good design principle to keep
  53  implementation and interface isolated from each other.  Thus while
  54  right now the V4L high level interface is the most complete, the
  55  sysfs high level interface will work equally well for similar
  56  functions, and there's no reason I see right now why it shouldn't be
  57  possible to produce a DVB high level interface that can sit right
  58  alongside V4L.
  60  NOTE: Complete documentation on the pvrusb2 driver is contained in
  61  the html files within the doc directory; these are exactly the same
  62  as what is on the web site at the time.  Browse those files
  63  (especially the FAQ) before asking questions.
  68  To build these modules essentially amounts to just running "Make",
  69  but you need the kernel source tree nearby and you will likely also
  70  want to set a few controlling environment variables first in order
  71  to link things up with that source tree.  Please see the Makefile
  72  here for comments that explain how to do that.
  75Source file list / functional overview:
  77  (Note: The term "module" used below generally refers to loosely
  78  defined functional units within the pvrusb2 driver and bears no
  79  relation to the Linux kernel's concept of a loadable module.)
  81  pvrusb2-audio.[ch] - This is glue logic that resides between this
  82    driver and the msp3400.ko I2C client driver (which is found
  83    elsewhere in V4L).
  85  pvrusb2-context.[ch] - This module implements the context for an
  86    instance of the driver.  Everything else eventually ties back to
  87    or is otherwise instanced within the data structures implemented
  88    here.  Hotplugging is ultimately coordinated here.  All high level
  89    interfaces tie into the driver through this module.  This module
  90    helps arbitrate each interface's access to the actual driver core,
  91    and is designed to allow concurrent access through multiple
  92    instances of multiple interfaces (thus you can for example change
  93    the tuner's frequency through sysfs while simultaneously streaming
  94    video through V4L out to an instance of mplayer).
  96  pvrusb2-debug.h - This header defines a printk() wrapper and a mask
  97    of debugging bit definitions for the various kinds of debug
  98    messages that can be enabled within the driver.
 100  pvrusb2-debugifc.[ch] - This module implements a crude command line
 101    oriented debug interface into the driver.  Aside from being part
 102    of the process for implementing manual firmware extraction (see
 103    the pvrusb2 web site mentioned earlier), probably I'm the only one
 104    who has ever used this.  It is mainly a debugging aid.
 106  pvrusb2-eeprom.[ch] - This is glue logic that resides between this
 107    driver the tveeprom.ko module, which is itself implemented
 108    elsewhere in V4L.
 110  pvrusb2-encoder.[ch] - This module implements all protocol needed to
 111    interact with the Conexant mpeg2 encoder chip within the pvrusb2
 112    device.  It is a crude echo of corresponding logic in ivtv,
 113    however the design goals (strict isolation) and physical layer
 114    (proxy through USB instead of PCI) are enough different that this
 115    implementation had to be completely different.
 117  pvrusb2-hdw-internal.h - This header defines the core data structure
 118    in the driver used to track ALL internal state related to control
 119    of the hardware.  Nobody outside of the core hardware-handling
 120    modules should have any business using this header.  All external
 121    access to the driver should be through one of the high level
 122    interfaces (e.g. V4L, sysfs, etc), and in fact even those high
 123    level interfaces are restricted to the API defined in
 124    pvrusb2-hdw.h and NOT this header.
 126  pvrusb2-hdw.h - This header defines the full internal API for
 127    controlling the hardware.  High level interfaces (e.g. V4L, sysfs)
 128    will work through here.
 130  pvrusb2-hdw.c - This module implements all the various bits of logic
 131    that handle overall control of a specific pvrusb2 device.
 132    (Policy, instantiation, and arbitration of pvrusb2 devices fall
 133    within the jurisdiction of pvrusb-context not here).
 135  pvrusb2-i2c-chips-*.c - These modules implement the glue logic to
 136    tie together and configure various I2C modules as they attach to
 137    the I2C bus.  There are two versions of this file.  The "v4l2"
 138    version is intended to be used in-tree alongside V4L, where we
 139    implement just the logic that makes sense for a pure V4L
 140    environment.  The "all" version is intended for use outside of
 141    V4L, where we might encounter other possibly "challenging" modules
 142    from ivtv or older kernel snapshots (or even the support modules
 143    in the standalone snapshot).
 145  pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1
 146    compatible commands to the I2C modules.  It is here where state
 147    changes inside the pvrusb2 driver are translated into V4L1
 148    commands that are in turn send to the various I2C modules.
 150  pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2
 151    compatible commands to the I2C modules.  It is here where state
 152    changes inside the pvrusb2 driver are translated into V4L2
 153    commands that are in turn send to the various I2C modules.
 155  pvrusb2-i2c-core.[ch] - This module provides an implementation of a
 156    kernel-friendly I2C adaptor driver, through which other external
 157    I2C client drivers (e.g. msp3400, tuner, lirc) may connect and
 158    operate corresponding chips within the pvrusb2 device.  It is
 159    through here that other V4L modules can reach into this driver to
 160    operate specific pieces (and those modules are in turn driven by
 161    glue logic which is coordinated by pvrusb2-hdw, doled out by
 162    pvrusb2-context, and then ultimately made available to users
 163    through one of the high level interfaces).
 165  pvrusb2-io.[ch] - This module implements a very low level ring of
 166    transfer buffers, required in order to stream data from the
 167    device.  This module is *very* low level.  It only operates the
 168    buffers and makes no attempt to define any policy or mechanism for
 169    how such buffers might be used.
 171  pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch]
 172    to provide a streaming API usable by a read() system call style of
 173    I/O.  Right now this is the only layer on top of pvrusb2-io.[ch],
 174    however the underlying architecture here was intended to allow for
 175    other styles of I/O to be implemented with additional modules, like
 176    mmap()'ed buffers or something even more exotic.
 178  pvrusb2-main.c - This is the top level of the driver.  Module level
 179    and USB core entry points are here.  This is our "main".
 181  pvrusb2-sysfs.[ch] - This is the high level interface which ties the
 182    pvrusb2 driver into sysfs.  Through this interface you can do
 183    everything with the driver except actually stream data.
 185  pvrusb2-tuner.[ch] - This is glue logic that resides between this
 186    driver and the tuner.ko I2C client driver (which is found
 187    elsewhere in V4L).
 189  pvrusb2-util.h - This header defines some common macros used
 190    throughout the driver.  These macros are not really specific to
 191    the driver, but they had to go somewhere.
 193  pvrusb2-v4l2.[ch] - This is the high level interface which ties the
 194    pvrusb2 driver into video4linux.  It is through here that V4L
 195    applications can open and operate the driver in the usual V4L
 196    ways.  Note that **ALL** V4L functionality is published only
 197    through here and nowhere else.
 199  pvrusb2-video-*.[ch] - This is glue logic that resides between this
 200    driver and the saa711x.ko I2C client driver (which is found
 201    elsewhere in V4L).  Note that saa711x.ko used to be known as
 202    saa7115.ko in ivtv.  There are two versions of this; one is
 203    selected depending on the particular saa711[5x].ko that is found.
 205  pvrusb2.h - This header contains compile time tunable parameters
 206    (and at the moment the driver has very little that needs to be
 207    tuned).
 210  -Mike Isely
 213 kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.