The pvrusb2 driver

배경과 개발 이력

Mike Isely가 작성한 이 `GPL-2.0` 문서는 USB 2.0 TV tuner인 Hauppauge WinTV PVR USB 2.0용 `pvrusb2` driver를 설명합니다. 문서 작성 시점에 driver는 계속 개발 중인 작업입니다.

역사는 Björn Danielsson의 reverse-engineering 작업에서 시작됐으며 당시 자료는 `http://pvrusb2.dax.nu/`에 있었습니다. 이후 Aurelien Alleaume가 Video4Linux 호환 driver 개발을 시작했고, 저자는 그의 마지막 snapshot을 기반으로 현재 상태까지 발전시켰습니다.

Driver에 관한 추가 정보는 `https://www.isely.net/pvrusb2.html`에서 확인할 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

The pvrusb2 driver
==================

Author: Mike Isely <[email protected]>

Background
----------

This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which
is a USB 2.0 hosted TV Tuner.  This driver is a work in progress.
Its history started with the reverse-engineering effort by Björn
Danielsson <[email protected]> whose web page can be found here:
http://pvrusb2.dax.nu/

From there Aurelien Alleaume <[email protected]> began an effort to
create a video4linux compatible driver.  I began with Aurelien's
last known snapshot and evolved the driver to the state it is in
here.

More information on this driver can be found at:
https://www.isely.net/pvrusb2.html

강하게 분리된 5개 계층

이 driver는 계층을 강하게 분리합니다. 가장 아래에는 device wire protocol이 있고, 그 위에 I2C adaptor와 V4L의 외부 I2C client driver, 전체 hardware 동작을 조정하는 core, hotplug와 instance 및 arbitration을 담당하는 context, Linux API에 연결하는 high-level interface가 놓입니다.

가장 중요한 분리 경계는 core/context 쪽과 high-level interface 사이입니다. Core 위에 어떤 API도 얹을 수 있도록 설계했으며, driver 내부가 V4L을 사용한다는 사실과 외부에 공개하는 API는 별개입니다.

Architecture는 서로 다른 API가 driver에 동시에 접근하도록 허용합니다. 현재 V4L interface가 가장 완성돼 있지만 sysfs interface도 비슷한 기능을 동등하게 수행하며, 향후 DVB interface 역시 V4L과 나란히 공존할 수 있습니다. 이는 implementation과 interface를 격리하고 API 사이의 공정성을 유지하려는 설계 원칙입니다.

This driver has a strong separation of layers.  They are very
roughly:

1. Low level wire-protocol implementation with the device.

2. I2C adaptor implementation and corresponding I2C client drivers
   implemented elsewhere in V4L.

3. High level hardware driver implementation which coordinates all
   activities that ensure correct operation of the device.

4. A "context" layer which manages instancing of driver, setup,
   tear-down, arbitration, and interaction with high level
   interfaces appropriately as devices are hotplugged in the
   system.

5. High level interfaces which glue the driver to various published
   Linux APIs (V4L, sysfs, maybe DVB in the future).

The most important shearing layer is between the top 2 layers.  A
lot of work went into the driver to ensure that any kind of
conceivable API can be laid on top of the core driver.  (Yes, the
driver internally leverages V4L to do its work but that really has
nothing to do with the API published by the driver to the outside
world.)  The architecture allows for different APIs to
simultaneously access the driver.  I have a strong sense of fairness
about APIs and also feel that it is a good design principle to keep
implementation and interface isolated from each other.  Thus while
right now the V4L high level interface is the most complete, the
sysfs high level interface will work equally well for similar
functions, and there's no reason I see right now why it shouldn't be
possible to produce a DVB high level interface that can sit right
alongside V4L.

Module build

이 module들을 build하는 작업은 본질적으로 `Make`를 실행하는 것입니다. 다만 인접한 kernel source tree가 필요하고, 해당 source tree와 연결하기 위해 먼저 몇 가지 제어용 environment variable을 설정해야 할 수 있습니다. 구체적인 방법은 Makefile의 설명 comment를 참고합니다.

Building
--------

To build these modules essentially amounts to just running "Make",
but you need the kernel source tree nearby and you will likely also
want to set a few controlling environment variables first in order
to link things up with that source tree.  Please see the Makefile
here for comments that explain how to do that.

