Documentation/dvb/README.dvb-usb

   1 Documentation for dvb-usb-framework module and its devices
   2
   3 Idea behind the dvb-usb-framework
   4 =================================
   5
   6 In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs and a firmware.
   7
   8 Quite keen I wanted to put the driver (with some quirks of course) into dibusb.
   9 After reading some specs and doing some USB snooping, it realized, that the
  10 dibusb-driver would be a complete mess afterwards. So I decided to do it in a
  11 different way: With the help of a dvb-usb-framework.
  12
  13 The framework provides generic functions (mostly kernel API calls), such as:
  14
  15 - Transport Stream URB handling in conjunction with dvb-demux-feed-control
  16   (bulk and isoc are supported)
  17 - registering the device for the DVB-API
  18 - registering an I2C-adapter if applicable
  19 - remote-control/input-device handling
  20 - firmware requesting and loading (currently just for the Cypress USB
  21   controllers)
  22 - other functions/methods which can be shared by several drivers (such as
  23   functions for bulk-control-commands)
  24 - TODO: a I2C-chunker. It creates device-specific chunks of register-accesses
  25   depending on length of a register and the number of values that can be
  26   multi-written and multi-read.
  27
  28 The source code of the particular DVB USB devices does just the communication
  29 with the device via the bus. The connection between the DVB-API-functionality
  30 is done via callbacks, assigned in a static device-description (struct
  31 dvb_usb_device) each device-driver has to have.
  32
  33 For an example have a look in drivers/media/usb/dvb-usb/vp7045*.
  34
  35 Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the
  36 ttusb; flexcop-usb already benefits from the generic flexcop-device) to use
  37 the dvb-usb-lib.
  38
  39 TODO: dynamic enabling and disabling of the pid-filter in regard to number of
  40 feeds requested.
  41
  42 Supported devices
  43 ========================
  44
  45 See the LinuxTV DVB Wiki at www.linuxtv.org for a complete list of
  46 cards/drivers/firmwares:
  47
  48 http://www.linuxtv.org/wiki/index.php/DVB_USB
  49
  50 0. History & News:
  51   2005-06-30 - added support for WideView WT-220U (Thanks to Steve Chang)
  52   2005-05-30 - added basic isochronous support to the dvb-usb-framework
  53                added support for Conexant Hybrid reference design and Nebula DigiTV USB
  54   2005-04-17 - all dibusb devices ported to make use of the dvb-usb-framework
  55   2005-04-02 - re-enabled and improved remote control code.
  56   2005-03-31 - ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb.
  57   2005-03-30 - first commit of the dvb-usb-module based on the dibusb-source. First device is a new driver for the
  58                TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device.
  59
  60   (change from dvb-dibusb to dvb-usb)
  61   2005-03-28 - added support for the AVerMedia AverTV DVB-T USB2.0 device (Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia)
  62   2005-03-14 - added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0
  63   2005-02-11 - added support for the KWorld/ADSTech Instant DVB-T USB2.0. Thanks a lot to Joachim von Caron
  64   2005-02-02 - added support for the Hauppauge Win-TV Nova-T USB2
  65   2005-01-31 - distorted streaming is gone for USB1.1 devices
  66   2005-01-13 - moved the mirrored pid_filter_table back to dvb-dibusb
  67              - first almost working version for HanfTek UMT-010
  68              - found out, that Yakumo/HAMA/Typhoon are predecessors of the HanfTek UMT-010
  69   2005-01-10 - refactoring completed, now everything is very delightful
  70              - tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a
  71                Panasonic Tuner assembled). Tunerprobing implemented. Thanks a lot to Gunnar Wittich.
  72   2004-12-29 - after several days of struggling around bug of no returning URBs fixed.
  73   2004-12-26 - refactored the dibusb-driver, splitted into separate files
  74              - i2c-probing enabled
  75   2004-12-06 - possibility for demod i2c-address probing
  76              - new usb IDs (Compro, Artec)
  77   2004-11-23 - merged changes from DiB3000MC_ver2.1
  78              - revised the debugging
  79              - possibility to deliver the complete TS for USB2.0
  80   2004-11-21 - first working version of the dib3000mc/p frontend driver.
  81   2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke.
  82   2004-11-07 - added remote control support. Thanks to David Matthews.
  83   2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec)
  84              - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD
  85              - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems
  86                better settled there (added xfer_ops-struct)
  87              - created a common files for frontends (mc/p/mb)
  88   2004-09-28 - added support for a new device (Unknown, vendor ID is Hyper-Paltek)
  89   2004-09-20 - added support for a new device (Compro DVB-U2000), thanks
  90                to Amaury Demol for reporting
  91              - changed usb TS transfer method (several urbs, stopping transfer
  92                before setting a new pid)
  93   2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks
  94                to Christian Motschke for reporting
  95   2004-09-05 - released the dibusb device and dib3000mb-frontend driver
  96
  97   (old news for vp7041.c)
  98   2004-07-15 - found out, by accident, that the device has a TUA6010XS for
  99                PLL
 100   2004-07-12 - figured out, that the driver should also work with the
 101                CTS Portable (Chinese Television System)
 102   2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working
 103                properly with firmware extracted from 2.422
 104              - #if for 2.6.4 (dvb), compile issue
 105              - changed firmware handling, see vp7041.txt sec 1.1
 106   2004-07-02 - some tuner modifications, v0.1, cleanups, first public
 107   2004-06-28 - now using the dvb_dmx_swfilter_packets, everything
 108                runs fine now
 109   2004-06-27 - able to watch and switching channels (pre-alpha)
 110              - no section filtering yet
 111   2004-06-06 - first TS received, but kernel oops :/
 112   2004-05-14 - firmware loader is working
 113   2004-05-11 - start writing the driver
 114
 115 1. How to use?
 116 1.1. Firmware
 117
 118 Most of the USB drivers need to download a firmware to the device before start
 119 working.
 120
 121 Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware
 122 you need for your device:
 123
 124 http://www.linuxtv.org/wiki/index.php/DVB_USB
 125
 126 1.2. Compiling
 127
 128 Since the driver is in the linux kernel, activating the driver in
 129 your favorite config-environment should sufficient. I recommend
 130 to compile the driver as module. Hotplug does the rest.
 131
 132 If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh
 133 load' afterwards.
 134
 135 1.3. Loading the drivers
 136
 137 Hotplug is able to load the driver, when it is needed (because you plugged
 138 in the device).
 139
 140 If you want to enable debug output, you have to load the driver manually and
 141 from within the dvb-kernel cvs repository.
 142
 143 first have a look, which debug level are available:
 144
 145 modinfo dvb-usb
 146 modinfo dvb-usb-vp7045
 147 etc.
 148
 149 modprobe dvb-usb debug=<level>
 150 modprobe dvb-usb-vp7045 debug=<level>
 151 etc.
 152
 153 should do the trick.
 154
 155 When the driver is loaded successfully, the firmware file was in
 156 the right place and the device is connected, the "Power"-LED should be
 157 turned on.
 158
 159 At this point you should be able to start a dvb-capable application. I'm use
 160 (t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the
 161 long-term test scenario.
 162
 163 2. Known problems and bugs
 164
 165 - Don't remove the USB device while running an DVB application, your system
 166   will go crazy or die most likely.
 167
 168 2.1. Adding support for devices
 169
 170 TODO
 171
 172 2.2. USB1.1 Bandwidth limitation
 173
 174 A lot of the currently supported devices are USB1.1 and thus they have a
 175 maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.
 176 This is not enough for receiving the complete transport stream of a
 177 DVB-T channel (which is about 16 MBit/s). Normally this is not a
 178 problem, if you only want to watch TV (this does not apply for HDTV),
 179 but watching a channel while recording another channel on the same
 180 frequency simply does not work very well. This applies to all USB1.1
 181 DVB-T devices, not just the dvb-usb-devices)
 182
 183 The bug, where the TS is distorted by a heavy usage of the device is gone
 184 definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are
 185 working like charm now with VDR. Sometimes I even was able to record a channel
 186 and watch another one.
 187
 188 2.3. Comments
 189
 190 Patches, comments and suggestions are very very welcome.
 191
 192 3. Acknowledgements
 193    Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for
 194     providing specs, code and help, on which the dvb-dibusb, dib3000mb and
 195     dib3000mc are based.
 196
 197    David Matthews for identifying a new device type (Artec T1 with AN2235)
 198     and for extending dibusb with remote control event handling. Thank you.
 199
 200    Alex Woods for frequently answering question about usb and dvb
 201     stuff, a big thank you.
 202
 203    Bernd Wagner for helping with huge bug reports and discussions.
 204
 205    Gunnar Wittich and Joachim von Caron for their trust for providing
 206     root-shells on their machines to implement support for new devices.
 207
 208    Allan Third and Michael Hutchinson for their help to write the Nebula
 209     digitv-driver.
 210
 211    Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei
 212     Jung from AVerMedia who kindly provided a special firmware to get the device
 213     up and running in Linux.
 214
 215    Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by
 216         writing the vp7045-driver.
 217
 218    Steve Chang from WideView for providing information for new devices and
 219         firmware files.
 220
 221    Michael Paxton for submitting remote control keymaps.
 222
 223    Some guys on the linux-dvb mailing list for encouraging me.
 224
 225    Peter Schildmann >peter.schildmann-nospam-at-web.de< for his
 226     user-level firmware loader, which saves a lot of time
 227     (when writing the vp7041 driver)
 228
 229    Ulf Hermenau for helping me out with traditional chinese.
 230
 231    André Smoktun and Christian Frömmel for supporting me with
 232     hardware and listening to my problems very patiently.