^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) The pvrusb2 driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Author: Mike Isely <isely@pobox.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) Background
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) is a USB 2.0 hosted TV Tuner. This driver is a work in progress.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Its history started with the reverse-engineering effort by Björn
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Danielsson <pvrusb2@dax.nu> whose web page can be found here:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) http://pvrusb2.dax.nu/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) From there Aurelien Alleaume <slts@free.fr> began an effort to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) create a video4linux compatible driver. I began with Aurelien's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) last known snapshot and evolved the driver to the state it is in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) More information on this driver can be found at:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) https://www.isely.net/pvrusb2.html
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) This driver has a strong separation of layers. They are very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) roughly:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 1. Low level wire-protocol implementation with the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) 2. I2C adaptor implementation and corresponding I2C client drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) implemented elsewhere in V4L.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) 3. High level hardware driver implementation which coordinates all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) activities that ensure correct operation of the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 4. A "context" layer which manages instancing of driver, setup,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) tear-down, arbitration, and interaction with high level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) interfaces appropriately as devices are hotplugged in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) 5. High level interfaces which glue the driver to various published
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Linux APIs (V4L, sysfs, maybe DVB in the future).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The most important shearing layer is between the top 2 layers. A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) lot of work went into the driver to ensure that any kind of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) conceivable API can be laid on top of the core driver. (Yes, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) driver internally leverages V4L to do its work but that really has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) nothing to do with the API published by the driver to the outside
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) world.) The architecture allows for different APIs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) simultaneously access the driver. I have a strong sense of fairness
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) about APIs and also feel that it is a good design principle to keep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) implementation and interface isolated from each other. Thus while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) right now the V4L high level interface is the most complete, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) sysfs high level interface will work equally well for similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) functions, and there's no reason I see right now why it shouldn't be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) possible to produce a DVB high level interface that can sit right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) alongside V4L.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) Building
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) To build these modules essentially amounts to just running "Make",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) but you need the kernel source tree nearby and you will likely also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) want to set a few controlling environment variables first in order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) to link things up with that source tree. Please see the Makefile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) here for comments that explain how to do that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) Source file list / functional overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) (Note: The term "module" used below generally refers to loosely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) defined functional units within the pvrusb2 driver and bears no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) relation to the Linux kernel's concept of a loadable module.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) pvrusb2-audio.[ch] - This is glue logic that resides between this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) driver and the msp3400.ko I2C client driver (which is found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) elsewhere in V4L).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) pvrusb2-context.[ch] - This module implements the context for an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) instance of the driver. Everything else eventually ties back to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) or is otherwise instanced within the data structures implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) here. Hotplugging is ultimately coordinated here. All high level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) interfaces tie into the driver through this module. This module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) helps arbitrate each interface's access to the actual driver core,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) and is designed to allow concurrent access through multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) instances of multiple interfaces (thus you can for example change
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) the tuner's frequency through sysfs while simultaneously streaming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) video through V4L out to an instance of mplayer).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) pvrusb2-debug.h - This header defines a printk() wrapper and a mask
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) of debugging bit definitions for the various kinds of debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) messages that can be enabled within the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) pvrusb2-debugifc.[ch] - This module implements a crude command line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) oriented debug interface into the driver. Aside from being part
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) of the process for implementing manual firmware extraction (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) the pvrusb2 web site mentioned earlier), probably I'm the only one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) who has ever used this. It is mainly a debugging aid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) pvrusb2-eeprom.[ch] - This is glue logic that resides between this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) driver the tveeprom.ko module, which is itself implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) elsewhere in V4L.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) pvrusb2-encoder.[ch] - This module implements all protocol needed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) interact with the Conexant mpeg2 encoder chip within the pvrusb2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) device. It is a crude echo of corresponding logic in ivtv,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) however the design goals (strict isolation) and physical layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) (proxy through USB instead of PCI) are enough different that this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) implementation had to be completely different.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) pvrusb2-hdw-internal.h - This header defines the core data structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) in the driver used to track ALL internal state related to control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) of the hardware. Nobody outside of the core hardware-handling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) modules should have any business using this header. All external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) access to the driver should be through one of the high level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) interfaces (e.g. V4L, sysfs, etc), and in fact even those high
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) level interfaces are restricted to the API defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) pvrusb2-hdw.h and NOT this header.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) pvrusb2-hdw.h - This header defines the full internal API for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) controlling the hardware. High level interfaces (e.g. V4L, sysfs)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) will work through here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) pvrusb2-hdw.c - This module implements all the various bits of logic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) that handle overall control of a specific pvrusb2 device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) (Policy, instantiation, and arbitration of pvrusb2 devices fall
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) within the jurisdiction of pvrusb-context not here).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) tie together and configure various I2C modules as they attach to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) the I2C bus. There are two versions of this file. The "v4l2"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) version is intended to be used in-tree alongside V4L, where we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) implement just the logic that makes sense for a pure V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) environment. The "all" version is intended for use outside of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) V4L, where we might encounter other possibly "challenging" modules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) from ivtv or older kernel snapshots (or even the support modules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) in the standalone snapshot).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) compatible commands to the I2C modules. It is here where state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) changes inside the pvrusb2 driver are translated into V4L1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) commands that are in turn send to the various I2C modules.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) compatible commands to the I2C modules. It is here where state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) changes inside the pvrusb2 driver are translated into V4L2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) commands that are in turn send to the various I2C modules.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) pvrusb2-i2c-core.[ch] - This module provides an implementation of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) kernel-friendly I2C adaptor driver, through which other external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) I2C client drivers (e.g. msp3400, tuner, lirc) may connect and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) operate corresponding chips within the pvrusb2 device. It is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) through here that other V4L modules can reach into this driver to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) operate specific pieces (and those modules are in turn driven by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) glue logic which is coordinated by pvrusb2-hdw, doled out by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) pvrusb2-context, and then ultimately made available to users
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) through one of the high level interfaces).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) pvrusb2-io.[ch] - This module implements a very low level ring of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) transfer buffers, required in order to stream data from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) device. This module is *very* low level. It only operates the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) buffers and makes no attempt to define any policy or mechanism for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) how such buffers might be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) to provide a streaming API usable by a read() system call style of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) I/O. Right now this is the only layer on top of pvrusb2-io.[ch],
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) however the underlying architecture here was intended to allow for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) other styles of I/O to be implemented with additional modules, like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) mmap()'ed buffers or something even more exotic.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) pvrusb2-main.c - This is the top level of the driver. Module level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) and USB core entry points are here. This is our "main".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) pvrusb2-sysfs.[ch] - This is the high level interface which ties the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) pvrusb2 driver into sysfs. Through this interface you can do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) everything with the driver except actually stream data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) pvrusb2-tuner.[ch] - This is glue logic that resides between this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) driver and the tuner.ko I2C client driver (which is found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) elsewhere in V4L).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) pvrusb2-util.h - This header defines some common macros used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) throughout the driver. These macros are not really specific to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) the driver, but they had to go somewhere.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) pvrusb2-v4l2.[ch] - This is the high level interface which ties the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) pvrusb2 driver into video4linux. It is through here that V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) applications can open and operate the driver in the usual V4L
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) ways. Note that **ALL** V4L functionality is published only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) through here and nowhere else.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) pvrusb2-video-\*.[ch] - This is glue logic that resides between this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) driver and the saa711x.ko I2C client driver (which is found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) elsewhere in V4L). Note that saa711x.ko used to be known as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) saa7115.ko in ivtv. There are two versions of this; one is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) selected depending on the particular saa711[5x].ko that is found.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) pvrusb2.h - This header contains compile time tunable parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) (and at the moment the driver has very little that needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) tuned).
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags