[PATCH] dvb: Add generalized dvb-usb driver

Documentation for dvb-usb-framework module and its devices

Idea behind the dvb-usb-framework

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

In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs and a firmware.

Quite keen I wanted to put the driver (with some quirks of course) into dibusb.

After reading some specs and doing some USB snooping, it realized, that the

dibusb-driver would be a complete mess afterwards. So I decided to do it in a

different way: With the help of a dvb-usb-framework.

The framework provides generic functions (mostly kernel API calls), such as:

- Transport Stream URB handling in conjunction with dvb-demux-feed-control

  (bulk and isoc (TODO) are supported)

- registering the device for the DVB-API

- registering an I2C-adapter if applicable

- remote-control/input-device handling

- firmware requesting and loading (currently just for the Cypress USB

  controller)

- other functions/methods which can be shared by several drivers (such as

  functions for bulk-control-commands)

The source code of the particular DVB USB devices does just the communication

with the device via the bus. The connection between the DVB-API-functionality

is done via callbacks, assigned in a static device-description (struct

dvb_usb_device) each device-driver has to have.

For an example have a look in drivers/media/dvb/dvb-usb/vp7045*.

Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the

ttusb; flexcop-usb already benefits from the generic flexcop-device) to use

the dvb-usb-lib.

TODO: dynamic enabling and disabling of the pid-filter in regard to number of

feeds requested.

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

- CTS Portable (Chinese Television System) (2)

	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

- 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, AN2235, AN2235 with Panasonic Tuner)

	http://82.161.246.249/products-tvbox.html

- Compro Videomate DVB-U2000 - DVB-T USB (2)

	http://www.comprousa.com/products/vmu2000.htm

- Grandtec USB DVB-T

	http://www.grand.com.tw/

- AVerMedia AverTV DVBT USB

	http://www.avermedia.com/

- DiBcom USB DVB-T reference device (non-public)

Supported devices USB2.0-only

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

- Twinhan MagicBox II

	http://www.twinhan.com/product_terrestrial_7.asp

- TwinhanDTV Alpha

	http://www.twinhan.com/product_terrestrial_8.asp

- DigitalNow TinyUSB 2 DVB-t Receiver

	http://www.digitalnow.com.au/DigitalNow%20tinyUSB2%20Specifications.html

- Hanftek UMT-010

	http://www.globalsources.com/si/6008819757082/ProductDetail/Digital-TV/product_id-100046529

Supported devices USB2.0 and USB1.1

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

- Typhoon/Yakumo/HAMA/Yuan DVB-T mobile USB2.0

	http://www.yakumo.de/produkte/index.php?pid=1&ag=DVB-T

	http://www.yuan.com.tw/en/products/vdo_ub300.html

	http://www.hama.de/portal/articleId*114663/action*2563

	http://www.anubisline.com/english/articlec.asp?id=50502&catid=002

- Artec T1 USB TVBOX (FX2) (2)

- Hauppauge WinTV NOVA-T USB2

	http://www.hauppauge.com/

- KWorld/ADSTech Instant DVB-T USB2.0 (DiB3000M-B)

- DiBcom USB2.0 DVB-T reference device (non-public)

- AVerMedia AverTV A800 DVB-T USB2.0

1) It is working almost - work-in-progress.

2) No test reports received yet.

