[PATCH] dvb: documentation update

Start of a big DVB update.


The reasons for revamping the DVB frontend architecture:

Just as analog TV cards, DVB cards need some sort of tuner to tune to the
desired frequency of the digital transponder.  Tuning alone doesn't give you a
digital DVB datastream, however, you need a demodulator as well.  The
combination of tuner and demodulator is called frontend in the DVB world.
Tuner and demodulator are both accessed via the serial i2c bus on all DVB
cards out there.  So, technically a frontend consists of two i2c helper
chipsets.

In former times when there was only a handful of different DVB cards, the
frontend was encapsulated in one tin box.  Some people had the idea that there
should be one "frontend driver" instead of dedicated tuner and demodulator
drivers.  A bad idea.

As time went on, different manufacturers used the same tuner and demodulator
combination, but used a different wiring for the tuner or did other technical
changes.  The only possibility to support different cards with one combined
frontend driver was to add hardware dependent tuner code inside the generic
i2c frontend drivers.  Yuck.

So there was a need for communication between the i2c frontend driver and the
hardware depenedent driver, for example to exchange initialization code for
the tuner.  Unfortunately, the i2c infrastructure is one way, from the i2c
client to the i2c adapter using a non-typesafe ioctl() like interface, which
is ugly by itself.  Greg K-H and others refused the idea to add an iotctl()
like interface from the i2c adapter to the i2c client and instead proposed to
use a typesafe interface instead.  We all agreed with that.

The existing i2c infrastructure heavily depends on the probing facility, ie.
clients probe for their existence on i2c busses.  This is dumb for most i2c
busses out there that sit on dedicated hardware.  A DVB card is uniquely
identified with pci or usb subvendor and subsystem ids, so on that particular
bus we exactly *know* which kinds of i2c helper chipsets sit on there.

Up to now this wasn't a problem, because we could fix all conflicts manually
until half a year ago.  By that date, we found two different DVB designs which
used different demodulators that unfortunately use the same i2c address and
which cannot be distinguished by hardware tricks (ie.  different number of
registers, some fixed hw dependent register,...)

Getting a usable DVB card depended on the load order of the modules, because
the i2c core probed the demodulator drivers one after another and the first
one won the race.  Compiling all drivers statically into the kernel resulted
in non-working cards.

Our solution is as follows: we agreed to keep the basic underlying kernel i2c
infrastructure, but we decided not to register our bussed and chipsets to the
kernel i2c "probing" infrastructure.  Instead, we killed the tuner parts of
the frontend drivers and put them into the dedicated hardware drivers (this is
were they technically belong, they are highly hardware dependent) and we
changed the frontend drivers to pure demodulator drivers (which are hardware
independend).  There is now a type-safe functional dependency between the
drivers and the demodulator drivers, the drivers explicitely ask the
demodulator drivers to attach to their i2c bus.  The only negative aspect of
that approach is that for some hardware there are now more dependencies to
demodulator drivers than needed, ie.  a small amount of memory is wasted.

This patch:

- [DVB] cards.txt: added the USB devices to the card-list
- [DVB] README.dibusb: follow changes in dibusb-driver

Signed-off-by: Michael Hunold <hunold@linuxtv.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

2 files changed, 89 insertions, 31 deletions

diff --git a/Documentation/dvb/README.dibusb b/Documentation/dvb/README.dibusb
index d6449ec80999da..b6d7472fab6e66 100644
--- a/Documentation/dvb/README.dibusb
+++ b/Documentation/dvb/README.dibusb
@@ -1,43 +1,82 @@
+Documentation for dib3000mb frontend driver and dibusb device driver
+====================================================================
 
+Copyright (C) 2004 Patrick Boettcher (patrick.boettcher@desy.de),
 
-Documentation for dib3000mb frontend driver and dibusb device driver
+dibusb and dib3000mb/mc drivers based on GPL code, which has
 
-The drivers should work with
+Copyright (C) 2004 Amaury Demol for DiBcom (ademol@dibcom.fr)
 
-- Twinhan VisionPlus VisionDTV USB-Ter DVB-T Device (VP7041)
-	http://www.twinhan.com/
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation, version 2.
 
-- CTS Portable (Chinese Television System)
-	http://www.2cts.tv/ctsportable/
 
