Documentation/media/dvb-drivers/dvb-usb.rst

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