$Id: README,v 1.7 2005/08/29 23:39:57 sbertin Exp $

1. Introduction

	This is a driver for STMicroelectronics's CPiA2 (second generation
Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG
stream at up to vga size. It implements the Video4Linux interface as much as
possible.  Since the V4L interface does not support compressed formats, only
an mjpeg enabled application can be used with the camera. We have modified the
gqcam application to view this stream.

	The driver is implemented as two kernel modules. The cpia2 module
contains the camera functions and the V4L interface.  The cpia2_usb module
contains usb specific functions.  The main reason for this was the size of the
module was getting out of hand, so I separated them.  It is not likely that
there will be a parallel port version.

FEATURES:
   - Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos
     sensors. I only have the vga sensor, so can't test the other.
   - Image formats: VGA, QVGA, CIF, QCIF, and a number of sizes in between.
     VGA and QVGA are the native image sizes for the VGA camera. CIF is done
     in the coprocessor by scaling QVGA.  All other sizes are done by clipping.
   - Palette: YCrCb, compressed with MJPEG.
   - Some compression parameters are settable.
   - Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA).
   - Adjust brightness, color, contrast while streaming.
   - Flicker control settable for 50 or 60 Hz mains frequency.

2. Making and installing the stv672 driver modules:

	Requirements:
	-------------
	This should work with 2.4 (2.4.23 and later) and 2.6 kernels, but has
only been tested on 2.6.  Video4Linux must be either compiled into the kernel or
available as a module.  Video4Linux2 is automatically detected and made
available at compile time.

	Compiling:
	----------
	As root, do a make install.  This will compile and install the modules
into the media/video directory in the module tree. For 2.4 kernels, use
Makefile_2.4 (aka do make -f Makefile_2.4 install).

	Setup:
	------
	Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This
may be done automatically by your distribution.

3. Driver options

	Option		Description
	------		-----------
	video_nr	video device to register (0=/dev/video0, etc)
			range -1 to 64.  default is -1 (first available)
			If you have more than 1 camera, this MUST be -1.
	buffer_size	Size for each frame buffer in bytes (default 68k)
	num_buffers	Number of frame buffers (1-32, default 3)
	alternate	USB Alternate (2-7, default 7)
	flicker_freq	Frequency for flicker reduction(50 or 60, default 60)
	flicker_mode	0 to disable, or 1 to enable flicker reduction.
			(default 0). This is only effective if the camera
			uses a stv0672 coprocessor.

	Setting the options:
	--------------------
	If you are using modules, edit /etc/modules.conf and add an options
line like this:
	options cpia2 num_buffers=3 buffer_size=65535

	If the driver is compiled into the kernel, at boot time specify them
like this:
	cpia2.num_buffers=3 cpia2.buffer_size=65535

	What buffer size should I use?
	------------------------------
	The maximum image size depends on the alternate you choose, and the
frame rate achieved by the camera.  If the compression engine is able to
keep up with the frame rate, the maximum image size is given by the table
below.
	The compression engine starts out at maximum compression, and will
increase image quality until it is close to the size in the table.  As long
as the compression engine can keep up with the frame rate, after a short time
the images will all be about the size in the table, regardless of resolution.
	At low alternate settings, the compression engine may not be able to
compress the image enough and will reduce the frame rate by producing larger
images.
	The default of 68k should be good for most users.  This will handle
any alternate at frame rates down to 15fps.  For lower frame rates, it may
be necessary to increase the buffer size to avoid having frames dropped due
to insufficient space.

			     Image size(bytes)
	Alternate  bytes/ms   15fps    30fps
	    2         128      8533     4267
	    3         384     25600    12800
	    4         640     42667    21333
	    5         768     51200    25600
	    6         896     59733    29867
	    7        1023     68200    34100

	How many buffers should I use?
	------------------------------
	For normal streaming, 3 should give the best results.  With only 2,
it is possible for the camera to finish sending one image just after a
program has started reading the other.  If this happens, the driver must drop
a frame.  The exception to this is if you have a heavily loaded machine.  In
this case use 2 buffers.  You are probably not reading at the full frame rate.
If the camera can send multiple images before a read finishes, it could
overwrite the third buffer before the read finishes, leading to a corrupt
image.  Single and double buffering have extra checks to avoid overwriting.