-- KWorld V-Stream XPERT DTV - DVB-T USB
-	http://www.kworld.com.tw/asp/pindex.asp?id=4&pid=13
+Supported devices USB1.1
+========================
+
+Produced and reselled by Twinhan:
+---------------------------------
+- TwinhanDTV USB-Ter DVB-T Device (VP7041)
+	http://www.twinhan.com/product_terrestrial_3.asp
+
+- TwinhanDTV Magic Box (VP7041e)
+	http://www.twinhan.com/product_terrestrial_4.asp
 
 - HAMA DVB-T USB device
 	http://www.hama.de/portal/articleId*110620/action*2598
 
-- DiBcom USB DVB-T reference device
+- CTS Portable (Chinese Television System)
+	http://www.2cts.tv/ctsportable/
+
+- Unknown USB DVB-T device with vendor ID Hyper-Paltek
+
+
+Produced and reselled by KWorld:
+--------------------------------
+- KWorld V-Stream XPERT DTV DVB-T USB
+	http://www.kworld.com.tw/en/product/DVBT-USB/DVBT-USB.html
 
-- Ultima Electronic/Artec T1 USB TVBOX
+- JetWay DTV DVB-T USB
+	http://www.jetway.com.tw/evisn/product/lcd-tv/DVT-USB/dtv-usb.htm
+
+- ADSTech Instant TV DVB-T USB
+	http://www.adstech.com/products/PTV-333/intro/PTV-333_intro.asp?pid=PTV-333
+
+
+Others:
+-------
+- Ultima Electronic/Artec T1 USB TVBOX (AN2135 and AN2235)
 	http://www.arteceuro.com/products-tvbox.html
 
 - Compro Videomate DVB-U2000 - DVB-T USB
 	http://www.comprousa.com/products/vmu2000.htm
 
-- Unknown USB DVB-T device with vendor ID Hyper-Paltek
+- Grandtec USB DVB-T
+	http://www.grand.com.tw/
 
-Copyright (C) 2004 Patrick Boettcher (patrick.boettcher@desy.de),
+- Avermedia AverTV DVBT USB
+	http://www.avermedia.com/
 
-both drivers based on GPL code, which has
+- DiBcom USB DVB-T reference device (non-public)
 
-Copyright (C) 2004 Amaury Demol for DiBcom (ademol@dibcom.fr)
 
-This program is free software; you can redistribute it and/or
-modify it under the terms of the GNU General Public License as
-published by the Free Software Foundation, version 2.
+Supported devices USB2.0
+========================
+- Yakumo DVB-T mobile
+	http://www.yakumo.de/produkte/index.php?pid=1&ag=DVB-T
+
+- DiBcom USB2.0 DVB-T reference device (non-public)
 
 
-NEWS:
+
+0. NEWS:
+  2004-11-07 - added remote control support. Thanks to David Matthews.
+  2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec)
+             - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD
+             - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems
+               better settled there (added xfer_ops-struct)
+             - created a common files for frontends (mc/p/mb)
   2004-09-28 - added support for a new device (Unkown, vendor ID is Hyper-Paltek)
   2004-09-20 - added support for a new device (Compro DVB-U2000), thanks
                to Amaury Demol for reporting
@@ -49,7 +88,7 @@ NEWS:
 
   (old news for vp7041.c)
   2004-07-15 - found out, by accident, that the device has a TUA6010XS for
-               frequency generator
+               PLL
   2004-07-12 - figured out, that the driver should also work with the
                CTS Portable (Chinese Television System)
   2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working
@@ -67,7 +106,7 @@ NEWS:
 
 1. How to use?
 NOTE: This driver was developed using Linux 2.6.6.,
-it is working with 2.6.7, 2.6.8.1.
+it is working with 2.6.7, 2.6.8.1, 2.6.9 .
 
 Linux 2.4.x support is not planned, but patches are very welcome.
 
@@ -81,8 +120,15 @@ The USB driver needs to download a firmware to start working.
 You can either use "get_dvb_firmware dibusb" to download the firmware or you
 can get it directly via
 
+for USB1.1 (AN2135)
 http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-5.0.0.11.fw?rev=1.1&content-type=text/plain
 
