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

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