4. Using the camera

	We are providing a modified gqcam application to view the output. In
order to avoid confusion, here it is called mview.  There is also the qx5view
program which can also control the lights on the qx5 microscope. MJPEG Tools
(http://mjpeg.sourceforge.net) can also be used to record from the camera.

5. Notes to developers:

   - This is a driver version stripped of the 2.4 back compatibility
     and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support.

6. Thanks:

   - Peter Pregler <Peter_Pregler@email.com>,
     Scott J. Bertin <scottbertin@yahoo.com>, and
     Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which
     this one was modelled from.

cx8800 release notes
====================

This is a v4l2 device driver for the cx2388x chip.


current status
==============

video
	- Basically works.
	- For now, only capture and read(). Overlay isn't supported.

audio
	- The chip specs for the on-chip TV sound decoder are next
	  to useless :-/
	- Neverless the builtin TV sound decoder starts working now,
	  at least for some standards.
	  FOR ANY REPORTS ON THIS PLEASE MENTION THE TV NORM YOU ARE
	  USING.
	- Most tuner chips do provide mono sound, which may or may not
	  be useable depending on the board design.  With the Hauppauge
	  cards it works, so there is mono sound available as fallback.
	- audio data dma (i.e. recording without loopback cable to the
	  sound card) is supported via cx88-alsa.

vbi
	- Code present. Works for NTSC closed caption. PAL and other
	  TV norms may or may not work.


how to add support for new cards
================================

The driver needs some config info for the TV cards.  This stuff is in
cx88-cards.c.  If the driver doesn't work well you likely need a new
entry for your card in that file.  Check the kernel log (using dmesg)
to see whenever the driver knows your card or not.  There is a line
like this one:

	cx8800[0]: subsystem: 0070:3400, board: Hauppauge WinTV \
		34xxx models [card=1,autodetected]

If your card is listed as "board: UNKNOWN/GENERIC" it is unknown to
the driver.  What to do then?

 (1) Try upgrading to the latest snapshot, maybe it has been added
     meanwhile.
 (2) You can try to create a new entry yourself, have a look at
     cx88-cards.c.  If that worked, mail me your changes as unified
     diff ("diff -u").
 (3) Or you can mail me the config information.  I need at least the
     following informations to add the card:

     * the PCI Subsystem ID ("0070:3400" from the line above,
       "lspci -v" output is fine too).
     * the tuner type used by the card.  You can try to find one by
       trial-and-error using the tuner=<n> insmod option.  If you
       know which one the card has you can also have a look at the
       list in CARDLIST.tuner

Have fun,

  Gerd

--
Gerd Knorr <kraxel@bytesex.org> [SuSE Labs]

                VPBE V4L2 driver design
 ======================================================================

 File partitioning
 -----------------
 V4L2 display device driver
         drivers/media/platform/davinci/vpbe_display.c
         drivers/media/platform/davinci/vpbe_display.h

 VPBE display controller
         drivers/media/platform/davinci/vpbe.c
         drivers/media/platform/davinci/vpbe.h

 VPBE venc sub device driver
         drivers/media/platform/davinci/vpbe_venc.c
         drivers/media/platform/davinci/vpbe_venc.h
         drivers/media/platform/davinci/vpbe_venc_regs.h

 VPBE osd driver
         drivers/media/platform/davinci/vpbe_osd.c
         drivers/media/platform/davinci/vpbe_osd.h
         drivers/media/platform/davinci/vpbe_osd_regs.h

 Functional partitioning
 -----------------------

 Consists of the following (in the same order as the list under file
 partitioning):-

 1. V4L2 display driver
    Implements creation of video2 and video3 device nodes and
    provides v4l2 device interface to manage VID0 and VID1 layers.

 2. Display controller
    Loads up VENC, OSD and external encoders such as ths8200. It provides
    a set of API calls to V4L2 drivers to set the output/standards
    in the VENC or external sub devices. It also provides
    a device object to access the services from OSD subdevice
    using sub device ops. The connection of external encoders to VENC LCD
    controller port is done at init time based on default output and standard
    selection or at run time when application change the output through
    V4L2 IOCTLs.

    When connected to an external encoder, vpbe controller is also responsible
    for setting up the interface between VENC and external encoders based on
    board specific settings (specified in board-xxx-evm.c). This allows
    interfacing external encoders such as ths8200. The setup_if_config()
    is implemented for this as well as configure_venc() (part of the next patch)
    API to set timings in VENC for a specific display resolution. As of this
    patch series, the interconnection and enabling and setting of the external
    encoders is not present, and would be a part of the next patch series.

 3. VENC subdevice module
    Responsible for setting outputs provided through internal DACs and also
    setting timings at LCD controller port when external encoders are connected
    at the port or LCD panel timings required. When external encoder/LCD panel
    is connected, the timings for a specific standard/preset is retrieved from
    the board specific table and the values are used to set the timings in
    venc using non-standard timing mode.

    Support LCD Panel displays using the VENC. For example to support a Logic
    PD display, it requires setting up the LCD controller port with a set of
    timings for the resolution supported and setting the dot clock. So we could
    add the available outputs as a board specific entry (i.e add the "LogicPD"
    output name to board-xxx-evm.c). A table of timings for various LCDs
    supported can be maintained in the board specific setup file to support
    various LCD displays.As of this patch a basic driver is present, and this
    support for external encoders and displays forms a part of the next
    patch series.

 4. OSD module
    OSD module implements all OSD layer management and hardware specific
    features. The VPBE module interacts with the OSD for enabling and
    disabling appropriate features of the OSD.

 Current status:-

 A fully functional working version of the V4L2 driver is available. This
 driver has been tested with NTSC and PAL standards and buffer streaming.

 Following are TBDs.

 vpbe display controller
    - Add support for external encoders.
    - add support for selecting external encoder as default at probe time.

 vpbe venc sub device
    - add timings for supporting ths8200
    - add support for LogicPD LCD.

 FB drivers
    - Add support for fbdev drivers.- Ready and part of subsequent patches.

infrared remote control support in video4linux drivers
======================================================


basics
------

Current versions use the linux input layer to support infrared
remote controls.  I suggest to download my input layer tools
from http://bytesex.org/snapshot/input-<date>.tar.gz

Modules you have to load:

  saa7134	statically built in, i.e. just the driver :)
  bttv		ir-kbd-gpio or ir-kbd-i2c depending on your
		card.

