203 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3The pvrusb2 driver4==================5 6Author: Mike Isely <isely@pobox.com>7 8Background9----------10 11This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which12is a USB 2.0 hosted TV Tuner. This driver is a work in progress.13Its history started with the reverse-engineering effort by Björn14Danielsson <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 to18create a video4linux compatible driver. I began with Aurelien's19last known snapshot and evolved the driver to the state it is in20here.21 22More information on this driver can be found at:23https://www.isely.net/pvrusb2.html24 25 26This driver has a strong separation of layers. They are very27roughly:28 291. Low level wire-protocol implementation with the device.30 312. I2C adaptor implementation and corresponding I2C client drivers32 implemented elsewhere in V4L.33 343. High level hardware driver implementation which coordinates all35 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 level39 interfaces appropriately as devices are hotplugged in the40 system.41 425. High level interfaces which glue the driver to various published43 Linux APIs (V4L, sysfs, maybe DVB in the future).44 45The most important shearing layer is between the top 2 layers. A46lot of work went into the driver to ensure that any kind of47conceivable API can be laid on top of the core driver. (Yes, the48driver internally leverages V4L to do its work but that really has49nothing to do with the API published by the driver to the outside50world.) The architecture allows for different APIs to51simultaneously access the driver. I have a strong sense of fairness52about APIs and also feel that it is a good design principle to keep53implementation and interface isolated from each other. Thus while54right now the V4L high level interface is the most complete, the55sysfs high level interface will work equally well for similar56functions, and there's no reason I see right now why it shouldn't be57possible to produce a DVB high level interface that can sit right58alongside V4L.59 60Building61--------62 63To build these modules essentially amounts to just running "Make",64but you need the kernel source tree nearby and you will likely also65want to set a few controlling environment variables first in order66to link things up with that source tree. Please see the Makefile67here for comments that explain how to do that.68 69Source file list / functional overview70--------------------------------------71 72(Note: The term "module" used below generally refers to loosely73defined functional units within the pvrusb2 driver and bears no74relation to the Linux kernel's concept of a loadable module.)75 76pvrusb2-audio.[ch] - This is glue logic that resides between this77 driver and the msp3400.ko I2C client driver (which is found78 elsewhere in V4L).79 80pvrusb2-context.[ch] - This module implements the context for an81 instance of the driver. Everything else eventually ties back to82 or is otherwise instanced within the data structures implemented83 here. Hotplugging is ultimately coordinated here. All high level84 interfaces tie into the driver through this module. This module85 helps arbitrate each interface's access to the actual driver core,86 and is designed to allow concurrent access through multiple87 instances of multiple interfaces (thus you can for example change88 the tuner's frequency through sysfs while simultaneously streaming89 video through V4L out to an instance of mplayer).90 91pvrusb2-debug.h - This header defines a printk() wrapper and a mask92 of debugging bit definitions for the various kinds of debug93 messages that can be enabled within the driver.94 95pvrusb2-debugifc.[ch] - This module implements a crude command line96 oriented debug interface into the driver. Aside from being part97 of the process for implementing manual firmware extraction (see98 the pvrusb2 web site mentioned earlier), probably I'm the only one99 who has ever used this. It is mainly a debugging aid.100 101pvrusb2-eeprom.[ch] - This is glue logic that resides between this102 driver the tveeprom.ko module, which is itself implemented103 elsewhere in V4L.104 105pvrusb2-encoder.[ch] - This module implements all protocol needed to106 interact with the Conexant mpeg2 encoder chip within the pvrusb2107 device. It is a crude echo of corresponding logic in ivtv,108 however the design goals (strict isolation) and physical layer109 (proxy through USB instead of PCI) are enough different that this110 implementation had to be completely different.111 112pvrusb2-hdw-internal.h - This header defines the core data structure113 in the driver used to track ALL internal state related to control114 of the hardware. Nobody outside of the core hardware-handling115 modules should have any business using this header. All external116 access to the driver should be through one of the high level117 interfaces (e.g. V4L, sysfs, etc), and in fact even those high118 level interfaces are restricted to the API defined in119 pvrusb2-hdw.h and NOT this header.120 121pvrusb2-hdw.h - This header defines the full internal API for122 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 logic126 that handle overall control of a specific pvrusb2 device.127 (Policy, instantiation, and arbitration of pvrusb2 devices fall128 within the jurisdiction of pvrusb-context not here).129 130pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to131 tie together and configure various I2C modules as they attach to132 the I2C bus. There are two versions of this file. The "v4l2"133 version is intended to be used in-tree alongside V4L, where we134 implement just the logic that makes sense for a pure V4L135 environment. The "all" version is intended for use outside of136 V4L, where we might encounter other possibly "challenging" modules137 from ivtv or older kernel snapshots (or even the support modules138 in the standalone snapshot).139 140pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1141 compatible commands to the I2C modules. It is here where state142 changes inside the pvrusb2 driver are translated into V4L1143 commands that are in turn send to the various I2C modules.144 145pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2146 compatible commands to the I2C modules. It is here where state147 changes inside the pvrusb2 driver are translated into V4L2148 commands that are in turn send to the various I2C modules.149 150pvrusb2-i2c-core.[ch] - This module provides an implementation of a151 kernel-friendly I2C adaptor driver, through which other external152 I2C client drivers (e.g. msp3400, tuner, lirc) may connect and153 operate corresponding chips within the pvrusb2 device. It is154 through here that other V4L modules can reach into this driver to155 operate specific pieces (and those modules are in turn driven by156 glue logic which is coordinated by pvrusb2-hdw, doled out by157 pvrusb2-context, and then ultimately made available to users158 through one of the high level interfaces).159 160pvrusb2-io.[ch] - This module implements a very low level ring of161 transfer buffers, required in order to stream data from the162 device. This module is *very* low level. It only operates the163 buffers and makes no attempt to define any policy or mechanism for164 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 of168 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 for170 other styles of I/O to be implemented with additional modules, like171 mmap()'ed buffers or something even more exotic.172 173pvrusb2-main.c - This is the top level of the driver. Module level174 and USB core entry points are here. This is our "main".175 176pvrusb2-sysfs.[ch] - This is the high level interface which ties the177 pvrusb2 driver into sysfs. Through this interface you can do178 everything with the driver except actually stream data.179 180pvrusb2-tuner.[ch] - This is glue logic that resides between this181 driver and the tuner.ko I2C client driver (which is found182 elsewhere in V4L).183 184pvrusb2-util.h - This header defines some common macros used185 throughout the driver. These macros are not really specific to186 the driver, but they had to go somewhere.187 188pvrusb2-v4l2.[ch] - This is the high level interface which ties the189 pvrusb2 driver into video4linux. It is through here that V4L190 applications can open and operate the driver in the usual V4L191 ways. Note that **ALL** V4L functionality is published only192 through here and nowhere else.193 194pvrusb2-video-\*.[ch] - This is glue logic that resides between this195 driver and the saa711x.ko I2C client driver (which is found196 elsewhere in V4L). Note that saa711x.ko used to be known as197 saa7115.ko in ivtv. There are two versions of this; one is198 selected depending on the particular saa711[5x].ko that is found.199 200pvrusb2.h - This header contains compile time tunable parameters201 (and at the moment the driver has very little that needs to be202 tuned).203