1.. SPDX-License-Identifier: GPL-2.0
2
3Idea 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
13In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs
14and a firmware.
15
16Quite keen I wanted to put the driver (with some quirks of course) into dibusb.
17After reading some specs and doing some USB snooping, it realized, that the
18dibusb-driver would be a complete mess afterwards. So I decided to do it in a
19different way: With the help of a dvb-usb-framework.
20
21The 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
36The source code of the particular DVB USB devices does just the communication
37with the device via the bus. The connection between the DVB-API-functionality
38is done via callbacks, assigned in a static device-description (struct
39dvb_usb_device) each device-driver has to have.
40
41For an example have a look in drivers/media/usb/dvb-usb/vp7045*.
42
43Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the
44ttusb; flexcop-usb already benefits from the generic flexcop-device) to use
45the dvb-usb-lib.
46
47TODO: dynamic enabling and disabling of the pid-filter in regard to number of
48feeds requested.
49
50Supported devices
51-----------------
52
53See the LinuxTV DVB Wiki at https://linuxtv.org for a complete list of
54cards/drivers/firmwares:
55https://linuxtv.org/wiki/index.php/DVB_USB
56
570. 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
224How to use?
225-----------
226
227Firmware
228~~~~~~~~
229
230Most of the USB drivers need to download a firmware to the device before start
231working.
232
233Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware
234you need for your device:
235
236https://linuxtv.org/wiki/index.php/DVB_USB
237
238Compiling
239~~~~~~~~~
240
241Since the driver is in the linux kernel, activating the driver in
242your favorite config-environment should sufficient. I recommend
243to compile the driver as module. Hotplug does the rest.
244
245If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh
246load' afterwards.
247
248Loading the drivers
249~~~~~~~~~~~~~~~~~~~
250
251Hotplug is able to load the driver, when it is needed (because you plugged
252in the device).
253
254If you want to enable debug output, you have to load the driver manually and
255from within the dvb-kernel cvs repository.
256
257first 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
272should do the trick.
273
274When the driver is loaded successfully, the firmware file was in
275the right place and the device is connected, the "Power"-LED should be
276turned on.
277
278At 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
280long-term test scenario.
281
282Known 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
288Adding support for devices
289~~~~~~~~~~~~~~~~~~~~~~~~~~
290
291TODO
292
293USB1.1 Bandwidth limitation
294~~~~~~~~~~~~~~~~~~~~~~~~~~~
295
296A lot of the currently supported devices are USB1.1 and thus they have a
297maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.
298This is not enough for receiving the complete transport stream of a
299DVB-T channel (which is about 16 MBit/s). Normally this is not a
300problem, if you only want to watch TV (this does not apply for HDTV),
301but watching a channel while recording another channel on the same
302frequency simply does not work very well. This applies to all USB1.1
303DVB-T devices, not just the dvb-usb-devices)
304
305The bug, where the TS is distorted by a heavy usage of the device is gone
306definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are
307working like charm now with VDR. Sometimes I even was able to record a channel
308and watch another one.
309
310Comments
311~~~~~~~~
312
313Patches, comments and suggestions are very very welcome.
314
3153. 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.
358