ir-kbd-gpio and ir-kbd-i2c don't support all cards lirc supports
(yet), mainly for the reason that the code of lirc_i2c and lirc_gpio
was very confusing and I decided to basically start over from scratch.
Feel free to contact me in case of trouble.  Note that the ir-kbd-*
modules work on 2.6.x kernels only through ...


how it works
------------

The modules register the remote as keyboard within the linux input
layer, i.e. you'll see the keys of the remote as normal key strokes
(if CONFIG_INPUT_KEYBOARD is enabled).

Using the event devices (CONFIG_INPUT_EVDEV) it is possible for
applications to access the remote via /dev/input/event<n> devices.
You might have to create the special files using "/sbin/MAKEDEV
input".  The input layer tools mentioned above use the event device.

The input layer tools are nice for trouble shooting, i.e. to check
whenever the input device is really present, which of the devices it
is, check whenever pressing keys on the remote actually generates
events and the like.  You can also use the kbd utility to change the
keymaps (2.6.x kernels only through).


using with lircd
================

The cvs version of the lircd daemon supports reading events from the
linux input layer (via event device).  The input layer tools tarball
comes with a lircd config file.


using without lircd
===================

XFree86 likely can be configured to recognise the remote keys.  Once I
simply tried to configure one of the multimedia keyboards as input
device, which had the effect that XFree86 recognised some of the keys
of my remote control and passed volume up/down key presses as
XF86AudioRaiseVolume and XF86AudioLowerVolume key events to the X11
clients.

It likely is possible to make that fly with a nice xkb config file,
I know next to nothing about that through.


Have fun,

  Gerd

--
Gerd Knorr <kraxel@bytesex.org>

ivtv release notes
==================

This is a v4l2 device driver for the Conexant cx23415/6 MPEG encoder/decoder.
The cx23415 can do both encoding and decoding, the cx23416 can only do MPEG
encoding. Currently the only card featuring full decoding support is the
Hauppauge PVR-350.

