IMPORTANT:  Don't send me mails with images attached unless I ask you
to do so.  Mails with images attached will go to /dev/null unseen.


Release notes for bttv-0.7.x
============================

This version is based on Ralphs 0.6.4 release.  There are alot of
changes.  Bugfixes, merged patches from other people, merged fixes
from the kernel version, port to the new i2c stack, removed support
for 2.0.x, code cleanups, ...

To compile this bttv version, you'll the new i2c stack.  Kernels
newer than 2.3.34 have this already included.  If you have a older
kernel, download it from:
	http://www.lm-sensors.org/wiki/Download

You'll need at least these config options for bttv:
CONFIG_I2C=m
CONFIG_I2C_ALGOBIT=m
CONFIG_VIDEO_DEV=m

The latest bttv version is available from http://bytesex.org/bttv/

You'll find Ralphs original (mostly outdated) documentation in the
ralphs-doc subdirectory.


Compile bttv
------------

If you are compiling the kernel version, just say 'm' if you are asked
for bttv.  I /strongly/ recommend to compile bttv as module, because
there are some insmod options for configuring the driver.  Starting
with 0.7.49 the most important ones are available as kernel args too.

If you downloaded the separate bttv bundle:  You need configured kernel
sources to compile the bttv driver.  The driver uses some Makefile
magic to compile the modules with your kernel's configuration
(wrt. module-versions, SMP, ...).  If you already have compiled the
kernel at least once, you probably don't have do worry about this.  If
not, go to /usr/src/linux and run at least "make config".  Even
better, compile your own kernel, you'll never become a real hacker
else ;-)
Note that you have to turn on video4linux support (CONFIG_VIDEO_DEV)
in the kernel to get the videodev.o module which is required by bttv.


Make bttv work with your card
-----------------------------

Setup your /etc/modules.conf file and let kmod load the modules.
See also:

Modules.conf:	some sample entries for /etc/modules.conf
Insmod-options:	list of all insmod options available for bttv and
		the helper modules.
MAKEDEV:	a script to create the special files for v4l
CARDLIST:	List of all supported cards
Cards:		more detailed descriptions of known TV cards:
		OEM name variants, used i2c chips, ...
		also includes non-bttv cards.

Loading just the bttv modules isn't enouth for most cards.  The
drivers for the i2c tuner/sound chips must also be loaded.  bttv tries
to load them automagically by calling request_module() now, but this
obviously works only with kmod enabled.

If bttv takes very long to load (happens sometimes with the cheap
cards which have no tuner), try adding this to your modules.conf:
	options i2c-algo-bit bit_test=1

The most important insmod option for bttv is "card=n" to select the
correct card type in case the autodetection does'nt work. If you get
video but no sound you've very likely specified the wrong (or no)
card type.  A list of supported cards is in CARDLIST.

For the WinTV/PVR you need one firmware file from the driver CD:
hcwamc.rbf.  The file is in the pvr45xxx.exe archive (self-extracting
zip file, unzip can unpack it).  Put it into the /etc/pvr directory or
use the firm_altera=<path> insmod option to point the driver to the
location of the file.

If your card isn't listed in CARDLIST or if you have trouble making
audio work, you should read the Sound-FAQ.


Autodetecting cards
-------------------

bttv uses the PCI Subsystem ID to autodetect the card type.  lspci lists
the Subsystem ID in the second line, looks like this:

00:0a.0 Multimedia video controller: Brooktree Corporation Bt878 (rev 02)
        Subsystem: Hauppauge computer works Inc. WinTV/GO
        Flags: bus master, medium devsel, latency 32, IRQ 5
        Memory at e2000000 (32-bit, prefetchable) [size=4K]

only bt878-based cards can have a subsystem ID (which does not mean
that every card really has one).  bt848 cards can't have a Subsystem
ID and therefore can't be autodetected.  There is a list with the ID's
in bttv-cards.c (in case you are intrested or want to mail patches
with updates).

Old driver versions used to have a heuristic which could identify some
bt848-based cards.  It worked for Hauppauge and Miro cards in most
cases (simply because these where the first cards available on the
market), but misdetected other bt848 cards.  That code is gone now for
exactly this reason, the misdetection confused lots of people.  If you
have a old Hauppauge or Miro card, you'll have to load the driver with
card=1 or card=2 these days.


