Documentation/media/v4l-drivers/pvrusb2.rst

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