[media] doc-rst: add documentation for pvrusb2

	meye

	meye

	omap3isp

	omap3isp

	omap4_camera

	omap4_camera

	pvrusb2

	zr364xx

	zr364xx

The pvrusb2 driver

==================

$Id$

Author: Mike Isely <isely@pobox.com>

Mike Isely <isely@pobox.com>

			    pvrusb2 driver

Background

----------

Background:

This driver is intended for the "Hauppauge WinTV PVR USB 2.0", which

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.

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

Its history started with the reverse-engineering effort by Björn

Danielsson <pvrusb2@dax.nu> whose web page can be found here:

Danielsson <pvrusb2@dax.nu> whose web page can be found here:

http://pvrusb2.dax.nu/

http://pvrusb2.dax.nu/

From there Aurelien Alleaume <slts@free.fr> began an effort to

From there Aurelien Alleaume <slts@free.fr> began an effort to

here.

here.

More information on this driver can be found at:

More information on this driver can be found at:

http://www.isely.net/pvrusb2.html

http://www.isely.net/pvrusb2.html

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

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

roughly:

roughly:

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

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

  1b. I2C adaptor implementation and corresponding I2C client drivers

2. I2C adaptor implementation and corresponding I2C client drivers

   implemented elsewhere in V4L.

   implemented elsewhere in V4L.

  1c. High level hardware driver implementation which coordinates all

3. High level hardware driver implementation which coordinates all

   activities that ensure correct operation of the device.

   activities that ensure correct operation of the device.

  2.  A "context" layer which manages instancing of driver, setup,

4. A "context" layer which manages instancing of driver, setup,

   tear-down, arbitration, and interaction with high level

   tear-down, arbitration, and interaction with high level

   interfaces appropriately as devices are hotplugged in the

   interfaces appropriately as devices are hotplugged in the

   system.

   system.

  3.  High level interfaces which glue the driver to various published

5. High level interfaces which glue the driver to various published

   Linux APIs (V4L, sysfs, maybe DVB in the future).

   Linux APIs (V4L, sysfs, maybe DVB in the future).

The most important shearing layer is between the top 2 layers.  A

The most important shearing layer is between the top 2 layers.  A

possible to produce a DVB high level interface that can sit right

possible to produce a DVB high level interface that can sit right

alongside V4L.

alongside V4L.

  NOTE: Complete documentation on the pvrusb2 driver is contained in

  the html files within the doc directory; these are exactly the same

  as what is on the web site at the time.  Browse those files

  (especially the FAQ) before asking questions.

Building

Building

--------

To build these modules essentially amounts to just running "Make",

To build these modules essentially amounts to just running "Make",

but you need the kernel source tree nearby and you will likely also

but you need the kernel source tree nearby and you will likely also

to link things up with that source tree.  Please see the Makefile

to link things up with that source tree.  Please see the Makefile

here for comments that explain how to do that.

here for comments that explain how to do that.

Source file list / functional overview

Source file list / functional overview:

--------------------------------------

(Note: The term "module" used below generally refers to loosely

(Note: The term "module" used below generally refers to loosely

defined functional units within the pvrusb2 driver and bears no

defined functional units within the pvrusb2 driver and bears no

    (Policy, instantiation, and arbitration of pvrusb2 devices fall

    (Policy, instantiation, and arbitration of pvrusb2 devices fall

    within the jurisdiction of pvrusb-context not here).

    within the jurisdiction of pvrusb-context not here).

  pvrusb2-i2c-chips-*.c - These modules implement the glue logic to

pvrusb2-i2c-chips-\*.c - These modules implement the glue logic to

    tie together and configure various I2C modules as they attach to

    tie together and configure various I2C modules as they attach to

    the I2C bus.  There are two versions of this file.  The "v4l2"

    the I2C bus.  There are two versions of this file.  The "v4l2"

    version is intended to be used in-tree alongside V4L, where we

    version is intended to be used in-tree alongside V4L, where we

    ways.  Note that **ALL** V4L functionality is published only

    ways.  Note that **ALL** V4L functionality is published only

    through here and nowhere else.

    through here and nowhere else.

  pvrusb2-video-*.[ch] - This is glue logic that resides between this

pvrusb2-video-\*.[ch] - This is glue logic that resides between this

    driver and the saa711x.ko I2C client driver (which is found

    driver and the saa711x.ko I2C client driver (which is found

    elsewhere in V4L).  Note that saa711x.ko used to be known as

    elsewhere in V4L).  Note that saa711x.ko used to be known as

    saa7115.ko in ivtv.  There are two versions of this; one is

    saa7115.ko in ivtv.  There are two versions of this; one is

pvrusb2.h - This header contains compile time tunable parameters

pvrusb2.h - This header contains compile time tunable parameters

    (and at the moment the driver has very little that needs to be

    (and at the moment the driver has very little that needs to be

    tuned).

    tuned).

  -Mike Isely

  isely@pobox.com