blob: 8eb92264ee047163caa25738a30c09ad04d20fcc [file] [log] [blame]
Johannes Stezenbach776338e2005-06-23 22:02:35 -07001Documentation for dvb-usb-framework module and its devices
2
3Idea behind the dvb-usb-framework
4=================================
5
6In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs and a firmware.
7
8Quite keen I wanted to put the driver (with some quirks of course) into dibusb.
9After reading some specs and doing some USB snooping, it realized, that the
10dibusb-driver would be a complete mess afterwards. So I decided to do it in a
11different way: With the help of a dvb-usb-framework.
12
13The framework provides generic functions (mostly kernel API calls), such as:
14
15- Transport Stream URB handling in conjunction with dvb-demux-feed-control
Patrick Boettcher82ff8962005-07-07 17:58:17 -070016 (bulk and isoc are supported)
Johannes Stezenbach776338e2005-06-23 22:02:35 -070017- 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
Patrick Boettcher82ff8962005-07-07 17:58:17 -070021 controllers)
Johannes Stezenbach776338e2005-06-23 22:02:35 -070022- other functions/methods which can be shared by several drivers (such as
23 functions for bulk-control-commands)
Patrick Boettcher82ff8962005-07-07 17:58:17 -070024- 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.
Johannes Stezenbach776338e2005-06-23 22:02:35 -070027
28The source code of the particular DVB USB devices does just the communication
29with the device via the bus. The connection between the DVB-API-functionality
30is done via callbacks, assigned in a static device-description (struct
31dvb_usb_device) each device-driver has to have.
32
Mauro Carvalho Chehab786baec2012-06-14 16:35:56 -030033For an example have a look in drivers/media/usb/dvb-usb/vp7045*.
Johannes Stezenbach776338e2005-06-23 22:02:35 -070034
35Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the
36ttusb; flexcop-usb already benefits from the generic flexcop-device) to use
37the dvb-usb-lib.
38
39TODO: dynamic enabling and disabling of the pid-filter in regard to number of
40feeds requested.
41
Patrick Boettcher82ff8962005-07-07 17:58:17 -070042Supported devices
Johannes Stezenbach776338e2005-06-23 22:02:35 -070043========================
44
Patrick Boettcher82ff8962005-07-07 17:58:17 -070045See the LinuxTV DVB Wiki at www.linuxtv.org for a complete list of
46cards/drivers/firmwares:
Johannes Stezenbach776338e2005-06-23 22:02:35 -070047
Patrick Boettcher82ff8962005-07-07 17:58:17 -070048http://www.linuxtv.org/wiki/index.php/DVB_USB
Johannes Stezenbach776338e2005-06-23 22:02:35 -070049
500. History & News:
Patrick Boettcher3352e432005-07-07 17:58:34 -070051 2005-06-30 - added support for WideView WT-220U (Thanks to Steve Chang)
Patrick Boettcher82ff8962005-07-07 17:58:17 -070052 2005-05-30 - added basic isochronous support to the dvb-usb-framework
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080053 added support for Conexant Hybrid reference design and Nebula DigiTV USB
Johannes Stezenbach776338e2005-06-23 22:02:35 -070054 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
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080058 TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device.
Johannes Stezenbach776338e2005-06-23 22:02:35 -070059
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
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080067 - first almost working version for HanfTek UMT-010
68 - found out, that Yakumo/HAMA/Typhoon are predecessors of the HanfTek UMT-010
Johannes Stezenbach776338e2005-06-23 22:02:35 -070069 2005-01-10 - refactoring completed, now everything is very delightful
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080070 - 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.
Johannes Stezenbach776338e2005-06-23 22:02:35 -070072 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
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080074 - i2c-probing enabled
Johannes Stezenbach776338e2005-06-23 22:02:35 -070075 2004-12-06 - possibility for demod i2c-address probing
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080076 - new usb IDs (Compro, Artec)
Johannes Stezenbach776338e2005-06-23 22:02:35 -070077 2004-11-23 - merged changes from DiB3000MC_ver2.1
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080078 - revised the debugging
79 - possibility to deliver the complete TS for USB2.0
Johannes Stezenbach776338e2005-06-23 22:02:35 -070080 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)
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080084 - 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)
André Goddard Rosaaf901ca2009-11-14 13:09:05 -020088 2004-09-28 - added support for a new device (Unknown, vendor ID is Hyper-Paltek)
Johannes Stezenbach776338e2005-06-23 22:02:35 -070089 2004-09-20 - added support for a new device (Compro DVB-U2000), thanks
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080090 to Amaury Demol for reporting
91 - changed usb TS transfer method (several urbs, stopping transfer
92 before setting a new pid)
Johannes Stezenbach776338e2005-06-23 22:02:35 -070093 2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080094 to Christian Motschke for reporting
Johannes Stezenbach776338e2005-06-23 22:02:35 -070095 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
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -080099 PLL
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700100 2004-07-12 - figured out, that the driver should also work with the
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -0800101 CTS Portable (Chinese Television System)
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700102 2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -0800103 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
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700106 2004-07-02 - some tuner modifications, v0.1, cleanups, first public
107 2004-06-28 - now using the dvb_dmx_swfilter_packets, everything
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -0800108 runs fine now
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700109 2004-06-27 - able to watch and switching channels (pre-alpha)
Mauro Carvalho Chehab674434c2005-12-12 00:37:28 -0800110 - no section filtering yet
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700111 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
1151. How to use?
1161.1. Firmware
117
Patrick Boettcher3352e432005-07-07 17:58:34 -0700118Most of the USB drivers need to download a firmware to the device before start
119working.
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700120
Patrick Boettcher3352e432005-07-07 17:58:34 -0700121Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware
122you need for your device:
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700123
Patrick Boettcher3352e432005-07-07 17:58:34 -0700124http://www.linuxtv.org/wiki/index.php/DVB_USB
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700125
1261.2. Compiling
127
128Since the driver is in the linux kernel, activating the driver in
129your favorite config-environment should sufficient. I recommend
130to compile the driver as module. Hotplug does the rest.
131
132If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh
133load' afterwards.
134
1351.3. Loading the drivers
136
137Hotplug is able to load the driver, when it is needed (because you plugged
138in the device).
139
140If you want to enable debug output, you have to load the driver manually and
Lucas De Marchi25985ed2011-03-30 22:57:33 -0300141from within the dvb-kernel cvs repository.
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700142
143first have a look, which debug level are available:
144
145modinfo dvb-usb
146modinfo dvb-usb-vp7045
147etc.
148
149modprobe dvb-usb debug=<level>
150modprobe dvb-usb-vp7045 debug=<level>
151etc.
152
153should do the trick.
154
155When the driver is loaded successfully, the firmware file was in
156the right place and the device is connected, the "Power"-LED should be
157turned on.
158
159At 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
161long-term test scenario.
162
1632. 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
1682.1. Adding support for devices
169
170TODO
171
1722.2. USB1.1 Bandwidth limitation
173
174A lot of the currently supported devices are USB1.1 and thus they have a
175maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.
176This is not enough for receiving the complete transport stream of a
177DVB-T channel (which is about 16 MBit/s). Normally this is not a
178problem, if you only want to watch TV (this does not apply for HDTV),
179but watching a channel while recording another channel on the same
180frequency simply does not work very well. This applies to all USB1.1
181DVB-T devices, not just the dvb-usb-devices)
182
183The bug, where the TS is distorted by a heavy usage of the device is gone
184definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are
185working like charm now with VDR. Sometimes I even was able to record a channel
186and watch another one.
187
1882.3. Comments
189
190Patches, comments and suggestions are very very welcome.
191
1923. 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
Patrick Boettcher82ff8962005-07-07 17:58:17 -0700208 Allan Third and Michael Hutchinson for their help to write the Nebula
209 digitv-driver.
210
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700211 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
Patrick Boettcher3352e432005-07-07 17:58:34 -0700218 Steve Chang from WideView for providing information for new devices and
219 firmware files.
220
Patrick Boettcher2d188c62005-07-07 17:58:21 -0700221 Michael Paxton for submitting remote control keymaps.
222
223 Some guys on the linux-dvb mailing list for encouraging me.
Johannes Stezenbach776338e2005-06-23 22:02:35 -0700224
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
John Anthony Kazos Jrbe2a6082007-05-09 08:50:42 +0200231 André Smoktun and Christian Frömmel for supporting me with
Patrick Boettcher82ff8962005-07-07 17:58:17 -0700232 hardware and listening to my problems very patiently.