Source 목록: audio와 context

아래에서 사용하는 `module`이라는 말은 대체로 pvrusb2 driver 내부의 느슨한 기능 단위를 뜻하며, Linux kernel의 loadable module 개념과는 관계가 없습니다.

`pvrusb2-audio.[ch]`는 driver와 V4L의 다른 위치에 구현된 `msp3400.ko` I2C client driver 사이의 glue logic입니다.

`pvrusb2-context.[ch]`는 driver instance의 context를 구현합니다. 다른 모든 구성은 결국 이 data structure에 연결되거나 그 안에서 instance화됩니다. Hotplug coordination, 모든 high-level interface의 진입, interface별 core 접근 arbitration을 담당합니다.

Context 설계는 여러 interface instance의 동시 접근을 허용합니다. 예를 들어 sysfs로 tuner frequency를 바꾸는 동시에 V4L을 통해 mplayer로 video를 stream할 수 있습니다.

Source file list / functional overview
--------------------------------------

(Note: The term "module" used below generally refers to loosely
defined functional units within the pvrusb2 driver and bears no
relation to the Linux kernel's concept of a loadable module.)

pvrusb2-audio.[ch] - This is glue logic that resides between this
    driver and the msp3400.ko I2C client driver (which is found
    elsewhere in V4L).

pvrusb2-context.[ch] - This module implements the context for an
    instance of the driver.  Everything else eventually ties back to
    or is otherwise instanced within the data structures implemented
    here.  Hotplugging is ultimately coordinated here.  All high level
    interfaces tie into the driver through this module.  This module
    helps arbitrate each interface's access to the actual driver core,
    and is designed to allow concurrent access through multiple
    instances of multiple interfaces (thus you can for example change
    the tuner's frequency through sysfs while simultaneously streaming
    video through V4L out to an instance of mplayer).

Source 목록: debug, EEPROM, encoder

`pvrusb2-debug.h`는 `printk()` wrapper와 driver에서 선택적으로 켤 수 있는 여러 debug message 종류의 bit mask 정의를 제공합니다.

`pvrusb2-debugifc.[ch]`는 간단한 command-line 지향 debug interface를 구현합니다. 수동 firmware extraction 과정의 일부이기도 하지만, 주 용도는 개발자의 debugging 보조입니다.

`pvrusb2-eeprom.[ch]`는 pvrusb2 driver와 V4L에 별도로 구현된 `tveeprom.ko` module 사이의 glue logic입니다.

`pvrusb2-encoder.[ch]`는 device 안의 Conexant MPEG-2 encoder chip과 통신하는 데 필요한 모든 protocol을 구현합니다. `ivtv`의 대응 logic과 역할은 비슷하지만, 엄격한 격리라는 설계 목표와 PCI 대신 USB proxy를 사용하는 physical layer가 달라 구현은 완전히 별개여야 했습니다.

pvrusb2-debug.h - This header defines a printk() wrapper and a mask
    of debugging bit definitions for the various kinds of debug
    messages that can be enabled within the driver.

pvrusb2-debugifc.[ch] - This module implements a crude command line
    oriented debug interface into the driver.  Aside from being part
    of the process for implementing manual firmware extraction (see
    the pvrusb2 web site mentioned earlier), probably I'm the only one
    who has ever used this.  It is mainly a debugging aid.

pvrusb2-eeprom.[ch] - This is glue logic that resides between this
    driver the tveeprom.ko module, which is itself implemented
    elsewhere in V4L.

pvrusb2-encoder.[ch] - This module implements all protocol needed to
    interact with the Conexant mpeg2 encoder chip within the pvrusb2
    device.  It is a crude echo of corresponding logic in ivtv,
    however the design goals (strict isolation) and physical layer
    (proxy through USB instead of PCI) are enough different that this
    implementation had to be completely different.

Source 목록: hardware core API

`pvrusb2-hdw-internal.h`는 hardware 제어와 관련된 모든 internal state를 추적하는 core data structure를 정의합니다. Core hardware-handling module 밖에서는 이 header를 사용하면 안 됩니다.

외부 접근은 V4L이나 sysfs 같은 high-level interface를 통해야 하며, 이 interface들조차 `pvrusb2-hdw-internal.h`가 아니라 `pvrusb2-hdw.h`에 정의된 API로 제한됩니다.

`pvrusb2-hdw.h`는 hardware 제어를 위한 전체 internal API를 정의하므로 high-level interface는 이 경로를 사용합니다. `pvrusb2-hdw.c`는 특정 pvrusb2 device의 전반적 제어 logic을 구현합니다. Device policy, instantiation, arbitration은 이 파일이 아니라 `pvrusb2-context`의 책임입니다.

pvrusb2-hdw-internal.h - This header defines the core data structure
    in the driver used to track ALL internal state related to control
    of the hardware.  Nobody outside of the core hardware-handling
    modules should have any business using this header.  All external
    access to the driver should be through one of the high level
    interfaces (e.g. V4L, sysfs, etc), and in fact even those high
    level interfaces are restricted to the API defined in
    pvrusb2-hdw.h and NOT this header.

pvrusb2-hdw.h - This header defines the full internal API for
    controlling the hardware.  High level interfaces (e.g. V4L, sysfs)
    will work through here.

pvrusb2-hdw.c - This module implements all the various bits of logic
    that handle overall control of a specific pvrusb2 device.
    (Policy, instantiation, and arbitration of pvrusb2 devices fall
    within the jurisdiction of pvrusb-context not here).

Source 목록: I2C glue와 command 변환

`pvrusb2-i2c-chips-*.c`는 여러 I2C module이 bus에 attach될 때 이들을 연결하고 설정하는 glue logic입니다. 두 version 중 `v4l2` version은 V4L tree 내부의 순수 V4L 환경에 필요한 logic만 구현합니다. `all` version은 V4L 밖에서 `ivtv`, 오래된 kernel snapshot 또는 standalone snapshot의 지원 module처럼 다루기 까다로운 module을 만날 수 있는 경우를 위한 것입니다.

`pvrusb2-i2c-cmd-v4l1.[ch]`는 I2C module에 보내는 generic V4L1-compatible command를 구현합니다. Pvrusb2 내부 state 변화는 여기서 V4L1 command로 변환되어 각 I2C module에 전달됩니다.

`pvrusb2-i2c-cmd-v4l2.[ch]`도 같은 역할을 V4L2-compatible command에 대해 수행하며, 내부 state 변화를 V4L2 command로 변환해 I2C module에 전달합니다.

pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to
    tie together and configure various I2C modules as they attach to
    the I2C bus.  There are two versions of this file.  The "v4l2"
    version is intended to be used in-tree alongside V4L, where we
    implement just the logic that makes sense for a pure V4L
    environment.  The "all" version is intended for use outside of
    V4L, where we might encounter other possibly "challenging" modules
    from ivtv or older kernel snapshots (or even the support modules
    in the standalone snapshot).

pvrusb2-i2c-cmd-v4l1.[ch] - This module implements generic V4L1
    compatible commands to the I2C modules.  It is here where state
    changes inside the pvrusb2 driver are translated into V4L1
    commands that are in turn send to the various I2C modules.

pvrusb2-i2c-cmd-v4l2.[ch] - This module implements generic V4L2
    compatible commands to the I2C modules.  It is here where state
    changes inside the pvrusb2 driver are translated into V4L2
    commands that are in turn send to the various I2C modules.

Source 목록: I2C core와 streaming I/O

`pvrusb2-i2c-core.[ch]`는 kernel 친화적인 I2C adaptor driver를 구현합니다. `msp3400`, `tuner`, `lirc` 같은 외부 I2C client driver는 이 adaptor에 연결해 pvrusb2 device 내부의 대응 chip을 제어합니다.

다른 V4L module은 이 경로로 driver의 특정 부품을 제어합니다. 그 module들은 `pvrusb2-hdw`가 조정하는 glue logic에 의해 구동되고, `pvrusb2-context`가 접근을 배분한 뒤 high-level interface를 통해 user에게 제공됩니다.

`pvrusb2-io.[ch]`는 device data streaming에 필요한 매우 low-level transfer buffer ring을 구현합니다. Buffer만 운용하며 사용 policy나 mechanism은 정의하지 않습니다.

`pvrusb2-ioread.[ch]`는 `pvrusb2-io.[ch]` 위에 `read()` system call 방식 I/O에 사용할 streaming API를 제공합니다. 현재 유일한 상위 layer이지만, 기반 architecture는 추가 module을 통해 `mmap()` buffer나 더 특수한 I/O 방식도 구현할 수 있도록 설계됐습니다.

pvrusb2-i2c-core.[ch] - This module provides an implementation of a
    kernel-friendly I2C adaptor driver, through which other external
    I2C client drivers (e.g. msp3400, tuner, lirc) may connect and
    operate corresponding chips within the pvrusb2 device.  It is
    through here that other V4L modules can reach into this driver to
    operate specific pieces (and those modules are in turn driven by
    glue logic which is coordinated by pvrusb2-hdw, doled out by
    pvrusb2-context, and then ultimately made available to users
    through one of the high level interfaces).

pvrusb2-io.[ch] - This module implements a very low level ring of
    transfer buffers, required in order to stream data from the
    device.  This module is *very* low level.  It only operates the
    buffers and makes no attempt to define any policy or mechanism for
    how such buffers might be used.

pvrusb2-ioread.[ch] - This module layers on top of pvrusb2-io.[ch]
    to provide a streaming API usable by a read() system call style of
    I/O.  Right now this is the only layer on top of pvrusb2-io.[ch],
    however the underlying architecture here was intended to allow for
    other styles of I/O to be implemented with additional modules, like
    mmap()'ed buffers or something even more exotic.

Source 목록: 진입점과 high-level interface

`pvrusb2-main.c`는 driver의 최상위 파일로 module-level 및 USB core entry point를 포함하는 `main`입니다.

`pvrusb2-sysfs.[ch]`는 pvrusb2 driver를 sysfs에 연결하는 high-level interface입니다. 실제 data streaming을 제외한 driver의 모든 작업을 이 interface로 수행할 수 있습니다.

`pvrusb2-tuner.[ch]`는 driver와 V4L의 `tuner.ko` I2C client driver 사이 glue logic이며, `pvrusb2-util.h`는 driver 전체에서 쓰는 공통 macro를 정의합니다.

`pvrusb2-v4l2.[ch]`는 pvrusb2를 Video4Linux에 연결하는 high-level interface입니다. V4L application은 이 경로를 통해 일반적인 방식으로 driver를 open하고 조작합니다. 모든 V4L 기능은 오직 이 파일을 통해서만 공개되며 다른 위치에서는 공개되지 않습니다.

pvrusb2-main.c - This is the top level of the driver.  Module level
    and USB core entry points are here.  This is our "main".

pvrusb2-sysfs.[ch] - This is the high level interface which ties the
    pvrusb2 driver into sysfs.  Through this interface you can do
    everything with the driver except actually stream data.

pvrusb2-tuner.[ch] - This is glue logic that resides between this
    driver and the tuner.ko I2C client driver (which is found
    elsewhere in V4L).

pvrusb2-util.h - This header defines some common macros used
    throughout the driver.  These macros are not really specific to
    the driver, but they had to go somewhere.

pvrusb2-v4l2.[ch] - This is the high level interface which ties the
    pvrusb2 driver into video4linux.  It is through here that V4L
    applications can open and operate the driver in the usual V4L
    ways.  Note that **ALL** V4L functionality is published only
    through here and nowhere else.

Source 목록: video decoder와 build-time 설정

`pvrusb2-video-*.[ch]`는 pvrusb2 driver와 V4L의 다른 위치에 있는 `saa711x.ko` I2C client driver 사이 glue logic입니다. `saa711x.ko`는 과거 `ivtv`에서 `saa7115.ko`라는 이름으로 알려졌습니다. 발견된 `saa711[5x].ko` variant에 따라 두 version 중 하나를 선택합니다.

`pvrusb2.h`에는 compile-time 조정 parameter가 들어 있습니다. 문서 작성 시점의 driver에는 조정이 필요한 항목이 거의 없습니다.

pvrusb2-video-\*.[ch] - This is glue logic that resides between this
    driver and the saa711x.ko I2C client driver (which is found
    elsewhere in V4L).  Note that saa711x.ko used to be known as
    saa7115.ko in ivtv.  There are two versions of this; one is
    selected depending on the particular saa711[5x].ko that is found.

pvrusb2.h - This header contains compile time tunable parameters
    (and at the moment the driver has very little that needs to be
    tuned).