Still doesn't work?
-------------------

I do NOT have a lab with 30+ different grabber boards and a
PAL/NTSC/SECAM test signal generator at home, so I often can't
reproduce your problems.  This makes debugging very difficult for me.
If you have some knowledge and spare time, please try to fix this
yourself (patches very welcome of course...)  You know: The linux
slogan is "Do it yourself".

There is a mailing list: video4linux-list@redhat.com.
https://listman.redhat.com/mailman/listinfo/video4linux-list

If you have trouble with some specific TV card, try to ask there
instead of mailing me directly.  The chance that someone with the
same card listens there is much higher...

For problems with sound:  There are alot of different systems used
for TV sound all over the world.  And there are also different chips
which decode the audio signal.  Reports about sound problems ("stereo
does'nt work") are pretty useless unless you include some details
about your hardware and the TV sound scheme used in your country (or
at least the country you are living in).


Finally: If you mail some patches for bttv around the world (to
linux-kernel/Alan/Linus/...), please Cc: me.


Have fun with bttv,

  Gerd

--
Gerd Knorr <kraxel@goldbach.in-berlin.de>

Support for the Leadtek WinView 601 TV/FM by Jon Tombs <jon@gte.esi.us.es>

This card is basically the same as all the rest (Bt484A, Philips tuner),
the main difference is that they have attached a programmable attenuator to 3
GPIO lines in order to give some volume control. They have also stuck an
infra-red remote control decoded on the board, I will add support for this
when I get time (it simple generates an interrupt for each key press, with
the key code is placed in the GPIO port).

I don't yet have any application to test the radio support. The tuner
frequency setting should work but it is possible that the audio multiplexer
is wrong. If it doesn't work, send me email.


- No Thanks to Leadtek they refused to answer any questions about their
hardware. The driver was written by visual inspection of the card. If you
use this driver, send an email insult to them, and tell them you won't
continue buying their hardware unless they support Linux.

- Little thanks to Princeton Technology Corp (http://www.princeton.com.tw)
who make the audio attenuator. Their publicly available data-sheet available
on their web site doesn't include the chip programming information! Hidden
on their server are the full data-sheets, but don't ask how I found it.

To use the driver I use the following options, the tuner and pll settings might
be different in your country

insmod videodev
insmod i2c scan=1 i2c_debug=0 verbose=0
insmod tuner type=1 debug=0
insmod bttv  pll=1 radio=1 card=17

If the box freezes hard with bttv ...
=====================================

It might be a bttv driver bug.  It also might be bad hardware.  It also
might be something else ...

Just mailing me "bttv freezes" isn't going to help much.  This README
has a few hints how you can help to pin down the problem.


bttv bugs
---------

If some version works and another doesn't it is likely to be a driver
bug.  It is very helpful if you can tell where exactly it broke
(i.e. the last working and the first broken version).

With a hard freeze you probably doesn't find anything in the logfiles.
The only way to capture any kernel messages is to hook up a serial
console and let some terminal application log the messages.  /me uses
screen.  See Documentation/serial-console.txt for details on setting
up a serial console.

Read Documentation/oops-tracing.txt to learn how to get any useful
information out of a register+stack dump printed by the kernel on
protection faults (so-called "kernel oops").

If you run into some kind of deadlock, you can try to dump a call trace
for each process using sysrq-t (see Documentation/sysrq.txt).  ksymoops
will translate these dumps into kernel symbols too.  This way it is
possible to figure where *exactly* some process in "D" state is stuck.

I've seen reports that bttv 0.7.x crashes whereas 0.8.x works rock solid
for some people.  Thus probably a small buglet left somewhere in bttv
0.7.x.  I have no idea where exactly, it works stable for me and alot of
other people.  But in case you have problems with the 0.7.x versions you
can give 0.8.x a try ...


hardware bugs
-------------

Some hardware can't deal with PCI-PCI transfers (i.e. grabber => vga).
Sometimes problems show up with bttv just because of the high load on
the PCI bus. The bt848/878 chips have a few workarounds for known
incompatibilities, see README.quirks.

Some folks report that increasing the pci latency helps too,
althrought I'm not sure whenever this really fixes the problems or
only makes it less likely to happen.  Both bttv and btaudio have a
insmod option to set the PCI latency of the device.

Some mainboard have problems to deal correctly with multiple devices
doing DMA at the same time.  bttv + ide seems to cause this sometimes,
if this is the case you likely see freezes only with video and hard disk
access at the same time.  Updating the IDE driver to get the latest and
greatest workarounds for hardware bugs might fix these problems.


other
-----

If you use some binary-only yunk (like nvidia module) try to reproduce
the problem without.

IRQ sharing is known to cause problems in some cases.  It works just
fine in theory and many configurations.  Neverless it might be worth a
try to shuffle around the PCI cards to give bttv another IRQ or make
it share the IRQ with some other piece of hardware.  IRQ sharing with
VGA cards seems to cause trouble sometimes.  I've also seen funny
effects with bttv sharing the IRQ with the ACPI bridge (and
apci-enabled kernel).

Below is what the bt878 data book says about the PCI bug compatibility
modes of the bt878 chip.

The triton1 insmod option sets the EN_TBFX bit in the control register.
The vsfx insmod option does the same for EN_VSFX bit.  If you have
stability problems you can try if one of these options makes your box
work solid.

drivers/pci/quirks.c knows about these issues, this way these bits are
enabled automagically for known-buggy chipsets (look at the kernel
messages, bttv tells you).

HTH,

  Gerd

---------------------------- cut here --------------------------

Normal PCI Mode
---------------

The PCI REQ signal is the logical-or of the incoming function requests.
The inter-nal GNT[0:1] signals are gated asynchronously with GNT and
demultiplexed by the audio request signal. Thus the arbiter defaults to
the video function at power-up and parks there during no requests for
bus access. This is desirable since the video will request the bus more
often. However, the audio will have highest bus access priority. Thus
the audio will have first access to the bus even when issuing a request
after the video request but before the PCI external arbiter has granted
access to the Bt879. Neither function can preempt the other once on the
bus. The duration to empty the entire video PCI FIFO onto the PCI bus is
very short compared to the bus access latency the audio PCI FIFO can
tolerate.


430FX Compatibility Mode
------------------------

When using the 430FX PCI, the following rules will ensure
compatibility:

 (1) Deassert REQ at the same time as asserting FRAME.
 (2) Do not reassert REQ to request another bus transaction until after
     finish-ing the previous transaction.

Since the individual bus masters do not have direct control of REQ, a
simple logical-or of video and audio requests would violate the rules.
Thus, both the arbiter and the initiator contain 430FX compatibility
mode logic. To enable 430FX mode, set the EN_TBFX bit as indicated in
Device Control Register on page 104.

When EN_TBFX is enabled, the arbiter ensures that the two compatibility
rules are satisfied. Before GNT is asserted by the PCI arbiter, this
internal arbiter may still logical-or the two requests. However, once
the GNT is issued, this arbiter must lock in its decision and now route
only the granted request to the REQ pin. The arbiter decision lock
happens regardless of the state of FRAME because it does not know when
FRAME will be asserted (typically - each initiator will assert FRAME on
the cycle following GNT). When FRAME is asserted, it is the initiator s
responsibility to remove its request at the same time. It is the
arbiters responsibility to allow this request to flow through to REQ and
not allow the other request to hold REQ asserted. The decision lock may
be removed at the end of the transaction: for example, when the bus is
idle (FRAME and IRDY). The arbiter decision may then continue
asynchronously until GNT is again asserted.


Interfacing with Non-PCI 2.1 Compliant Core Logic
-------------------------------------------------

A small percentage of core logic devices may start a bus transaction
during the same cycle that GNT is de-asserted. This is non PCI 2.1
compliant. To ensure compatibility when using PCs with these PCI
controllers, the EN_VSFX bit must be enabled (refer to Device Control
Register on page 104). When in this mode, the arbiter does not pass GNT
to the internal functions unless REQ is asserted. This prevents a bus
transaction from starting the same cycle as GNT is de-asserted. This
also has the side effect of not being able to take advantage of bus
parking, thus lowering arbitration performance. The Bt879 drivers must
query for these non-compliant devices, and set the EN_VSFX bit only if
required.