Documentation/media/v4l-drivers/pvrusb2.rst

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