1.. SPDX-License-Identifier: GPL-2.0
2
3The pvrusb2 driver
4==================
5
6Author: Mike Isely <isely@pobox.com>
7
8Background
9----------
10
11This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
12is a USB 2.0 hosted TV Tuner.  This driver is a work in progress.
13Its history started with the reverse-engineering effort by Björn
14Danielsson <pvrusb2@dax.nu> whose web page can be found here:
15http://pvrusb2.dax.nu/
16
17From there Aurelien Alleaume <slts@free.fr> began an effort to
18create a video4linux compatible driver.  I began with Aurelien's
19last known snapshot and evolved the driver to the state it is in
20here.
21
22More information on this driver can be found at:
23http://www.isely.net/pvrusb2.html
24
25
26This driver has a strong separation of layers.  They are very
27roughly:
28
291. Low level wire-protocol implementation with the device.
30
312. I2C adaptor implementation and corresponding I2C client drivers
32   implemented elsewhere in V4L.
33
343. High level hardware driver implementation which coordinates all
35   activities that ensure correct operation of the device.
36
374. 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
425. High level interfaces which glue the driver to various published
43   Linux APIs (V4L, sysfs, maybe DVB in the future).
44
45The most important shearing layer is between the top 2 layers.  A
46lot of work went into the driver to ensure that any kind of
47conceivable API can be laid on top of the core driver.  (Yes, the
48driver internally leverages V4L to do its work but that really has
49nothing to do with the API published by the driver to the outside
50world.)  The architecture allows for different APIs to
51simultaneously access the driver.  I have a strong sense of fairness
52about APIs and also feel that it is a good design principle to keep
53implementation and interface isolated from each other.  Thus while
54right now the V4L high level interface is the most complete, the
55sysfs high level interface will work equally well for similar
56functions, and there's no reason I see right now why it shouldn't be
57possible to produce a DVB high level interface that can sit right
58alongside V4L.
59
60Building
61--------
62
63To build these modules essentially amounts to just running "Make",
64but you need the kernel source tree nearby and you will likely also
65want to set a few controlling environment variables first in order
66to link things up with that source tree.  Please see the Makefile
67here for comments that explain how to do that.
68
69Source file list / functional overview
70--------------------------------------
71
72(Note: The term "module" used below generally refers to loosely
73defined functional units within the pvrusb2 driver and bears no
74relation to the Linux kernel's concept of a loadable module.)
75
76pvrusb2-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
80pvrusb2-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
91pvrusb2-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
95pvrusb2-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
101pvrusb2-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
105pvrusb2-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
112pvrusb2-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
121pvrusb2-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
125pvrusb2-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
130pvrusb2-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
140pvrusb2-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
145pvrusb2-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
150pvrusb2-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
160pvrusb2-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
166pvrusb2-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
173pvrusb2-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
176pvrusb2-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
180pvrusb2-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
184pvrusb2-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
188pvrusb2-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
194pvrusb2-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
200pvrusb2.h - This header contains compile time tunable parameters
201    (and at the moment the driver has very little that needs to be
202    tuned).
203