1The pvrusb2 driver 2================== 3 4Author: Mike Isely <isely@pobox.com> 5 6Background 7---------- 8 9This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which 10is a USB 2.0 hosted TV Tuner. This driver is a work in progress. 11Its history started with the reverse-engineering effort by Björn 12Danielsson <pvrusb2@dax.nu> whose web page can be found here: 13http://pvrusb2.dax.nu/ 14 15From there Aurelien Alleaume <slts@free.fr> began an effort to 16create a video4linux compatible driver. I began with Aurelien's 17last known snapshot and evolved the driver to the state it is in 18here. 19 20More information on this driver can be found at: 21http://www.isely.net/pvrusb2.html 22 23 24This driver has a strong separation of layers. They are very 25roughly: 26 271. Low level wire-protocol implementation with the device. 28 292. I2C adaptor implementation and corresponding I2C client drivers 30 implemented elsewhere in V4L. 31 323. High level hardware driver implementation which coordinates all 33 activities that ensure correct operation of the device. 34 354. 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. 39 405. High level interfaces which glue the driver to various published 41 Linux APIs (V4L, sysfs, maybe DVB in the future). 42 43The most important shearing layer is between the top 2 layers. A 44lot of work went into the driver to ensure that any kind of 45conceivable API can be laid on top of the core driver. (Yes, the 46driver internally leverages V4L to do its work but that really has 47nothing to do with the API published by the driver to the outside 48world.) The architecture allows for different APIs to 49simultaneously access the driver. I have a strong sense of fairness 50about APIs and also feel that it is a good design principle to keep 51implementation and interface isolated from each other. Thus while 52right now the V4L high level interface is the most complete, the 53sysfs high level interface will work equally well for similar 54functions, and there's no reason I see right now why it shouldn't be 55possible to produce a DVB high level interface that can sit right 56alongside V4L. 57 58Building 59-------- 60 61To build these modules essentially amounts to just running "Make", 62but you need the kernel source tree nearby and you will likely also 63want to set a few controlling environment variables first in order 64to link things up with that source tree. Please see the Makefile 65here for comments that explain how to do that. 66 67Source file list / functional overview 68-------------------------------------- 69 70(Note: The term "module" used below generally refers to loosely 71defined functional units within the pvrusb2 driver and bears no 72relation to the Linux kernel's concept of a loadable module.) 73 74pvrusb2-audio.[ch] - This is glue logic that resides between this 75 driver and the msp3400.ko I2C client driver (which is found 76 elsewhere in V4L). 77 78pvrusb2-context.[ch] - This module implements the context for an 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 89pvrusb2-debug.h - This header defines a printk() wrapper and a mask 90 of debugging bit definitions for the various kinds of debug 91 messages that can be enabled within the driver. 92 93pvrusb2-debugifc.[ch] - This module implements a crude command line 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 99pvrusb2-eeprom.[ch] - This is glue logic that resides between this 100 driver the tveeprom.ko module, which is itself implemented 101 elsewhere in V4L. 102 103pvrusb2-encoder.[ch] - This module implements all protocol needed to 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 110pvrusb2-hdw-internal.h - This header defines the core data structure 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 119pvrusb2-hdw.h - This header defines the full internal API for 120 controlling the hardware. High level interfaces (e.g. V4L, sysfs) 121 will work through here. 122 123pvrusb2-hdw.c - This module implements all the various bits of logic 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 128pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to 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 138pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1 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 143pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2 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 148pvrusb2-i2c-core.[ch] - This module provides an implementation of a 149 kernel-friendly I2C adaptor driver, through which other external 150 I2C client drivers (e.g. msp3400, tuner, lirc) may connect and 151 operate corresponding chips within the pvrusb2 device. It is 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 158pvrusb2-io.[ch] - This module implements a very low level ring of 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 164pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch] 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 168 other styles of I/O to be implemented with additional modules, like 169 mmap()'ed buffers or something even more exotic. 170 171pvrusb2-main.c - This is the top level of the driver. Module level 172 and USB core entry points are here. This is our "main". 173 174pvrusb2-sysfs.[ch] - This is the high level interface which ties the 175 pvrusb2 driver into sysfs. Through this interface you can do 176 everything with the driver except actually stream data. 177 178pvrusb2-tuner.[ch] - This is glue logic that resides between this 179 driver and the tuner.ko I2C client driver (which is found 180 elsewhere in V4L). 181 182pvrusb2-util.h - This header defines some common macros used 183 throughout the driver. These macros are not really specific to 184 the driver, but they had to go somewhere. 185 186pvrusb2-v4l2.[ch] - This is the high level interface which ties the 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 192pvrusb2-video-\*.[ch] - This is glue logic that resides between this 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 198pvrusb2.h - This header contains compile time tunable parameters 199 (and at the moment the driver has very little that needs to be 200 tuned). 201
