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