0. History & News:

  2005-04-17 - all dibusb devices ported to make use of the dvb-usb-framework

  2005-04-02 - re-enabled and improved remote control code.

  2005-03-31 - ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb.

  2005-03-30 - first commit of the dvb-usb-module based on the dibusb-source. First device is a new driver for the

               TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device.

  (change from dvb-dibusb to dvb-usb)

  2005-03-28 - added support for the AVerMedia AverTV DVB-T USB2.0 device (Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia)

  2005-03-14 - added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0

  2005-02-11 - added support for the KWorld/ADSTech Instant DVB-T USB2.0. Thanks a lot to Joachim von Caron

  2005-02-02 - added support for the Hauppauge Win-TV Nova-T USB2

  2005-01-31 - distorted streaming is gone for USB1.1 devices

  2005-01-13 - moved the mirrored pid_filter_table back to dvb-dibusb

             - first almost working version for HanfTek UMT-010

             - found out, that Yakumo/HAMA/Typhoon are predessors of the HanfTek UMT-010

  2005-01-10 - refactoring completed, now everything is very delightful

             - tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a

               Panasonic Tuner assembled). Tunerprobing implemented. Thanks a lot to Gunnar Wittich.

  2004-12-29 - after several days of struggling around bug of no returning URBs fixed.

  2004-12-26 - refactored the dibusb-driver, splitted into separate files

             - i2c-probing enabled

  2004-12-06 - possibility for demod i2c-address probing

             - new usb IDs (Compro, Artec)

  2004-11-23 - merged changes from DiB3000MC_ver2.1

             - revised the debugging

             - possibility to deliver the complete TS for USB2.0

  2004-11-21 - first working version of the dib3000mc/p frontend driver.

  2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke.

  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

             - changed usb TS transfer method (several urbs, stopping transfer

               before setting a new pid)

  2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks

               to Christian Motschke for reporting

  2004-09-05 - released the dibusb device and dib3000mb-frontend driver

  (old news for vp7041.c)

  2004-07-15 - found out, by accident, that the device has a TUA6010XS for

               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

               properly with firmware extracted from 2.422

             - #if for 2.6.4 (dvb), compile issue

             - changed firmware handling, see vp7041.txt sec 1.1

  2004-07-02 - some tuner modifications, v0.1, cleanups, first public

  2004-06-28 - now using the dvb_dmx_swfilter_packets, everything

               runs fine now

  2004-06-27 - able to watch and switching channels (pre-alpha)

             - no section filtering yet

  2004-06-06 - first TS received, but kernel oops :/

  2004-05-14 - firmware loader is working

  2004-05-11 - start writing the driver

1. How to use?

1.1. Firmware

Most of the USB drivers need to download a firmware to start working.

for USB1.1 (AN2135) you need: dvb-usb-dibusb-5.0.0.11.fw

for USB2.0 HanfTek: dvb-usb-umt-010-02.fw

for USB2.0 DiBcom: dvb-usb-dibusb-6.0.0.8.fw

for USB2.0 AVerMedia AverTV DVB-T USB2: dvb-usb-avertv-a800-01.fw

for USB2.0 TwinhanDTV Alpha/MagicBox II: dvb-usb-vp7045-01.fw

The files can be found on http://www.linuxtv.org/download/firmware/ .

We do not have the permission (yet) to publish the following firmware-files.

You'll need to extract them from the windows drivers.

You should be able to use "get_dvb_firmware dvb-usb" to get the firmware:

for USB1.1 (AN2235) (a few Artec T1 devices): dvb-usb-dibusb-an2235-01.fw

for USB2.0 Hauppauge: dvb-usb-nova-t-usb2-01.fw

for USB2.0 ADSTech/Kworld USB2.0: dvb-usb-adstech-usb2-01.fw

for USB2.0 Yakumo/Typhoon/Hama: dvb-usb-dtt200u-01.fw

1.2. Compiling

Since the driver is in the linux kernel, activating the driver in

your favorite config-environment should sufficient. I recommend

to compile the driver as module. Hotplug does the rest.

If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh

load' afterwards.

1.3. Loading the drivers

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 and

from withing the dvb-kernel cvs repository.

first have a look, which debug level are available:

modinfo dvb-usb

modinfo dvb-usb-vp7045

etc.

modprobe dvb-usb debug=<level>

modprobe dvb-usb-vp7045 debug=<level>

etc.

should do the trick.

When the driver is loaded successfully, the firmware file was in

the right place and the device is connected, the "Power"-LED should be

turned on.

At this point you should be able to start a dvb-capable application. I'm use

(t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the

long-term test scenario.

2. Known problems and bugs

- Don't remove the USB device while running an DVB application, your system

  will go crazy or die most likely.

2.1. Adding support for devices

TODO

2.2. USB1.1 Bandwidth limitation

A lot of the currently supported devices are USB1.1 and thus they have a

maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.

This is not enough for receiving the complete transport stream of a

DVB-T channel (which is about 16 MBit/s). Normally this is not a

problem, if you only want to watch TV (this does not apply for HDTV),

but watching a channel while recording another channel on the same

frequency simply does not work very well. This applies to all USB1.1

DVB-T devices, not just the dvb-usb-devices)

