Commit | Line | Data |
---|---|---|
1bb6f32a MCC |
1 | The pvrusb2 driver |
2 | ================== | |
d855497e | 3 | |
1bb6f32a | 4 | Author: Mike Isely <isely@pobox.com> |
d855497e | 5 | |
1bb6f32a MCC |
6 | Background |
7 | ---------- | |
d855497e | 8 | |
1bb6f32a MCC |
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/ | |
d855497e | 14 | |
1bb6f32a MCC |
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. | |
d855497e | 19 | |
1bb6f32a MCC |
20 | More information on this driver can be found at: |
21 | http://www.isely.net/pvrusb2.html | |
d855497e | 22 | |
d855497e | 23 | |
1bb6f32a MCC |
24 | This driver has a strong separation of layers. They are very |
25 | roughly: | |
d855497e | 26 | |
1bb6f32a | 27 | 1. Low level wire-protocol implementation with the device. |
d855497e | 28 | |
1bb6f32a MCC |
29 | 2. I2C adaptor implementation and corresponding I2C client drivers |
30 | implemented elsewhere in V4L. | |
d855497e | 31 | |
1bb6f32a MCC |
32 | 3. High level hardware driver implementation which coordinates all |
33 | activities that ensure correct operation of the device. | |
d855497e | 34 | |
1bb6f32a MCC |
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. | |
d855497e | 39 | |
1bb6f32a MCC |
40 | 5. High level interfaces which glue the driver to various published |
41 | Linux APIs (V4L, sysfs, maybe DVB in the future). | |
d855497e | 42 | |
1bb6f32a MCC |
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. | |
d855497e MI |
57 | |
58 | Building | |
1bb6f32a | 59 | -------- |
d855497e | 60 | |
1bb6f32a MCC |
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. | |
d855497e | 66 | |
1bb6f32a MCC |
67 | Source file list / functional overview |
68 | -------------------------------------- | |
d855497e | 69 | |
1bb6f32a MCC |
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.) | |
d855497e | 73 | |
1bb6f32a | 74 | pvrusb2-audio.[ch] - This is glue logic that resides between this |
d855497e MI |
75 | driver and the msp3400.ko I2C client driver (which is found |
76 | elsewhere in V4L). | |
77 | ||
1bb6f32a | 78 | pvrusb2-context.[ch] - This module implements the context for an |
d855497e MI |
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 | ||
1bb6f32a | 89 | pvrusb2-debug.h - This header defines a printk() wrapper and a mask |
d855497e MI |
90 | of debugging bit definitions for the various kinds of debug |
91 | messages that can be enabled within the driver. | |
92 | ||
1bb6f32a | 93 | pvrusb2-debugifc.[ch] - This module implements a crude command line |
d855497e MI |
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 | ||
1bb6f32a | 99 | pvrusb2-eeprom.[ch] - This is glue logic that resides between this |
d855497e MI |
100 | driver the tveeprom.ko module, which is itself implemented |
101 | elsewhere in V4L. | |
102 | ||
1bb6f32a | 103 | pvrusb2-encoder.[ch] - This module implements all protocol needed to |
d855497e MI |
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 | ||
1bb6f32a | 110 | pvrusb2-hdw-internal.h - This header defines the core data structure |
d855497e MI |
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 | ||
1bb6f32a | 119 | pvrusb2-hdw.h - This header defines the full internal API for |
d855497e MI |
120 | controlling the hardware. High level interfaces (e.g. V4L, sysfs) |
121 | will work through here. | |
122 | ||
1bb6f32a | 123 | pvrusb2-hdw.c - This module implements all the various bits of logic |
d855497e MI |
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 | ||
1bb6f32a | 128 | pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to |
d855497e MI |
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 | ||
1bb6f32a | 138 | pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1 |
d855497e MI |
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 | ||
1bb6f32a | 143 | pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2 |
d855497e MI |
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 | ||
1bb6f32a | 148 | pvrusb2-i2c-core.[ch] - This module provides an implementation of a |
d855497e MI |
149 | kernel-friendly I2C adaptor driver, through which other external |
150 | I2C client drivers (e.g. msp3400, tuner, lirc) may connect and | |
670e9f34 | 151 | operate corresponding chips within the pvrusb2 device. It is |
d855497e MI |
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 | ||
1bb6f32a | 158 | pvrusb2-io.[ch] - This module implements a very low level ring of |
d855497e MI |
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 | ||
1bb6f32a | 164 | pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch] |
d855497e MI |
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 | |
25985edc | 168 | other styles of I/O to be implemented with additional modules, like |
d855497e MI |
169 | mmap()'ed buffers or something even more exotic. |
170 | ||
1bb6f32a | 171 | pvrusb2-main.c - This is the top level of the driver. Module level |
d855497e MI |
172 | and USB core entry points are here. This is our "main". |
173 | ||
1bb6f32a | 174 | pvrusb2-sysfs.[ch] - This is the high level interface which ties the |
d855497e MI |
175 | pvrusb2 driver into sysfs. Through this interface you can do |
176 | everything with the driver except actually stream data. | |
177 | ||
1bb6f32a | 178 | pvrusb2-tuner.[ch] - This is glue logic that resides between this |
d855497e MI |
179 | driver and the tuner.ko I2C client driver (which is found |
180 | elsewhere in V4L). | |
181 | ||
1bb6f32a | 182 | pvrusb2-util.h - This header defines some common macros used |
d855497e MI |
183 | throughout the driver. These macros are not really specific to |
184 | the driver, but they had to go somewhere. | |
185 | ||
1bb6f32a | 186 | pvrusb2-v4l2.[ch] - This is the high level interface which ties the |
d855497e MI |
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 | ||
1bb6f32a | 192 | pvrusb2-video-\*.[ch] - This is glue logic that resides between this |
d855497e MI |
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 | ||
1bb6f32a | 198 | pvrusb2.h - This header contains compile time tunable parameters |
d855497e MI |
199 | (and at the moment the driver has very little that needs to be |
200 | tuned). |