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