- Merge with Linux 2.1.121.

- Bugfixes.
author: Ralf Baechle <ralf@linux-mips.org> 1998-09-19 19:15:08 +0000
committer: Ralf Baechle <ralf@linux-mips.org> 1998-09-19 19:15:08 +0000
commit: 03ba4131783cc9e872f8bb26a03f15bc11f27564 (patch)
tree: 88db8dba75ae06ba3bad08e42c5e52efc162535c /Documentation/video4linux
parent: 257730f99381dd26e10b832fce4c94cae7ac1176 (diff)
14 files changed, 949 insertions, 0 deletions
diff --git a/Documentation/video4linux/API.html b/Documentation/video4linux/API.html
new file mode 100644
index 000000000..5b3780cc3
--- /dev/null
+++ b/Documentation/video4linux/API.html
@@ -0,0 +1,354 @@
+<HTML><HEAD>
+<TITLE>Video4Linux Kernel API Reference v0.1:19980516</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
+<H3>Devices</H3>
+Video4Linux provides the following sets of device files. These live on the
+character device formerly known as "/dev/bttv". /dev/bttv should be a
+symlink to /dev/video0 for most people. 
+<P>
+<TABLE>
+<TR><TH>Device Name</TH><TH>Minor Range</TH><TH>Function</TH>
+<TR><TD>/dev/video</TD><TD>0-63</TD><TD>Video Capture Interface</TD>
+<TR><TD>/dev/radio</TD><TD>64-127</TD><TD>AM/FM Radio Devices</TD>
+<TR><TD>/dev/vtx</TD><TD>192-223</TD><TD>Teletext Interface Chips</TD>
+<TR><TD>/dev/vbi</TD><TD>224-239</TD><TD>Raw VBI Data (Intercast/teletext)</TD>
+</TABLE>
+<P>
+Video4Linux programs open and scan the devices to find what they are looking
+for. Capability queries define what each interface supports. The 
+described API is only defined for video capture cards. The relevant subset
+applies to radio cards. Teletext interfaces talk the existing VTX API.
+<P>
+<H3>Capability Query Ioctl</H3>
+The <B>VIDIOCGCAP</B> ioctl call is used to obtain the capability
+information for a video device. The <b>struct video_capability</b> object
+passed to the ioctl is completed and returned. It contains the following
+information
+<P>
+<TABLE>
+<TR><TD><b>name[32]</b><TD>Cannonical name for this interface</TD>
+<TR><TD><b>type</b><TD>Type of interface</TD>
+<TR><TD><b>channels</b><TD>Number of radio/tv channels if appropriate</TD>
+<TR><TD><b>audios</b><TD>Number of audio devices if appropriate</TD>
+<TR><TD><b>maxwidth</b><TD>Maximum capture width in pixels</TD>
+<TR><TD><b>maxheight</b><TD>Maximum capture height in pixels</TD>
+<TR><TD><b>minwidth</b><TD>Minimum capture width in pixels</TD>
+<TR><TD><b>minheight</b><TD>Minimum capture height in pixels</TD>
+</TABLE>
+<P>
+The type field lists the capability flags for the device. These are
+as follows
+<P>
+<TABLE>
+<TR><TH>Name</TH><TH>Description</TH>
+<TR><TD><b>VID_TYPE_CAPTURE</b><TD>Can capture to memory</TD>
+<TR><TD><b>VID_TYPE_TUNER</b><TD>Has a tuner of some form</TD>
+<TR><TD><b>VID_TYPE_TELETEXT</b><TD>Has teletext capability</TD>
+<TR><TD><b>VID_TYPE_OVERLAY</b><TD>Can overlay its image onto the frame buffer</TD>
+<TR><TD><b>VID_TYPE_CHROMAKEY</b><TD>Overlay is Chromakeyed</TD>
+<TR><TD><b>VID_TYPE_CLIPPING</b><TD>Overlay clipping is supported</TD>
+<TR><TD><b>VID_TYPE_FRAMERAM</b><TD>Overlay overwrites frame buffer memory</TD>
+<TR><TD><b>VID_TYPE_SCALES</b><TD>The hardware supports image scaling</TD>
+<TR><TD><b>VID_TYPE_MONOCHROME</b><TD>Image capture is grey scale only</TD>
+<TR><TD><b>VID_TYPE_SUBCAPTURE</b><TD>Capture can be of only part of the image</TD>
+</TABLE>
+<P>
+The minimum and maximum sizes listed for a capture device do not imply all
+that all height/width ratios or sizes within the range are possible. A
+request to set a size will be honoured by the largest available capture
+size whose capture is no large than the requested rectangle in either
+direction. For example the quickcam has 3 fixed settings. 
+<P>
+<H3>Frame Buffer</H3>
+Capture cards that drop data directly onto the frame buffer must be told the
+base address of the frame buffer, its size and organisation. This is a 
+privileged ioctl and one that eventually X itself should set.
+<P>
+The <b>VIDIOCSFBUF</b> ioctl sets the frame buffer parameters for a capture
+card. If the card does not do direct writes to the frame buffer then this
+ioctl will be unsupported. The <b>VIDIOCGFBUF</b> ioctl returns the
+currently used parameters. The structure used in both cases is a 
+<b>struct video_buffer</b>.
+<P>
+<TABLE>
+<TR><TD><b>void *base</b></TD><TD>Base physical address of the buffer</TD>
+<TR><TD><b>int height</b></TD><TD>Height of the frame buffer</TD>
+<TR><TD><b>int width</b></TD><TD>Width of the frame buffer</TD>
+<TR><TD><b>int depth</b></TD><TD>Depth of the frame buffer</TD>
+<TR><TD><b>int bytesperline</b></TD><TD>Number of bytes of memory between the start of two adjacent lines</TD>
+</TABLE>
+<P>
+Note that these values reflect the physical layout of the frame buffer. 
+The visible area may be smaller. In fact under XFree86 this is commonly the
+case. XFree86 DGA can provide the parameters required to set up this ioctl.
+Setting the base address to NULL indicates there is no physical frame buffer
+access.
+<P>
+<H3>Capture Windows</H3>
+The capture area is described by a <b>struct video_window</b>. This defines
+a capture area and the clipping information if relevant. The 
+<b>VIDIOCGWIN</b> ioctl recovers the current settings and the 
+<b>VIDIOCSWIN</b> sets new values. A successful call to <b>VIDIOCSWIN</b> 
+indicates that a suitable set of parameters have been chosen. They do not
+indicate that exactly what was requested was granted. The program should
+call <b>VIDIOCGWIN</b> to check if the nearest match was suitable. The
+<b>struct video_window</b> contains the following fields.
+<P>
+<TABLE>
+<TR><TD><b>x</b><TD>The X co-ordinate specified in X windows format.</TD>
+<TR><TD><b>y</b><TD>The Y co-ordinate specified in X windows format.</TD>
+<TR><TD><b>width</b><TD>The width of the image capture.</TD>
+<TR><TD><b>height</b><TD>The height of the image capture.</TD>
+<TR><TD><b>chromakey</b><TD>A host order RGB32 value for the chroma key.</TD>
+<TR><TD><b>flags</b><TD>Additional capture flags.</TD>
+<TR><TD><b>clips</b><TD>A list of clipping rectangles. <em>(Set only)</em)</TD>
+<TR><TD><b>clipcount</b><TD>The number of clipping rectangles. <em>(Set only)</em></TD>
+</TABLE>
+<P>
+Clipping rectangles are passed as an array. Each clip consists of the following
+fields available to the user.
+<P>
+<TABLE>
+<TR><TD><b>x</b></TD><TD>X co-ordinate of rectangle to skip</TD>
+<TR><TD><b>y</b></TD><TD>Y co-ordinate of rectangle to skip</TD>
+<TR><TD><b>width</b></TD><TD>Width of rectangle to skip</TD>
+<TR><TD><b>height</b></TD><TD>Height of rectangle to skip</TD>
+</TABLE>
+<P>
+Merely setting the window does not enable capturing. Overlay capturing
+is activatied by passing the <b>VIDIOCCAPTURE</b> ioctl a value of 1, and
+disabled by passing it a value of 0. 
+<P>
+Some capture devices can capture a subfield of the image they actually see.
+This is indicated when VIDEO_TYPE_SUBCAPTURE is defined.
+The video_capture describes the time and spacial subfields to capture.
+The video_capture structure contains the following fields.
+<P>
+<TABLE>
+<TR><TD><b>x</b></TD><TD>X co-ordinate of source rectangle to grab</TD>
+<TR><TD><b>y</b></TD><TD>Y co-ordinate of source rectangle to grab</TD>
+<TR><TD><b>width</b></TD><TD>Width of source rectangle to grab</TD>
+<TR><TD><b>height</b></TD><TD>Height of source rectangle to grab</TD>
+<TR><TD><b>decimation</b></TD><TD>Decimation to apply</TD>
+<TR><TD><b>flags</b></TD><TD>Flag settings for grabbing</TD>
+</TABLE>
+The available flags are
+<P>
+<TABLE>
+<TR><TH>Name</TH><TH>Description</TH>
+<TR><TD><b>VIDEO_CAPTURE_ODD</b><TD>Capture only odd frames</TD>
+<TR><TD><b>VIDEO_CAPTURE_EVEN</b><TD>Capture only even frames</TD>
+</TABLE>
+<P>
+<H3>Video Sources</H3>
+Each video4linux video or audio device captures from one or more 
+source <b>channels</b>. Each channel can be queries with the 
+<b>VDIOCGCHAN</b> ioctl call. Before invoking this function the caller
+must set the channel field to the channel that is being queried. On return
+the <b>struct video_channel</b> is filled in with information about the
+nature of the channel itself.
+<P>
+The <b>VIDIOCSCHAN</b> ioctl takes an integer argument and switches the
+capture to this input. It is not defined whether paramters such as colour
+settings or tuning are maintained across a channel switch. The caller should
+maintain settings as desired for each channel. (This is reasonable as 
+different video inputs may have different properties).
+<P>
+The <b>struct video_channel</b> consists of the following
+<P>
+<TABLE>
+<TR><TD><b>channel</b></TD><TD>The channel number</TD>
+<TR><TD><b>name</b></TD><TD>The input name - preferably reflecting the label
+on the card input itself</TD>
+<TR><TD><b>tuners</b></TD><TD>Number of tuners for this input</TD>
+<TR><TD><b>flags</b></TD><TD>Properties the tuner has</TD>
+<TR><TD><b>type</b></TD><TD>Input type (if known)</TD>
+<TR><TD><b>norm</b><TD>The norm for this channel</TD>
+</TABLE>
+<P>
+The flags defined are
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_VC_TUNER</b><TD>Channel has tuners.</TD>
+<TR><TD><b>VIDEO_VC_AUDIO</b><TD>Channel has audio.</TD>
+<TR><TD><b>VIDEO_VC_NORM</b><TD>Channel has norm setting.</TD>
+</TABLE>
+<P>
+The types defined are
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_TYPE_TV</b><TD>The input is a TV input.</TD>
+<TR><TD><b>VIDEO_TYPE_CAMERA</b><TD>The input is a camera.</TD>
+</TABLE>
+<P>
+<H3>Image Properties</H3>
+The image properties of the picture can be queried with the <b>VIDIOCGPICT</b>
+ioctl which fills in a <b>struct video_picture</b>. The <b>VIDIOCSPICT</b> 
+ioctl allows values to be changed. All values except for the palette type
+are scaled between 0-65535. 
+<P>
+The <b>struct video_picture</b> consists of the following fields
+<P>
+<TABLE>
+<TR><TD><b>brightness</b><TD>Picture brightness</TD>
+<TR><TD><b>hue</b><TD>Picture hue (colour only)</TD>
+<TR><TD><b>colour</b><TD>Picture colour (colour only)</TD>
+<TR><TD><b>contrast</b><TD>Picture contrast</TD>
+<TR><TD><b>whiteness</b><TD>The whiteness (greyscale only)</TD>
+<TR><TD><b>depth</b><TD>The capture depth (may need to match the frame buffer depth)</TD>
+<TR><TD><b>palette</b><TD>Reports the palette that should be used for this image</TD>
+</TABLE>
+<P>
+The following palettes are defined
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_PALETTE_GREY</b><TD>Linear intensity grey scale (255 is brightest).</TD>
+<TR><TD><b>VIDEO_PALETTE_HI240</b><TD>The BT848 8bit colour cube.</TD>
+<TR><TD><b>VIDEO_PALETTE_RGB565</b><TD>RGB565 packed into 16 bit words.</TD>
+<TR><TD><b>VIDEO_PALETTE_RGB555</b><TD>RGV555 packed into 16 bit words, top bit undefined.</TD>
+<TR><TD><b>VIDEO_PALETTE_RGB24</b><TD>RGB888 packed into 24bit words.</TD>
+<TR><TD><b>VIDEO_PALETTE_RGB32</b><TD>RGB888 packed into the low 3 bytes of 32bit words. The top 8bits are undefined.</TD>
+<TR><TD><b>VIDEO_PALETTE_YUV422</b><TD>Video style YUV422 - 8bits packed 4bits Y 2bits U 2bits V</TD>
+<TR><TD><b>VIDEO_PALETTE_YUYV</b><TD>Describe me</TD>
+<TR><TD><b>VIDEO_PALETTE_UYVY</b><TD>Describe me</TD>
+<TR><TD><b>VIDEO_PALETTE_YUV420</b><TD>YUV420 capture</TD>
+<TR><TD><b>VIDEO_PALETTE_YUV411</b><TD>YUV411 capture</TD>
+<TR><TD><b>VIDEO_PALETTE_RAW</b><TD>RAW capture (BT848)</TD>
+<TR><TD><b>VIDEO_PALETTE_YUV422P</b><TD>YUV 4:2:2 Planar</TD>
+<TR><TD><b>VIDEO_PALETTE_YUV411P</b><TD>YUV 4:1:1 Planar</TD>
+</TABLE>
+<P>
+<H3>Tuning</H3>
+Each video input channel can have one or more tuners associated with it. Many
+devices will not have tuners. TV cards and radio cards will have one or more
+tuners attached.
+<P>
+Tuners are described by a <b>struct video_tuner</b> which can be obtained by
+the <b>VIDIOCGTUNER</b> ioctl. Fill in the tuner number in the structure
+then pass the structure to the ioctl to have the data filled in. The 
+tuner can be switched using <b>VIDIOCSTUNER</b> which takes an integer argument
+giving the tuner to use. A struct tuner has the following fields
+<P>
+<TABLE>
+<TR><TD><b>tuner</b><TD>Number of the tuner</TD>
+<TR><TD><b>name</b><TD>Cannonical name for this tuner (eg FM/AM/TV)</TD>
+<TR><TD><b>rangelow</b><TD>Lowest tunable frequency</TD>
+<TR><TD><b>rangehigh</b><TD>Highest tunable frequency</TD>
+<TR><TD><b>flags</b><TD>Flags describing the tuner</TD>
+<TR><TD><b>mode</b><TD>The video signal mode if relevant</TD>
+<TR><TD><b>signal</b><TD>Signal strength if known - between 0-65535</TD>
+</TABLE>
+<P>
+The following flags exist
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_TUNER_PAL</b><TD>PAL tuning is supported</TD>
+<TR><TD><b>VIDEO_TUNER_NTSC</b><TD>NTSC tuning is supported</TD>
+<TR><TD><b>VIDEO_TUNER_SECAM</b><TD>SECAM tuning is supported</TD>
+<TR><TD><b>VIDEO_TUNER_LOW</b><TD>Frequency is in a lower range</TD>
+<TR><TD><b>VIDEO_TUNER_NORM</b><TD>The norm for this tuner is settable</TD>
+<TR><TD><b>VIDEO_TUNER_STEREO_ON</b><TD>The tuner is seeing stereo audio</TD>
+</TABLE>
+<P>
+The following modes are defined
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_MODE_PAL</b><TD>The tuner is in PAL mode</TD>
+<TR><TD><b>VIDEO_MODE_NTSC</b><TD>The tuner is in NTSC mode</TD>
+<TR><TD><b>VIDEO_MODE_SECAM</b><TD>The tuner is in SECAM mode</TD>
+<TR><TD><b>VIDEO_MODE_AUTO</b><TD>The tuner auto switches, or mode does not apply</TD>
+</TABLE>
+<P>
+Tuning frequencies are an unsigned 32bit value in 1/16th MHz or if the
+<b>VIDEO_TUNER_LOW</b> flag is set they are in 1/16th KHz. The current
+frequency is obtained as an unsigned long via the <b>VIDIOCGFREQ</b> ioctl and
+set by the <b>VIDIOCSFREQ</b> ioctl.
+<P>
+<H3>Audio</H3>
+TV and Radio devices have one or more audio inputs that may be selected. 
+The audio properties are queried by passing a <b>struct video_audio</b> to <b>VIDIOCGAUDIO</b> ioctl. The
+<b>VIDIOCSAUDIO</b> ioctl sets audio properties.
+<P>
+The structure contains the following fields
+<P>
+<TABLE>
+<TR><TD><b>audio</b><TD>The channel number</TD>
+<TR><TD><b>volume</b><TD>The voume level</TD>
+<TR><TD><b>bass</b><TD>The bass level</TD>
+<TR><TD><b>treble</b><TD>The treble level</TD>
+<TR><TD><b>flags</b><TD>Flags describing the audio channel</TD>
+<TR><TD><b>name</b><TD>Canonical name for the audio input</TD>
+<TR><TD><b>mode</b><TD>The mode the audio input is in</TD>
+<TR><TD><b>balance</b><TD>The left/right balance</TD>
+<TR><TD><b>step</b><TD>Actual step used by the hardware</TD>
+</TABLE>
+<P>
+The following flags are defined
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_AUDIO_MUTE</b><TD>The audio is muted</TD>
+<TR><TD><b>VIDEO_AUDIO_MUTABLE</b><TD>Audio muting is supported</TD>
+<TR><TD><b>VIDEO_AUDIO_VOLUME</b><TD>The volume is controllable</TD>
+<TR><TD><b>VIDEO_AUDIO_BASS</b><TD>The bass is controllable</TD>
+<TR><TD><b>VIDEO_AUDIO_TREBLE</b><TD>The treble is controllable</TD>
+<TR><TD><b>VIDEO_AUDIO_BALANCE</b><TD>The balance is controllable</TD>
+</TABLE>
+<P>
+The following decoding modes are defined
+<P>
+<TABLE>
+<TR><TD><b>VIDEO_SOUND_MONO</b><TD>Mono signal</TD>
+<TR><TD><b>VIDEO_SOUND_STEREO</b><TD>Stereo signal (NICAM for TV)</TD>
+<TR><TD><b>VIDEO_SOUND_LANG1</b><TD>European TV alternate language 1</TD>
+<TR><TD><b>VIDEO_SOUND_LANG2</b><TD>European TV alternate language 2</TD>
+</TABLE>
+<P>
+<H3>Reading Images</H3>
+Each call to the <b>read</b> syscall returns the next available image from
+the device. It is up to the caller to set the format and then to pass a 
+suitable size buffer and length to the function. Not all devices will support
+read operations.
+<P>
+A second way to handle image capture is via the mmap interface if supported.
+To use the mmap interface a user first sets the desired image size and depth
+properties. Next the VIDIOCGMBUF ioctl is issued. This reports the size
+of buffer to mmap and the offset within the buffer for each frame. The
+number of frames supported is device dependant and may only be one. 
+<P>
+The video_mbuf structure contains the following fields
+<P>
+<TABLE>
+<TR><TD><b>size</b><TD>The number of bytes to map</TD>
+<TR><TD><b>frames</b><TD>The number of frames</TD>
+<TR><TD><b>offsets</b><TD>The offset of each frame</TD>
+</TABLE>
+<P>
+Once the mmap has been made the VIDIOCMCAPTURE ioctl sets the image size
+you wish to use (which should match or be below the initial query size).
+Having done so it will begin capturing to the memory mapped buffer. Whenever
+a buffer is "used" by the program it should called VIDIOCSYNC to free this
+frame up and continue. <em>to add:</em>VIDIOCSYNC takes the frame number
+you are freeing as its argument. When the buffer is unmapped or all the
+buffers are full capture ceases. While capturing to memory the driver will
+make a "best effort" attempt to capture to screen as well if requested. This
+normally means all frames that "miss" memory mapped capture will go to the
+display.
+<P>
+A final ioctl exists to allow a device to obtain related devices if a
+driver has multiple components (for example video0 may not be associated
+with vbi0 which would cause an intercast display program to make a bad
+mistake). The VIDIOCGUNIT ioctl reports the unit numbers of the associated
+devices if any exist. The video_unit structure has the following fields.
+<P>
+<TABLE>
+<TR><TD><b>video</b><TD>Video capture device</TD>
+<TR><TD><b>vbi</b><TD>VBI capture device</TD>
+<TR><TD><b>radio</b><TD>Radio device</TD>
+<TR><TD><b>audio</b><TD>Audio mixer</TD>
+<TR><TD><b>teletext</b><TD>Teletext device</TD>
+</TABLE>
+<P>
+
+</BODY>
+</HTML>
diff --git a/Documentation/video4linux/bttv/CARDS b/Documentation/video4linux/bttv/CARDS
new file mode 100644
index 000000000..0cfd4d72e
--- /dev/null
+++ b/Documentation/video4linux/bttv/CARDS
@@ -0,0 +1,104 @@
+Suppported cards:
+
+
+Bt848/Bt848a/Bt849/Bt878/Bt879 cards
+------------------------------------
+
+All cards with Bt848/Bt848a/Bt849/Bt878/Bt879 and normal Composite/S-VHS inputs
+are supported.
+Teletext and Intercast support (PAL only) via VBI samples decoding in software.
+
+Some cards with additional multiplexing of inputs are only partially 
+supported (unless specifications by the card manufacturer are given).
+
+All other cards only differ by additional components as tuners, sound decoders,
+EEPROMs, teletext decoders ...
+
+Tuner and sound decoder support for Bt878/879 is not fully working yet.
+
+
+MATRIX Vision
+-------------
+
+MV-Delta
+- Bt848A
+- 4 Composite inputs, 1 S-VHS input (shared with 4th composite)
+- EEPROM
+
+http://www.matrix-vision.de/
+
+This card has no tuner but supports all 4 composite (1 shared with an
+S-VHS input) of the Bt848A.
+Very nice card if you only have satellite TV but several tuners connected
+to the card via composite.
+
+Many thanks to Matrix-Vision for giving us 2 cards for free which made
+Bt848a/Bt849 single crytal operation support possible!!!
+
+
+
+Miro/Pinnacle PCTV
+------------------
+
+- Bt848 
+  some (all??) come with 2 crystals for PAL/SECAM and NTSC 
+- PAL, SECAM or NTSC TV tuner (Philips or TEMIC)
+- MSP34xx sound decoder on add on board
+  decoder is supported but AFAIK does not yet work 
+  (other sound MUX setting in GPIO port needed??? somebody who fixed this???)
+- 1 tuner, 1 composite and 1 S-VHS input
+- tuner type is autodetected
+
+http://www.miro.de/
+http://www.miro.com/
+
+
+Many thanks for the free card which made first NTSC support possible back
+in 1997!
+
+
+Hauppauge Win/TV pci
+--------------------
+
+There are many different versions of the Hauppauge cards with different 
+tuners (TV+Radio ...), teletext decoders.
+Note that even cards with same model numbers have (depending on the revision)
+different chips on it.
+
+- Bt848 (and others but always in 2 crystal operation???)
+  newer cards have a Bt878, I2C support for it is still experimental 
+- PAL, SECAM, NTSC or tuner with or without Radio support
+
+e.g.:
+  PAL: 
+  TDA5737: VHF, hyperband and UHF mixer/oscillator for TV and VCR 3-band tuners
+  TSA5522: 1.4 GHz I2C-bus controlled synthesizer, I2C 0xc2-0xc3
+  
+  NTSC:
+  TDA5731: VHF, hyperband and UHF mixer/oscillator for TV and VCR 3-band tuners
+  TSA5518: no datasheet available on Philips site
+- Philips SAA5246 or SAA5284 ( or no) Teletext decoder chip	
+  with buffer RAM (e.g. Winbond W24257AS-35: 32Kx8 CMOS static RAM)
+  SAA5246 (I2C 0x22) is supported
+- 256 bytes EEPROM: Microchip 24LC02B or Philips 8582E2Y 
+  with configuration information
+  I2C address 0xa0 (24LC02B also responds to 0xa2-0xaf)
+- 1 tuner, 1 composite and (depending on model) 1 S-VHS input
+- 14052B: mux for selection of sound source
+- sound decoder: TDA9800, MSP34xx (stereo cards) 
+
+
+AverMedia
+---------
+
+...
+
+
+
+
+
+ 
+
+
+
+
diff --git a/Documentation/video4linux/bttv/CONTRIBUTORS b/Documentation/video4linux/bttv/CONTRIBUTORS
new file mode 100644
index 000000000..cf7d2300a
--- /dev/null
+++ b/Documentation/video4linux/bttv/CONTRIBUTORS
@@ -0,0 +1,20 @@
+Contributors to bttv: 
+
+Michael Chu <mmchu@pobox.com>
+  AverMedia fix and more flexible card recognition
+
+Alan Cox <alan@cymru.net>
+  Video4Linux interface and 2.1.x kernel adaptation
+
+Chris Kleitsch
+  Hardware I2C
+  
+Gerd Knorr <kraxel@cs.tu-berlin.de> 
+  Radio card (ITT sound processor)
+
++ many more (please mail me if you are missing in this list and would
+             like to be mentioned)
+
+
+
+
diff --git a/Documentation/video4linux/bttv/ICs b/Documentation/video4linux/bttv/ICs
new file mode 100644
index 000000000..6b7491336
--- /dev/null
+++ b/Documentation/video4linux/bttv/ICs
@@ -0,0 +1,37 @@
+all boards:
+
+Brooktree Bt848/848A/849/878/879: video capture chip
+
+
+
+Miro PCTV:
+
+Philips or Temic Tuner
+
+
+
+Hauppauge Win/TV pci (version 405):
+
+Microchip 24LC02B or
+Philips 8582E2Y: 256 Byte EEPROM with configuration information
+                 I2C 0xa0-0xa1, (24LC02B also responds to 0xa2-0xaf)
+Philips SAA5246AGP/E: Videotext decoder chip, I2C 0x22-0x23
+TDA9800: sound decoder
+Winbond W24257AS-35: 32Kx8 CMOS static RAM (Videotext buffer mem)
+14052B: analog switch for selection of sound source
+
+PAL: 
+TDA5737: VHF, hyperband and UHF mixer/oscillator for TV and VCR 3-band tuners
+TSA5522: 1.4 GHz I2C-bus controlled synthesizer, I2C 0xc2-0xc3
+
+NTSC:
+TDA5731: VHF, hyperband and UHF mixer/oscillator for TV and VCR 3-band tuners
+TSA5518: no datasheet available on Philips site
+
+
+
+STB TV pci:
+
+???
+if you want better support for STB cards send me info!
+Look at the board! What chips are on it?
diff --git a/Documentation/video4linux/bttv/INSTALL b/Documentation/video4linux/bttv/INSTALL
new file mode 100644
index 000000000..52cac1e6c
--- /dev/null
+++ b/Documentation/video4linux/bttv/INSTALL
@@ -0,0 +1,73 @@
+- Make sure you have a recent 2.0.x kernel (I recommend AT LEAST 2.0.33!)
+  or a recent 2.1.x kernel.
+  Older kernels might lead to problems. 
+
+- Do NOT compile videodev into your kernel!
+  Use the module supplied with bttv.
+
+- Edit "driver/Makefile":
+
+  - If you do NOT have a Miro card:
+    Adjust TUNER to a number between 0 and 7. 
+
+    This number has the following meaning:
+
+    0: Temic PAL tuner
+    1: Philips PAL_I tuner
+    2: Philips NTSC tuner
+    3: Philips SECAM tuner
+    4: no tuner
+    5: Philips PAL tuner
+    6: Temic NTSC tuner
+    7: Temic PAL tuner
+
+    The number corresponds to the number (-1) given at the GPIO port of the
+    Bt848 on Miro cards.
+
+
+  - Adjust CARD to one of the numbers below:
+
+    0: Auto-Detect
+    1: Miro
+    2: Hauppauge
+    3: STB
+    4: Intel
+    5: Diamond
+    6: AVerMedia
+
+
+  - You may have to adjust BTTV_MAJOR to a different number depending on your
+    kernel version. The official number 81 does not work on some setups.
+    But instead of changing it, better update to a newer kernel.
+
+  - If you have a Bt848a or Bt849 on your board you might have to
+    uncomment: -DUSE_PLL 
+
+- do a "make" in the main directory.
+
+If you have Hauppauge card read "README.HAUPPAUGE" before proceeding.
+
+- type "make ins"
+
+  This creates the bttv devices in /dev and installs the bttv module
+
+  Look in the kernel log file (/var/adm/syslog or /var/log/kernel or something
+  else depending on your /etc/syslogd.conf or just call "dmesg")
+  and see what bttv reported (lines starting with "bttv:")
+  If the installation failed and you send e-mail to me always include those
+  lines! Dumps of the insmod output alone do not help at all.
+
+- Start X11 in hi or true color mode 
+  8 bit color is also supported but really ugly!
+  (If you have an S3 card you might have to start X11 before installing
+   the module!)
+
+  If you have Motif or LessTif, "xtvscreen" in the "XTV" directory should
+  have been compiled with the "make" above.
+  Otherwise use the statically linked version which should be available 
+  on the web site you got bttv from.
+  Read the documentation in "XTV" and start xtvscreen.
+
+- make applications by typing "make" in "apps"
+   
+
diff --git a/Documentation/video4linux/bttv/PROBLEMS b/Documentation/video4linux/bttv/PROBLEMS
new file mode 100644
index 000000000..9e0e61d52
--- /dev/null
+++ b/Documentation/video4linux/bttv/PROBLEMS
@@ -0,0 +1,62 @@
+- Start capturing by pressing "c" or by selecting it via a menu!
+
+- Start capturing by pressing "c" or by selecting it via a menu!!!
+
+- The memory of some S3 cards is not recognized right:
+  
+  First of all, if you are not using Xfree-3.2 or newer, upgrade AT LEAST to
+  XFree-3.2A! This solved the problem for most people.
+
+  Start up X11 like this: "XF86_S3 -probeonly" and write down where the
+  linear frame buffer is.
+  If it is different to the address found by bttv install bttv like this:
+  "insmod bttv vidmem=0xfb0"
+  if the linear frame buffer is at 0xfb000000 (i.e. omit the last 5 zeros!)
+
+  Some S3 cards even take up 64MB of memory but only report 32MB to the BIOS.
+  If this 64MB area overlaps the IO memory of the Bt848 you also have to
+  remap this. E.g.: insmod bttv vidmem=0xfb0 remap=0xfa0
+
+  If the videomemory is found at the right place and there are no address
+  conflicts but still no picture (or the computer even crashes.),
+  try disabling features of your PCI chipset in the BIOS Setup.
+
+  Frank Kapahnke <frank@kapahnke.prima.ruhr.de> also reported that problems
+  with his S3 868 went away when he upgraded to XFree 3.2.
+
+
+- I still only get a black picture with my S3 card!
+
+  Even with XFree-3.2A some people have problems with their S3 cards
+  (mostly with Trio 64 but also with some others)
+  Get the free demo version of Accelerated X from www.xinside.com and try
+  bttv with it. bttv seems to work with most S3 cards with Accelerated X.
+  
+  Since I do not know much (better make that almost nothing) about VGA card
+  programming I do not know the reason for this.
+  Looks like XFree does something different when setting up the video memory?
+  Maybe somebody can enlighten me?  
+  Would be nice if somebody could get this to work with XFree since 
+  Accelerated X costs more than some of the grabber cards ... 
+ 
+  Better linear frame buffer support for S3 cards will probably be in
+  XFree 4.0.
+  
+- Grabbing is not switched off when changing consoles with XFree.
+  That's because XFree and some AcceleratedX versions do not send unmap
+  events.
+
+- Some popup windows (e.g. of the window manager) are not refreshed.
+  
+  Disable backing store by starting X with the option "-bs"
+
+- When using 32bpp in XFree or 24+8bpp mode in AccelX 3.1 the system
+  can sometimes lock up if you use more than 1 bt848 card at the same time.
+  You will always get pixel errors when e.g. using more than 1 card in full
+  screen mode. Maybe we need something faster than the PCI bus ...
+
+
+- Some S3 cards and the Matrox Mystique will produce pixel erros with
+  full resolution in 32bit mode.
+
+- Some video cards have problems with Accelerated X 4.1
diff --git a/Documentation/video4linux/bttv/README b/Documentation/video4linux/bttv/README
new file mode 100644
index 000000000..72f4f4b73
--- /dev/null
+++ b/Documentation/video4linux/bttv/README
@@ -0,0 +1,41 @@
+bttv - BT848 frame grabber driver
+
+Copyright (C) 1996,97 Ralph Metzler  (rjkm@thp.uni-koeln.de)
+                    & Marcus Metzler (mocm@thp.uni-koeln.de)
+                    according to GNU GPL in file COPYING.
+
+
+Bttv is a device driver for frame grabber cards using the Bt848 family
+of video decoder chips.
+Among those are the Bt848, Bt848A, Bt849, Bt878 and Bt879.
+The only major differences between the cards by different manufacturers 
+are the types of tuners and extra components on the boards.
+E.g., some cards by Hauppauge have an additional Videotext decoder 
+and/or sound decoder chip.
+Also type (Composite or S-VHS) and number of inputs differ.
+Other Brooktree chips (e.g. the Bt829) or chips by other manufacturers 
+(Philips, Zoran, ...) are NOT supported by bttv.
+
+You can use several cards at the same time.
+Interrupts can be shared with other Bt848 cards or any other drivers
+which allow it.
+The (arbitrary) maximum number of cards is 4 but can be adjusted by
+changing BTTV_MAX at the beginning of bttv.c if you need more.
+(But which board has more than 4 PCI slots plus 1 for the VGA card?)
+
+Bttv is a standard component of all newer 2.1.x kernels.
+This distribution additionally supports 2.0.x kernels and all other
+changes and improvements which did not make it into the kernel version
+yet. 
+It also includes versions of videodev.c, i2.c, tuner.c and others
+which are the same as in the latest 2.1.x kernel but with 2.0.x support.
+A kernel version >2.0.30 is recommended.
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+Although bttv is now used and tested by many people it still might crash your
+computer! Take all precautions to avoid data loss until you are certain
+bttv runs on your setup without problems.
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+The latest version of bttv can be found at:
+http://www.thp.uni-koeln.de/~rjkm/linux/bttv.html
diff --git a/Documentation/video4linux/bttv/README.FIRST b/Documentation/video4linux/bttv/README.FIRST
new file mode 100644
index 000000000..ea68726a6
--- /dev/null
+++ b/Documentation/video4linux/bttv/README.FIRST
@@ -0,0 +1,4 @@
+o Please direct queries about the in kernel version of this driver to
+  Alan Cox first not to Ralph, or better yet join the video4linux mailing
+  list (mail majordomo@phunk.org with "subscribe video4linux")
+
diff --git a/Documentation/video4linux/bttv/README.Hauppauge b/Documentation/video4linux/bttv/README.Hauppauge
new file mode 100644
index 000000000..0076ed8d8
--- /dev/null
+++ b/Documentation/video4linux/bttv/README.Hauppauge
@@ -0,0 +1,29 @@
+The current I2C-Code could by accident overwrite the configuration EEPROM on 
+Hauppauge boards!!! 
+(E.g. the videotext driver and the bt848 driver do not know about each other.
+This might cause unwanted states on the I2C bus which overwrite the EEPROM)
+
+Back up this EEPROM before doing anything else by typing:
+(do this AFTER installing bttv.o with "make ins" but BEFORE starting the
+X application)
+
+make readee
+readee > tvee.h
+
+If you encounter any problems in Windows95 (like "PNP component not found" ...)
+go back into linux, load bttv and type:
+
+make writeee
+writeee
+
+to write the backed up contents.
+If you backed up your EEPROM as described above, this will restore it to its
+original state.
+A detailed description of the meaning of the EEPROM bytes by
+Hauppauge would of course be even more helpful! 
+
+If you have board type 405 and you did not make a backup, my tvee.h file in 
+mytvee.h might be of help.
+
+Forget about all of the above if you do not have a Hauppauge board.
+
diff --git a/Documentation/video4linux/bttv/README.MIRO b/Documentation/video4linux/bttv/README.MIRO
new file mode 100644
index 000000000..e74fc4ab6
--- /dev/null
+++ b/Documentation/video4linux/bttv/README.MIRO
@@ -0,0 +1,3 @@
+The right tuner type should automatically be detected.
+Look in your kernel log files to see which one bttv thinks it is.
+
diff --git a/Documentation/video4linux/bttv/README.PCI b/Documentation/video4linux/bttv/README.PCI
new file mode 100644
index 000000000..1ae8276f1
--- /dev/null
+++ b/Documentation/video4linux/bttv/README.PCI
@@ -0,0 +1,36 @@
+Because some people were asking about the bandwidth the Bt848 might use up
+on the PCI bus I did a little benchmark.
+
+"bonnie -s 200" with a Fireball TM 3.8 Gb using Busmaster DMA on an ASUS P6NP5
+
+without capturing:
+
+              -------Sequential Output-------- ---Sequential Input-- --Random--
+              -Per Char- --Block--- -Rewrite-- -Per Char- --Block--- --Seeks---
+Machine    MB K/sec %CPU K/sec %CPU K/sec %CPU K/sec %CPU K/sec %CPU  /sec %CPU
+          200  5353 76.6  5898 16.9  2363 12.1  5889 51.3  6416 10.2  37.8  0.9
+
+
+while capturing full screen PAL (786x576) with 24bpp:
+
+              -------Sequential Output-------- ---Sequential Input-- --Random--
+              -Per Char- --Block--- -Rewrite-- -Per Char- --Block--- --Seeks---
+Machine    MB K/sec %CPU K/sec %CPU K/sec %CPU K/sec %CPU K/sec %CPU  /sec %CPU
+          200  5619 69.3  5939 16.9  2334 12.0  5859 50.9  6441 10.5  37.9  0.9
+
+The differences are small and probably within the normal error margin of
+bonnie.
+So, one bt848 card does not have much(any?) impact on the normal operation 
+of a Linux system.
+If you have several cards running this will look very differently!
+The same is probably true if your Linux box is used as a file server 
+with 15 (or 30) SCSI drives.
+ 
+I tested having 2 Bt848 cards grabbing in 32 bit mode (That's almost 100MB/s!)
+while running bonnie.
+The xtvscreen windows showed severe pixel errors.
+After a while the ide driver failed to use DMA and switched DMA off.
+It continued running but the results where bad.
+
+
+
diff --git a/Documentation/video4linux/bttv/README.RADIO b/Documentation/video4linux/bttv/README.RADIO
new file mode 100644
index 000000000..53d04f59b
--- /dev/null
+++ b/Documentation/video4linux/bttv/README.RADIO
@@ -0,0 +1,15 @@
+Support is in now:
+  - Turn on the "big red switch" of the sound processor.
+  - two ioctls to access (some) registers of the sound processor.
+  - a function in the TV-Widget which monitors the signal quality
+    and does the mono/stereo switching.
+
+So you should have TV with (stereo) sound now.  Radio does _not_ work.
+It probably does not work with sat receivers. I can't test this and
+therefore hav'nt added support for it yet. If someone needs this and
+can help testing the sat stuff, drop me a note.
+
+  Gerd
+
+--
+Gerd Knorr <kraxel@cs.tu-berlin.de>
diff --git a/Documentation/video4linux/bttv/THANKS b/Documentation/video4linux/bttv/THANKS
new file mode 100644
index 000000000..0da6d9f8e
--- /dev/null
+++ b/Documentation/video4linux/bttv/THANKS
@@ -0,0 +1,24 @@
+Many thanks to:
+
+- Markus Schroeder <schroedm@uni-duesseldorf.de> for information on the Bt848 
+  and tuner programming and his control program xtvc.
+
+- Martin Buck <martin-2.buck@student.uni-ulm.de> for his great Videotext
+  package.
+
+- Gerd Knorr <kraxel@cs.tu-berlin.de> for the MSP3400 support and the modular
+  I2C, tuner, ... support.
+
+
+- MATRIX Vision for giving us 2 cards for free, which made support of
+  single crystal operation possible.
+
+- MIRO for providing a free PCTV card and detailed information about the
+  components on their cards. (E.g. how the tuner type is detected)
+  Without their card I could not have debugged the NTSC mode.
+	
+- Hauppauge for telling how the sound input is selected and what compenents
+  they do and will use on their radio cards.
+  Also many thanks for faxing me the FM1216 data sheet.
+
+
diff --git a/Documentation/video4linux/radiotrack.txt b/Documentation/video4linux/radiotrack.txt
new file mode 100644
index 000000000..fe942e8a9
--- /dev/null
+++ b/Documentation/video4linux/radiotrack.txt
@@ -0,0 +1,147 @@
+NOTES ON RADIOTRACK CARD CONTROL
+by Stephen M. Benoit (benoits@servicepro.com)  Dec 14, 1996
+----------------------------------------------------------------------------
+
+Document version 1.0
+
+ACKNOWLEDGMENTS
+----------------
+This document was made based on 'C' code for Linux from Gideon le Grange
+(legrang@active.co.za or legrang@cs.sun.ac.za) in 1994, and elaborations from
+Frans Brinkman (brinkman@esd.nl) in 1996.  The results reported here are from
+experiments that the author performed on his own setup, so your mileage may
+vary... I make no guarantees, claims or warrantees to the suitability or
+validity of this information.  No other documentation on the AIMS
+Lab (http://www.aimslab.com/) RadioTrack card was made available to the
+author.  This document is offered in the hopes that it might help users who
+want to use the RadioTrack card in an environment other than MS Windows.
+
+WHY THIS DOCUMENT?
+------------------
+I have a RadioTrack card from back when I ran an MS-Windows platform.  After
+converting to Linux, I found Gideon le Grange's command-line software for
+running the card, and found that it was good!  Frans Brinkman made a
+comfortable X-windows interface, and added a scanning feature.  For hack
+value, I wanted to see if the tuner could be tuned beyond the usual FM radio
+broadcast band, so I could pick up the audio carriers from North American
+broadcast TV channels, situated just below and above the 87.0-109.0 MHz range.
+I did not get much success, but I learned about programming ioports under
+Linux and gained some insights about the hardware design used for the card.
+
+So, without further delay, here are the details.
+
+
+PHYSICAL DESCRIPTION
+--------------------
+The RadioTrack card is an ISA 8-bit FM radio card.  The radio frequency (RF)
+input is simply an antenna lead, and the output is a power audio signal
+available through a miniature phono plug.  Its RF frequencies of operation are
+more or less limited from 87.0 to 109.0 MHz (the commercial FM broadcast
+band).  Although the registers can be programmed to request frequencies beyond
+these limits, experiments did not give promising results.  The variable
+frequency oscillator (VFO) that demodulates the intermediate frequency (IF)
+signal probably has a small range of useful frequencies, and wraps around or
+gets clipped beyond the limits mentioned above.
+
+
+CONTROLLING THE CARD WITH IOPORT
+--------------------------------
+The RadioTrack (base) ioport is configurable for 0x30c or 0x20c.  Only one
+ioport seems to be involved.  The ioport decoding circuitry must be pretty
+simple, as individual ioport bits are directly matched to specific functions
+(or blocks) of the radio card.  This way, many functions can be changed in
+parallel with one write to the ioport.  The only feedback available through
+the ioports appears to be the "Stereo Detect" bit.
+
+The bits of the ioport are arranged as follows:
+
+  MSb                                                         LSb
++------+------+------+--------+--------+-------+---------+--------+
+| VolA | VolB | ???? | Stereo | Radio  | TuneA | TuneB   | Tune   |
+|  (+) |  (-) |      | Detect | Audio  | (bit) | (latch) | Update |
+|      |      |      | Enable | Enable |       |         | Enable |
++------+------+------+--------+--------+-------+---------+--------+
+
+
+VolA . VolB  [AB......]
+-----------
+0 0 : audio mute
+0 1 : volume +    (some delay required)
+1 0 : volume -    (some delay required)
+1 1 : stay at present volume
+
+Stereo Detect Enable [...S....]
+--------------------
+0 : No Detect
+1 : Detect
+
+  Results available by reading ioport >60 msec after last port write.
+  0xff ==> no stereo detected,  0xfd ==> stereo detected.
+
+Radio to Audio (path) Enable [....R...]
+----------------------------
+0 : Disable path (silence)
+1 : Enable path  (audio produced)
+
+TuneA . TuneB [.....AB.]
+-------------
+0 0 : "zero" bit phase 1
+0 1 : "zero" bit phase 2
+
+1 0 : "one" bit phase 1
+1 1 : "one" bit phase 2
+
+  24-bit code, where bits = (freq*40) + 10486188.
+  The Most Significant 11 bits must be 1010 xxxx 0x0 to be valid.
+  The bits are shifted in LSb first.
+
+Tune Update Enable [.......T]
+------------------
+0 : Tuner held constant
+1 : Tuner updating in progress
+
+
+PROGRAMMING EXAMPLES
+--------------------
+Default:        BASE <-- 0xc8  (current volume, no stereo detect,
+				radio enable, tuner adjust disable)
+
+Card Off:	BASE <-- 0x00  (audio mute, no stereo detect,
+				radio disable, tuner adjust disable)
+
+Card On:	BASE <-- 0x00  (see "Card Off", clears any unfinished business)
+		BASE <-- 0xc8  (see "Default")
+
+Volume Down:    BASE <-- 0x48  (volume down, no stereo detect,
+				radio enable, tuner adjust disable)
+		* wait 10 msec *
+		BASE <-- 0xc8  (see "Default")
+
+Volume Up:      BASE <-- 0x88  (volume up, no stereo detect,
+				radio enable, tuner adjust disable)
+		* wait 10 msec *
+		BASE <-- 0xc8  (see "Default")
+
+Check Stereo:   BASE <-- 0xd8  (current volume, stereo detect,
+				radio enable, tuner adjust disable)
+		* wait 100 msec *
+		x <-- BASE     (read ioport)
+		BASE <-- 0xc8  (see "Default")
+
+		x=0xff ==> "not stereo", x=0xfd ==> "stereo detected"
+
+Set Frequency:  code = (freq*40) + 10486188
+                foreach of the 24 bits in code,
+                (from Least to Most Significant):
+                  to write a "zero" bit,
+                    BASE <-- 0x01  (audio mute, no stereo detect, radio
+				    disable, "zero" bit phase 1, tuner adjust)
+                    BASE <-- 0x03  (audio mute, no stereo detect, radio
+				    disable, "zero" bit phase 2, tuner adjust)
+                  to write a "one" bit,
+                    BASE <-- 0x05  (audio mute, no stereo detect, radio
+				    disable, "one" bit phase 1, tuner adjust)
+                    BASE <-- 0x07  (audio mute, no stereo detect, radio
+				    disable, "one" bit phase 2, tuner adjust)
+
+----------------------------------------------------------------------------
author	Ralf Baechle <ralf@linux-mips.org>	1998-09-19 19:15:08 +0000
committer	Ralf Baechle <ralf@linux-mips.org>	1998-09-19 19:15:08 +0000
commit	03ba4131783cc9e872f8bb26a03f15bc11f27564 (patch)
tree	88db8dba75ae06ba3bad08e42c5e52efc162535c /Documentation/video4linux
parent	257730f99381dd26e10b832fce4c94cae7ac1176 (diff)