0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 The pvrusb2 driver
0004 ==================
0005
0006 Author: Mike Isely <isely@pobox.com>
0007
0008 Background
0009 ----------
0010
0011 This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
0012 is a USB 2.0 hosted TV Tuner. This driver is a work in progress.
0013 Its history started with the reverse-engineering effort by Björn
0014 Danielsson <pvrusb2@dax.nu> whose web page can be found here:
0015 http://pvrusb2.dax.nu/
0016
0017 From there Aurelien Alleaume <slts@free.fr> began an effort to
0018 create a video4linux compatible driver. I began with Aurelien's
0019 last known snapshot and evolved the driver to the state it is in
0020 here.
0021
0022 More information on this driver can be found at:
0023 https://www.isely.net/pvrusb2.html
0024
0025
0026 This driver has a strong separation of layers. They are very
0027 roughly:
0028
0029 1. Low level wire-protocol implementation with the device.
0030
0031 2. I2C adaptor implementation and corresponding I2C client drivers
0032 implemented elsewhere in V4L.
0033
0034 3. High level hardware driver implementation which coordinates all
0035 activities that ensure correct operation of the device.
0036
0037 4. A "context" layer which manages instancing of driver, setup,
0038 tear-down, arbitration, and interaction with high level
0039 interfaces appropriately as devices are hotplugged in the
0040 system.
0041
0042 5. High level interfaces which glue the driver to various published
0043 Linux APIs (V4L, sysfs, maybe DVB in the future).
0044
0045 The most important shearing layer is between the top 2 layers. A
0046 lot of work went into the driver to ensure that any kind of
0047 conceivable API can be laid on top of the core driver. (Yes, the
0048 driver internally leverages V4L to do its work but that really has
0049 nothing to do with the API published by the driver to the outside
0050 world.) The architecture allows for different APIs to
0051 simultaneously access the driver. I have a strong sense of fairness
0052 about APIs and also feel that it is a good design principle to keep
0053 implementation and interface isolated from each other. Thus while
0054 right now the V4L high level interface is the most complete, the
0055 sysfs high level interface will work equally well for similar
0056 functions, and there's no reason I see right now why it shouldn't be
0057 possible to produce a DVB high level interface that can sit right
0058 alongside V4L.
0059
0060 Building
0061 --------
0062
0063 To build these modules essentially amounts to just running "Make",
0064 but you need the kernel source tree nearby and you will likely also
0065 want to set a few controlling environment variables first in order
0066 to link things up with that source tree. Please see the Makefile
0067 here for comments that explain how to do that.
0068
0069 Source file list / functional overview
0070 --------------------------------------
0071
0072 (Note: The term "module" used below generally refers to loosely
0073 defined functional units within the pvrusb2 driver and bears no
0074 relation to the Linux kernel's concept of a loadable module.)
0075
0076 pvrusb2-audio.[ch] - This is glue logic that resides between this
0077 driver and the msp3400.ko I2C client driver (which is found
0078 elsewhere in V4L).
0079
0080 pvrusb2-context.[ch] - This module implements the context for an
0081 instance of the driver. Everything else eventually ties back to
0082 or is otherwise instanced within the data structures implemented
0083 here. Hotplugging is ultimately coordinated here. All high level
0084 interfaces tie into the driver through this module. This module
0085 helps arbitrate each interface's access to the actual driver core,
0086 and is designed to allow concurrent access through multiple
0087 instances of multiple interfaces (thus you can for example change
0088 the tuner's frequency through sysfs while simultaneously streaming
0089 video through V4L out to an instance of mplayer).
0090
0091 pvrusb2-debug.h - This header defines a printk() wrapper and a mask
0092 of debugging bit definitions for the various kinds of debug
0093 messages that can be enabled within the driver.
0094
0095 pvrusb2-debugifc.[ch] - This module implements a crude command line
0096 oriented debug interface into the driver. Aside from being part
0097 of the process for implementing manual firmware extraction (see
0098 the pvrusb2 web site mentioned earlier), probably I'm the only one
0099 who has ever used this. It is mainly a debugging aid.
0100
0101 pvrusb2-eeprom.[ch] - This is glue logic that resides between this
0102 driver the tveeprom.ko module, which is itself implemented
0103 elsewhere in V4L.
0104
0105 pvrusb2-encoder.[ch] - This module implements all protocol needed to
0106 interact with the Conexant mpeg2 encoder chip within the pvrusb2
0107 device. It is a crude echo of corresponding logic in ivtv,
0108 however the design goals (strict isolation) and physical layer
0109 (proxy through USB instead of PCI) are enough different that this
0110 implementation had to be completely different.
0111
0112 pvrusb2-hdw-internal.h - This header defines the core data structure
0113 in the driver used to track ALL internal state related to control
0114 of the hardware. Nobody outside of the core hardware-handling
0115 modules should have any business using this header. All external
0116 access to the driver should be through one of the high level
0117 interfaces (e.g. V4L, sysfs, etc), and in fact even those high
0118 level interfaces are restricted to the API defined in
0119 pvrusb2-hdw.h and NOT this header.
0120
0121 pvrusb2-hdw.h - This header defines the full internal API for
0122 controlling the hardware. High level interfaces (e.g. V4L, sysfs)
0123 will work through here.
0124
0125 pvrusb2-hdw.c - This module implements all the various bits of logic
0126 that handle overall control of a specific pvrusb2 device.
0127 (Policy, instantiation, and arbitration of pvrusb2 devices fall
0128 within the jurisdiction of pvrusb-context not here).
0129
0130 pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to
0131 tie together and configure various I2C modules as they attach to
0132 the I2C bus. There are two versions of this file. The "v4l2"
0133 version is intended to be used in-tree alongside V4L, where we
0134 implement just the logic that makes sense for a pure V4L
0135 environment. The "all" version is intended for use outside of
0136 V4L, where we might encounter other possibly "challenging" modules
0137 from ivtv or older kernel snapshots (or even the support modules
0138 in the standalone snapshot).
0139
0140 pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1
0141 compatible commands to the I2C modules. It is here where state
0142 changes inside the pvrusb2 driver are translated into V4L1
0143 commands that are in turn send to the various I2C modules.
0144
0145 pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2
0146 compatible commands to the I2C modules. It is here where state
0147 changes inside the pvrusb2 driver are translated into V4L2
0148 commands that are in turn send to the various I2C modules.
0149
0150 pvrusb2-i2c-core.[ch] - This module provides an implementation of a
0151 kernel-friendly I2C adaptor driver, through which other external
0152 I2C client drivers (e.g. msp3400, tuner, lirc) may connect and
0153 operate corresponding chips within the pvrusb2 device. It is
0154 through here that other V4L modules can reach into this driver to
0155 operate specific pieces (and those modules are in turn driven by
0156 glue logic which is coordinated by pvrusb2-hdw, doled out by
0157 pvrusb2-context, and then ultimately made available to users
0158 through one of the high level interfaces).
0159
0160 pvrusb2-io.[ch] - This module implements a very low level ring of
0161 transfer buffers, required in order to stream data from the
0162 device. This module is *very* low level. It only operates the
0163 buffers and makes no attempt to define any policy or mechanism for
0164 how such buffers might be used.
0165
0166 pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch]
0167 to provide a streaming API usable by a read() system call style of
0168 I/O. Right now this is the only layer on top of pvrusb2-io.[ch],
0169 however the underlying architecture here was intended to allow for
0170 other styles of I/O to be implemented with additional modules, like
0171 mmap()'ed buffers or something even more exotic.
0172
0173 pvrusb2-main.c - This is the top level of the driver. Module level
0174 and USB core entry points are here. This is our "main".
0175
0176 pvrusb2-sysfs.[ch] - This is the high level interface which ties the
0177 pvrusb2 driver into sysfs. Through this interface you can do
0178 everything with the driver except actually stream data.
0179
0180 pvrusb2-tuner.[ch] - This is glue logic that resides between this
0181 driver and the tuner.ko I2C client driver (which is found
0182 elsewhere in V4L).
0183
0184 pvrusb2-util.h - This header defines some common macros used
0185 throughout the driver. These macros are not really specific to
0186 the driver, but they had to go somewhere.
0187
0188 pvrusb2-v4l2.[ch] - This is the high level interface which ties the
0189 pvrusb2 driver into video4linux. It is through here that V4L
0190 applications can open and operate the driver in the usual V4L
0191 ways. Note that **ALL** V4L functionality is published only
0192 through here and nowhere else.
0193
0194 pvrusb2-video-\*.[ch] - This is glue logic that resides between this
0195 driver and the saa711x.ko I2C client driver (which is found
0196 elsewhere in V4L). Note that saa711x.ko used to be known as
0197 saa7115.ko in ivtv. There are two versions of this; one is
0198 selected depending on the particular saa711[5x].ko that is found.
0199
0200 pvrusb2.h - This header contains compile time tunable parameters
0201 (and at the moment the driver has very little that needs to be
0202 tuned).
