4dfe812ca33bb8353ce2060ea1e9f4fedc3e372a
[linux-2.6.git] / 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/dvb/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-05-30 - added basic isochronous support to the dvb-usb-framework
52                added support for Conexant Hybrid reference design and Nebula DigiTV USB
53   2005-04-17 - all dibusb devices ported to make use of the dvb-usb-framework
54   2005-04-02 - re-enabled and improved remote control code.
55   2005-03-31 - ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb.
56   2005-03-30 - first commit of the dvb-usb-module based on the dibusb-source. First device is a new driver for the
57                TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device.
58
59   (change from dvb-dibusb to dvb-usb)
60   2005-03-28 - added support for the AVerMedia AverTV DVB-T USB2.0 device (Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia)
61   2005-03-14 - added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0
62   2005-02-11 - added support for the KWorld/ADSTech Instant DVB-T USB2.0. Thanks a lot to Joachim von Caron
63   2005-02-02 - added support for the Hauppauge Win-TV Nova-T USB2
64   2005-01-31 - distorted streaming is gone for USB1.1 devices
65   2005-01-13 - moved the mirrored pid_filter_table back to dvb-dibusb
66              - first almost working version for HanfTek UMT-010
67              - found out, that Yakumo/HAMA/Typhoon are predessors of the HanfTek UMT-010
68   2005-01-10 - refactoring completed, now everything is very delightful
69              - tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a
70                Panasonic Tuner assembled). Tunerprobing implemented. Thanks a lot to Gunnar Wittich.
71   2004-12-29 - after several days of struggling around bug of no returning URBs fixed.
72   2004-12-26 - refactored the dibusb-driver, splitted into separate files
73              - i2c-probing enabled
74   2004-12-06 - possibility for demod i2c-address probing
75              - new usb IDs (Compro, Artec)
76   2004-11-23 - merged changes from DiB3000MC_ver2.1
77              - revised the debugging
78              - possibility to deliver the complete TS for USB2.0
79   2004-11-21 - first working version of the dib3000mc/p frontend driver.
80   2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke.
81   2004-11-07 - added remote control support. Thanks to David Matthews.
82   2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec)
83              - merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD
84              - moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems
85                better settled there (added xfer_ops-struct)
86              - created a common files for frontends (mc/p/mb)
87   2004-09-28 - added support for a new device (Unkown, vendor ID is Hyper-Paltek)
88   2004-09-20 - added support for a new device (Compro DVB-U2000), thanks
89                to Amaury Demol for reporting
90              - changed usb TS transfer method (several urbs, stopping transfer
91                before setting a new pid)
92   2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks
93                to Christian Motschke for reporting
94   2004-09-05 - released the dibusb device and dib3000mb-frontend driver
95
96   (old news for vp7041.c)
97   2004-07-15 - found out, by accident, that the device has a TUA6010XS for
98                PLL
99   2004-07-12 - figured out, that the driver should also work with the
100                CTS Portable (Chinese Television System)
101   2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working
102                properly with firmware extracted from 2.422
103              - #if for 2.6.4 (dvb), compile issue
104              - changed firmware handling, see vp7041.txt sec 1.1
105   2004-07-02 - some tuner modifications, v0.1, cleanups, first public
106   2004-06-28 - now using the dvb_dmx_swfilter_packets, everything
107                runs fine now
108   2004-06-27 - able to watch and switching channels (pre-alpha)
109              - no section filtering yet
110   2004-06-06 - first TS received, but kernel oops :/
111   2004-05-14 - firmware loader is working
112   2004-05-11 - start writing the driver
113
114 1. How to use?
115 1.1. Firmware
116
117 Most of the USB drivers need to download a firmware to start working.
118
119 for USB1.1 (AN2135) you need: dvb-usb-dibusb-5.0.0.11.fw
120 for USB2.0 HanfTek: dvb-usb-umt-010-02.fw
121 for USB2.0 DiBcom: dvb-usb-dibusb-6.0.0.8.fw
122 for USB2.0 AVerMedia AverTV DVB-T USB2: dvb-usb-avertv-a800-01.fw
123 for USB2.0 TwinhanDTV Alpha/MagicBox II: dvb-usb-vp7045-01.fw
124
125 The files can be found on http://www.linuxtv.org/download/firmware/ .
126
127 We do not have the permission (yet) to publish the following firmware-files.
128 You'll need to extract them from the windows drivers.
129
130 You should be able to use "get_dvb_firmware dvb-usb" to get the firmware:
131
132 for USB1.1 (AN2235) (a few Artec T1 devices): dvb-usb-dibusb-an2235-01.fw
133 for USB2.0 Hauppauge: dvb-usb-nova-t-usb2-01.fw
134 for USB2.0 ADSTech/Kworld USB2.0: dvb-usb-adstech-usb2-01.fw
135 for USB2.0 Yakumo/Typhoon/Hama: dvb-usb-dtt200u-01.fw
136
137 1.2. Compiling
138
139 Since the driver is in the linux kernel, activating the driver in
140 your favorite config-environment should sufficient. I recommend
141 to compile the driver as module. Hotplug does the rest.
142
143 If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh
144 load' afterwards.
145
146 1.3. Loading the drivers
147
148 Hotplug is able to load the driver, when it is needed (because you plugged
149 in the device).
150
151 If you want to enable debug output, you have to load the driver manually and
152 from withing the dvb-kernel cvs repository.
153
154 first have a look, which debug level are available:
155
156 modinfo dvb-usb
157 modinfo dvb-usb-vp7045
158 etc.
159
160 modprobe dvb-usb debug=<level>
161 modprobe dvb-usb-vp7045 debug=<level>
162 etc.
163
164 should do the trick.
165
166 When the driver is loaded successfully, the firmware file was in
167 the right place and the device is connected, the "Power"-LED should be
168 turned on.
169
170 At this point you should be able to start a dvb-capable application. I'm use
171 (t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the
172 long-term test scenario.
173
174 2. Known problems and bugs
175
176 - Don't remove the USB device while running an DVB application, your system
177   will go crazy or die most likely.
178
179 2.1. Adding support for devices
180
181 TODO
182
183 2.2. USB1.1 Bandwidth limitation
184
185 A lot of the currently supported devices are USB1.1 and thus they have a
186 maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.
187 This is not enough for receiving the complete transport stream of a
188 DVB-T channel (which is about 16 MBit/s). Normally this is not a
189 problem, if you only want to watch TV (this does not apply for HDTV),
190 but watching a channel while recording another channel on the same
191 frequency simply does not work very well. This applies to all USB1.1
192 DVB-T devices, not just the dvb-usb-devices)
193
194 The bug, where the TS is distorted by a heavy usage of the device is gone
195 definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are
196 working like charm now with VDR. Sometimes I even was able to record a channel
197 and watch another one.
198
199 2.3. Comments
200
201 Patches, comments and suggestions are very very welcome.
202
203 3. Acknowledgements
204    Amaury Demol (ademol@dibcom.fr) and Francois Kanounnikoff from DiBcom for
205     providing specs, code and help, on which the dvb-dibusb, dib3000mb and
206     dib3000mc are based.
207
208    David Matthews for identifying a new device type (Artec T1 with AN2235)
209     and for extending dibusb with remote control event handling. Thank you.
210
211    Alex Woods for frequently answering question about usb and dvb
212     stuff, a big thank you.
213
214    Bernd Wagner for helping with huge bug reports and discussions.
215
216    Gunnar Wittich and Joachim von Caron for their trust for providing
217     root-shells on their machines to implement support for new devices.
218
219    Allan Third and Michael Hutchinson for their help to write the Nebula
220     digitv-driver.
221
222    Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei
223     Jung from AVerMedia who kindly provided a special firmware to get the device
224     up and running in Linux.
225
226    Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by
227         writing the vp7045-driver.
228
229    Michael Paxton for submitting remote control keymaps.
230
231    Some guys on the linux-dvb mailing list for encouraging me.
232
233    Peter Schildmann >peter.schildmann-nospam-at-web.de< for his
234     user-level firmware loader, which saves a lot of time
235     (when writing the vp7041 driver)
236
237    Ulf Hermenau for helping me out with traditional chinese.
238
239    André Smoktun and Christian Frömmel for supporting me with
240     hardware and listening to my problems very patiently.