+for USB1.1 (AN2235) (a few Artec T1 devices)
+http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-an2235-1.fw?rev=1.1&content-type=text/plain
+
+for USB2.0 (FX2)
+http://linuxtv.org/cgi-bin/cvsweb.cgi/dvb-kernel/firmware/dvb-dibusb-6.0.0.5.fw?rev=1.1&content-type=text/plain
+
 1.2. Compiling
 
 Since the driver is in the linux kernel, activating the driver in
@@ -94,15 +140,16 @@ to compile the driver as module. Hotplug does the rest.
 Hotplug is able to load the driver, when it is needed (because you plugged
 in the device).
 
-If you want to enable debug output, you have to load the driver manually.
+If you want to enable debug output, you have to load the driver manually and
+from withing the dvb-kernel cvs repository.
 
 first have a look, which debug level are available:
 
-modinfo dvb-dibusb
 modinfo dib3000mb
+modinfo dvb-dibusb
 
-modprobe dvb-dibusb debug=<level> 
 modprobe dib3000mb debug=<level>
+modprobe dvb-dibusb debug=<level>
 
 should do the trick.
 
@@ -118,21 +165,19 @@ as a slave device in vdr, was not working for me. Some work has to be done
 2. Known problems and bugs
 
 TODO:
-- remote control tasklet
+- remote control
 - signal-quality and strength calculations
-- debug messages restructure
 - i2c address probing
-- 
 
 2.1. Adding support for devices 
 
 It is not possible to determine the range of devices based on the DiBcom
-reference design. This is because the reference design of DiBcom can be sold
-to third persons, without telling DiBcom (so done with the Twinhan VP7041 and
+reference designs. This is because the reference design of DiBcom can be sold
+to thirds, without telling DiBcom (so done with the Twinhan VP7041 and
 the HAMA device).
 
 When you think you have a device like this and the driver does not recognizes it,
-please send the ****load.inf and the ****cap.inf of the Windows driver to me.
+please send the ****load*.inf and the ****cap*.inf of the Windows driver to me.
 
 Sometimes the Vendor or Product ID is identical to the ones of Twinhan, even
 though it is not a Twinhan device (e.g. HAMA), then please send me the name
@@ -153,6 +198,9 @@ Patches, comments and suggestions are very very welcome
 	providing specs, code and help, on which the dvb-dibusb and dib3000mb are
 	based.
 
+   David Matthews for identifying a new device type (Artec T1 with AN2235)
+    and for extending dibusb with remote control event handling. Thank you.
+
    Alex Woods for frequently answering question about usb and dvb
     stuff, a big thank you
 
diff --git a/Documentation/dvb/cards.txt b/Documentation/dvb/cards.txt
index 43e1a8a9788195..efdc4ee9d40c11 100644
--- a/Documentation/dvb/cards.txt
+++ b/Documentation/dvb/cards.txt
@@ -38,7 +38,7 @@ o Frontends drivers:
                		  Comtech DVBT-6k07 (SP5730 PLL)
                		  (NxtWave Communications NXT6000 demodulator)
    - sp887x		: Microtune 7202D
-   - dib3000mb	: DiBcom 3000-MB Frontend
+   - dib3000mb	: DiBcom 3000-MB demodulator
   DVB-S/C/T:
    - dst		: TwinHan DST Frontend
 
@@ -69,7 +69,17 @@ o Technotrend / Hauppauge DVB USB devices:
 
 o DiBcom DVB-T USB based devices:
   - Twinhan VisionPlus VisionDTV USB-Ter DVB-T Device
-  - KWorld V-Stream XPERT DTV - DVB-T USB
   - HAMA DVB-T USB device
+  - CTS Portable (Chinese Television System)
+  - KWorld V-Stream XPERT DTV DVB-T USB
+  - JetWay DTV DVB-T USB
+  - ADSTech Instant TV DVB-T USB
+  - Ultima Electronic/Artec T1 USB TVBOX (AN2135 and AN2235)
+  - Compro Videomate DVB-U2000 - DVB-T USB
+  - Grandtec USB DVB-T
+  - Avermedia AverTV DVBT USB
+  - DiBcom USB DVB-T reference device (non-public)
+  - Yakumo DVB-T mobile USB2.0
+  - DiBcom USB2.0 DVB-T reference device (non-public)
 
 o Experimental support for the analog module of the Siemens DVB-C PCI card