NOTE: this driver requires the latest encoder firmware (version 2.06.039, size
376836 bytes). Get the firmware from here:

http://dl.ivtvdriver.org/ivtv/firmware/

NOTE: 'normal' TV applications do not work with this driver, you need
an application that can handle MPEG input such as mplayer, xine, MythTV,
etc.

The primary goal of the IVTV project is to provide a "clean room" Linux
Open Source driver implementation for video capture cards based on the
iCompression iTVC15 or Conexant CX23415/CX23416 MPEG Codec.

Features:
 * Hardware mpeg2 capture of broadcast video (and sound) via the tuner or
   S-Video/Composite and audio line-in.
 * Hardware mpeg2 capture of FM radio where hardware support exists
 * Supports NTSC, PAL, SECAM with stereo sound
 * Supports SAP and bilingual transmissions.
 * Supports raw VBI (closed captions and teletext).
 * Supports sliced VBI (closed captions and teletext) and is able to insert
   this into the captured MPEG stream.
 * Supports raw YUV and PCM input.

Additional features for the PVR-350 (CX23415 based):
 * Provides hardware mpeg2 playback
 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
   video signal)
 * Provides a framebuffer (allowing X applications to appear on the video
   device)
 * Supports raw YUV output.

IMPORTANT: In case of problems first read this page:
	   http://www.ivtvdriver.org/index.php/Troubleshooting

See also:

Homepage + Wiki
http://www.ivtvdriver.org

IRC
irc://irc.freenode.net/ivtv-dev

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

Devices
=======

A maximum of 12 ivtv boards are allowed at the moment.

Cards that don't have a video output capability (i.e. non PVR350 cards)
lack the vbi8, vbi16, video16 and video48 devices. They also do not
support the framebuffer device /dev/fbx for OSD.

The radio0 device may or may not be present, depending on whether the
card has a radio tuner or not.

Here is a list of the base v4l devices:
crw-rw----    1 root     video     81,   0 Jun 19 22:22 /dev/video0
crw-rw----    1 root     video     81,  16 Jun 19 22:22 /dev/video16
crw-rw----    1 root     video     81,  24 Jun 19 22:22 /dev/video24
crw-rw----    1 root     video     81,  32 Jun 19 22:22 /dev/video32
crw-rw----    1 root     video     81,  48 Jun 19 22:22 /dev/video48
crw-rw----    1 root     video     81,  64 Jun 19 22:22 /dev/radio0
crw-rw----    1 root     video     81, 224 Jun 19 22:22 /dev/vbi0
crw-rw----    1 root     video     81, 228 Jun 19 22:22 /dev/vbi8
crw-rw----    1 root     video     81, 232 Jun 19 22:22 /dev/vbi16

Base devices
============

For every extra card you have the numbers increased by one. For example,
/dev/video0 is listed as the 'base' encoding capture device so we have:

 /dev/video0  is the encoding capture device for the first card (card 0)
 /dev/video1  is the encoding capture device for the second card (card 1)
 /dev/video2  is the encoding capture device for the third card (card 2)

Note that if the first card doesn't have a feature (eg no decoder, so no
video16, the second card will still use video17. The simple rule is 'add
the card number to the base device number'. If you have other capture
cards (e.g. WinTV PCI) that are detected first, then you have to tell
the ivtv module about it so that it will start counting at 1 (or 2, or
whatever). Otherwise the device numbers can get confusing. The ivtv
'ivtv_first_minor' module option can be used for that.


/dev/video0
The encoding capture device(s).
Read-only.

Reading from this device gets you the MPEG1/2 program stream.
Example:

cat /dev/video0 > my.mpg (you need to hit ctrl-c to exit)


/dev/video16
The decoder output device(s)
Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.

An mpeg2 stream sent to this device will appear on the selected video
display, audio will appear on the line-out/audio out.  It is only
available for cards that support video out. Example:

cat my.mpg >/dev/video16


/dev/video24
The raw audio capture device(s).
Read-only