The bug, where the TS is distorted by a heavy usage of the device is gone

definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are

working like charm now with VDR. Sometimes I even was able to record a channel

and watch another one.

2.3. Comments

Patches, comments and suggestions are very very welcome.

3. Acknowledgements

   Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for

    providing specs, code and help, on which the dvb-dibusb, dib3000mb and

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

   Bernd Wagner for helping with huge bug reports and discussions.

   Gunnar Wittich and Joachim von Caron for their trust for providing

    root-shells on their machines to implement support for new devices.

   Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei

    Jung from AVerMedia who kindly provided a special firmware to get the device

    up and running in Linux.

   Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by

	writing the vp7045-driver.

   Some guys on the linux-dvb mailing list for encouraging me

   Peter Schildmann >peter.schildmann-nospam-at-web.de< for his

    user-level firmware loader, which saves a lot of time

    (when writing the vp7041 driver)

   Ulf Hermenau for helping me out with traditional chinese.

   André Smoktun and Christian Frömmel for supporting me with

    hardware and listening to my problems very patient.

comment "Supported USB Adapters"

	depends on DVB_CORE && USB

source "drivers/media/dvb/dvb-usb/Kconfig"

source "drivers/media/dvb/ttusb-budget/Kconfig"

source "drivers/media/dvb/ttusb-dec/Kconfig"

source "drivers/media/dvb/cinergyT2/Kconfig"

# Makefile for the kernel multimedia device drivers.

#

obj-y        := dvb-core/ frontends/ ttpci/ ttusb-dec/ ttusb-budget/ b2c2/ bt8xx/ cinergyT2/

obj-y        := dvb-core/ frontends/ ttpci/ ttusb-dec/ ttusb-budget/ b2c2/ bt8xx/ cinergyT2/ dvb-usb/

config DVB_USB

	tristate "Support for various USB DVB devices"

	depends on DVB_CORE && USB

	select FW_LOADER

	help

	  By enabling this you will be able to choose the various USB 1.1 and

	  USB2.0 DVB devices.

	  Almost every USB device needs a firmware, please look into

	  <file:Documentation/dvb/README.dvb-usb>

	  Say Y if you own an USB DVB device.

config DVB_USB_DEBUG

	bool "Enable extended debug support for all DVB-USB devices"

	depends on DVB_USB

	help

	  Say Y if you want to enable debuging. See modinfo dvb-usb (and the

	  appropriate drivers) for debug levels.

config DVB_USB_A800

	tristate "AVerMedia AverTV DVB-T USB 2.0 (A800)"

	depends on DVB_USB

	help

	  Say Y here to support the AVerMedia AverTV DVB-T USB 2.0 (A800) receiver.

