| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
The pvrusb2 driver |
| 4 |
================== |
| 5 |
|
| 6 |
Author: Mike Isely <[email protected]> |
| 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 <[email protected]> whose web page can be found here: |
| 15 |
http://pvrusb2.dax.nu/ |
| 16 |
|
| 17 |
From there Aurelien Alleaume <[email protected]> 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 |
https://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). |