The raw audio PCM stereo stream from the currently selected
tuner or audio line-in.  Reading from this device results in a raw
(signed 16 bit Little Endian, 48000 Hz, stereo pcm) capture.
This device only captures audio. This should be replaced by an ALSA
device in the future.
Note that there is no corresponding raw audio output device, this is
not supported in the decoder firmware.


/dev/video32
The raw video capture device(s)
Read-only

The raw YUV video output from the current video input. The YUV format
is non-standard (V4L2_PIX_FMT_HM12).

Note that the YUV and PCM streams are not synchronized, so they are of
limited use.


/dev/video48
The raw video display device(s)
Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.

Writes a YUV stream to the decoder of the card.


/dev/radio0
The radio tuner device(s)
Cannot be read or written.

Used to enable the radio tuner and tune to a frequency. You cannot
read or write audio streams with this device.  Once you use this
device to tune the radio, use /dev/video24 to read the raw pcm stream
or /dev/video0 to get an mpeg2 stream with black video.


/dev/vbi0
The 'vertical blank interval' (Teletext, CC, WSS etc) capture device(s)
Read-only

Captures the raw (or sliced) video data sent during the Vertical Blank
Interval. This data is used to encode teletext, closed captions, VPS,
widescreen signalling, electronic program guide information, and other
services.


/dev/vbi8
Processed vbi feedback device(s)
Read-only. Only present if the MPEG decoder (i.e. CX23415) exists.

The sliced VBI data embedded in an MPEG stream is reproduced on this
device. So while playing back a recording on /dev/video16, you can
read the embedded VBI data from /dev/vbi8.


/dev/vbi16
The vbi 'display' device(s)
Write-only. Only present if the MPEG decoder (i.e. CX23415) exists.

Can be used to send sliced VBI data to the video-out connector.

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

Hans Verkuil <hverkuil@xs4all.nl>

$Id$
Mike Isely <isely@pobox.com>

			    pvrusb2 driver

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 <pvrusb2@dax.nu> whose web page can be found here:

    http://pvrusb2.dax.nu/

  From there Aurelien Alleaume <slts@free.fr> 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:

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


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

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

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

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

  2.  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.

  3.  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.

  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

  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 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).

  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.

  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).

  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.

  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.

  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.

  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).


  -Mike Isely
  isely@pobox.com

What is it?
===========

This is a v4l2/oss device driver for saa7130/33/34/35 based capture / TV
boards.  See http://www.semiconductors.philips.com/pip/saa7134hl for a
description.


Status
======

Almost everything is working.  video, sound, tuner, radio, mpeg ts, ...

As with bttv, card-specific tweaks are needed.  Check CARDLIST for a
list of known TV cards and saa7134-cards.c for the drivers card
configuration info.


Build
=====

Pick up videodev + v4l2 patches from http://bytesex.org/patches/.
Configure, build, install + boot the new kernel.  You'll need at least
these config options:

	CONFIG_I2C=m
	CONFIG_VIDEO_DEV=m

Type "make" to build the driver now.  "make install" installs the
driver.  "modprobe saa7134" should load it.  Depending on the card you
might have to pass card=<nr> as insmod option, check CARDLIST for
valid choices.


Changes / Fixes
===============

Please mail me unified diffs ("diff -u") with your changes, and don't
forget to tell me what it changes / which problem it fixes / whatever
it is good for ...


Known Problems
==============

* The tuner for the flyvideos isn't detected automatically and the
  default might not work for you depending on which version you have.
  There is a tuner= insmod option to override the driver's default.

Card Variations:
================

Cards can use either of these two crystals (xtal):
 - 32.11 MHz -> .audio_clock=0x187de7
 - 24.576MHz -> .audio_clock=0x200000
(xtal * .audio_clock = 51539600)

Some details about 30/34/35:

 - saa7130 - low-price chip, doesn't have mute, that is why all those
 cards should have .mute field defined in their tuner structure.

 - saa7134 - usual chip

 - saa7133/35 - saa7135 is probably a marketing decision, since all those
 chips identifies itself as 33 on pci.

Credits
=======

andrew.stevens@philips.com + werner.leeb@philips.com for providing
saa7134 hardware specs and sample board.


Have fun,

  Gerd

--
Gerd Knorr <kraxel@bytesex.org> [SuSE Labs]