config DVB_USB_DIBUSB_MB

	tristate "DiBcom USB DVB-T devices (based on the DiB3000M-B) (see help for device list)"

	depends on DVB_USB

	help

	  Support for USB 1.1 and 2.0 DVB-T receivers based on reference designs made by

	  DiBcom (<http://www.dibcom.fr>) equipped with a DiB3000M-B demodulator.

	  Devices supported by this driver:

	    TwinhanDTV USB-Ter (VP7041)

	    TwinhanDTV Magic Box (VP7041e)

	    KWorld/JetWay/ADSTech V-Stream XPERT DTV - DVB-T USB1.1 and USB2.0

	    Hama DVB-T USB1.1-Box

	    DiBcom USB1.1 reference devices (non-public)

	    Ultima Electronic/Artec T1 USB TVBOX

	    Compro Videomate DVB-U2000 - DVB-T USB

	    Grandtec DVB-T USB

	    Avermedia AverTV DVBT USB1.1

	    Artec T1 USB1.1 boxes

	  The VP7041 seems to be identical to "CTS Portable" (Chinese

	  Television System).

	  Say Y if you own such a device and want to use it. You should build it as

	  a module.

config DVB_USB_DIBUSB_MC

	tristate "DiBcom USB DVB-T devices (based on the DiB3000M-C/P) (see help for device list)"

	depends on DVB_USB

	help

	  Support for 2.0 DVB-T receivers based on reference designs made by

	  DiBcom (<http://www.dibcom.fr>) equipped with a DiB3000M-C/P demodulator.

	  Devices supported by this driver:

	    DiBcom USB2.0 reference devices (non-public)

	    Artec T1 USB2.0 boxes

	  Say Y if you own such a device and want to use it. You should build it as

	  a module.

config DVB_USB_UMT_010

	tristate "HanfTek UMT-010 DVB-T USB2.0 support"

	depends on DVB_USB

	help

	  Say Y here to support the HanfTek UMT-010 USB2.0 stick-sized DVB-T receiver.

config DVB_USB_DIGITV

	tristate "Nebula Electronics uDigiTV DVB-T USB2.0 support"

	depends on DVB_USB

	help

	  Say Y here to support the Nebula Electronics uDigitV USB2.0 DVB-T receiver.

config DVB_USB_VP7045

	tristate "TwinhanDTV Alpha/MagicBoxII and DNTV tinyUSB2 DVB-T USB2.0 support"

	depends on DVB_USB

	help

	  Say Y here to support the

	    TwinhanDTV Alpha (stick) (VP-7045),

		TwinhanDTV MagicBox II (VP-7046) and

		DigitalNow TinyUSB 2 DVB-t DVB-T USB2.0 receivers.

config DVB_USB_NOVA_T_USB2

	tristate "Hauppauge WinTV-NOVA-T usb2 DVB-T USB2.0 support"

	depends on DVB_USB

	help

	  Say Y here to support the Hauppauge WinTV-NOVA-T usb2 DVB-T USB2.0 receiver.

config DVB_USB_DTT200U

	tristate "Yakumo/Hama/Typhoon/Yuan DVB-T USB2.0 support"

	depends on DVB_USB

	help

	  Say Y here to support the Yakumo/Hama/Typhoon/Yuan DVB-T USB2.0 receiver.

	  The receivers are also known as DTT200U (Yakumo) and UB300 (Yuan).

dvb-usb-objs = dvb-usb-firmware.o dvb-usb-init.o dvb-usb-urb.o dvb-usb-i2c.o dvb-usb-dvb.o dvb-usb-remote.o

obj-$(CONFIG_DVB_USB) += dvb-usb.o

dvb-usb-vp7045-objs = vp7045.o vp7045-fe.o

obj-$(CONFIG_DVB_USB_VP7045) += dvb-usb-vp7045.o

dvb-usb-dtt200u-objs = dtt200u.o dtt200u-fe.o

obj-$(CONFIG_DVB_USB_DTT200U) += dvb-usb-dtt200u.o

dvb-usb-dibusb-common-objs = dibusb-common.o

dvb-usb-a800-objs = a800.o

obj-$(CONFIG_DVB_USB_A800) += dvb-usb-dibusb-common.o dvb-usb-a800.o

dvb-usb-dibusb-mb-objs = dibusb-mb.o

obj-$(CONFIG_DVB_USB_DIBUSB_MB) += dvb-usb-dibusb-common.o dvb-usb-dibusb-mb.o

dvb-usb-dibusb-mc-objs = dibusb-mc.o

obj-$(CONFIG_DVB_USB_DIBUSB_MC) += dvb-usb-dibusb-common.o dvb-usb-dibusb-mc.o

dvb-usb-nova-t-usb2-objs = nova-t-usb2.o

obj-$(CONFIG_DVB_USB_NOVA_T_USB2) += dvb-usb-dibusb-common.o dvb-usb-nova-t-usb2.o

dvb-usb-umt-010-objs = umt-010.o

obj-$(CONFIG_DVB_USB_UMT_010) += dvb-usb-dibusb-common.o dvb-usb-umt-010.o

dvb-usb-digitv-objs = digitv.o

obj-$(CONFIG_DVB_USB_DIGITV) += dvb-usb-digitv.o

EXTRA_CFLAGS = -Idrivers/media/dvb/dvb-core/ -Idrivers/media/dvb/frontends/