1 .. SPDX-License-Identifier: GPL-2.0
2
3 ================================
4 vidtv: Virtual Digital TV driver
5 ================================
6
7 Author: Daniel W. S. Almeida <dwlsalmeida@gmail.com>, June 2020.
8
9 Background
10 ----------
11
12 Vidtv is a virtual DVB driver that aims to serve as a reference for driver
13 writers by serving as a template. It also validates the existing media DVB
14 APIs, thus helping userspace application writers.
15
16 Currently, it consists of:
17
18 - A fake tuner driver, which will report a bad signal quality if the chosen
19 frequency is too far away from a table of valid frequencies for a
20 particular delivery system.
21
22 - A fake demod driver, which will constantly poll the fake signal quality
23 returned by the tuner, simulating a device that can lose/reacquire a lock
24 on the signal depending on the CNR levels.
25
26 - A fake bridge driver, which is the module responsible for modprobing the
27 fake tuner and demod modules and implementing the demux logic. This module
28 takes parameters at initialization that will dictate how the simulation
29 behaves.
30
31 - Code responsible for encoding a valid MPEG Transport Stream, which is then
32 passed to the bridge driver. This fake stream contains some hardcoded content.
33 For now, we have a single, audio-only channel containing a single MPEG
34 Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave.
35 Note that this particular encoder was chosen because it is the easiest
36 way to encode PCM audio data in a MPEG Transport Stream.
37
38 Building vidtv
39 --------------
40 vidtv is a test driver and thus is **not** enabled by default when
41 compiling the kernel.
42
43 In order to enable compilation of vidtv:
44
45 - Enable **DVB_TEST_DRIVERS**, then
46 - Enable **DVB_VIDTV**
47
48 When compiled as a module, expect the following .ko files:
49
50 - dvb_vidtv_tuner.ko
51
52 - dvb_vidtv_demod.ko
53
54 - dvb_vidtv_bridge.ko
55
56 Running vidtv
57 -------------
58 When compiled as a module, run::
59
60 modprobe vidtv
61
62 That's it! The bridge driver will initialize the tuner and demod drivers as
63 part of its own initialization.
64
65 By default, it will accept the following frequencies:
66
67 - 474 MHz for DVB-T/T2/C;
68 - 11,362 GHz for DVB-S/S2.
69
70 For satellite systems, the driver simulates an universal extended
71 LNBf, with frequencies at Ku-Band, ranging from 10.7 GHz to 12.75 GHz.
72
73 You can optionally define some command-line arguments to vidtv.
74
75 Command-line arguments to vidtv
76 -------------------------------
77 Below is a list of all arguments that can be supplied to vidtv:
78
79 drop_tslock_prob_on_low_snr
80 Probability of losing the TS lock if the signal quality is bad.
81 This probability be used by the fake demodulator driver to
82 eventually return a status of 0 when the signal quality is not
83 good.
84
85 recover_tslock_prob_on_good_snr:
86 Probability recovering the TS lock when the signal improves. This
87 probability be used by the fake demodulator driver to eventually
88 return a status of 0x1f when/if the signal quality improves.
89
90 mock_power_up_delay_msec
91 Simulate a power up delay. Default: 0.
92
93 mock_tune_delay_msec
94 Simulate a tune delay. Default 0.
95
96 vidtv_valid_dvb_t_freqs
97 Valid DVB-T frequencies to simulate, in Hz.
98
99 vidtv_valid_dvb_c_freqs
100 Valid DVB-C frequencies to simulate, in Hz.
101
102 vidtv_valid_dvb_s_freqs
103 Valid DVB-S/S2 frequencies to simulate at Ku-Band, in kHz.
104
105 max_frequency_shift_hz,
106 Maximum shift in HZ allowed when tuning in a channel.
107
108 si_period_msec
109 How often to send SI packets. Default: 40ms.
110
111 pcr_period_msec
112 How often to send PCR packets. Default: 40ms.
113
114 mux_rate_kbytes_sec
115 Attempt to maintain this bit rate by inserting TS null packets, if
116 necessary. Default: 4096.
117
118 pcr_pid,
119 PCR PID for all channels. Default: 0x200.
120
121 mux_buf_sz_pkts,
122 Size for the mux buffer in multiples of 188 bytes.
123
124 vidtv internal structure
125 ------------------------
126 The kernel modules are split in the following way:
127
128 vidtv_tuner.[ch]
129 Implements a fake tuner DVB driver.
130
131 vidtv_demod.[ch]
132 Implements a fake demodulator DVB driver.
133
134 vidtv_bridge.[ch]
135 Implements a bridge driver.
136
137 The MPEG related code is split in the following way:
138
139 vidtv_ts.[ch]
140 Code to work with MPEG TS packets, such as TS headers, adaptation
141 fields, PCR packets and NULL packets.
142
143 vidtv_psi.[ch]
144 This is the PSI generator. PSI packets contain general information
145 about a MPEG Transport Stream. A PSI generator is needed so
146 userspace apps can retrieve information about the Transport Stream
147 and eventually tune into a (dummy) channel.
148
149 Because the generator is implemented in a separate file, it can be
150 reused elsewhere in the media subsystem.
151
152 Currently vidtv supports working with 5 PSI tables: PAT, PMT,
153 SDT, NIT and EIT.
154
155 The specification for PAT and PMT can be found in *ISO 13818-1:
156 Systems*, while the specification for the SDT, NIT, EIT can be found in *ETSI
157 EN 300 468: Specification for Service Information (SI) in DVB
158 systems*.
159
160 It isn't strictly necessary, but using a real TS file helps when
161 debugging PSI tables. Vidtv currently tries to replicate the PSI
162 structure found in this file: `TS1Globo.ts
163 <https://tsduck.io/streams/brazil-isdb-tb/TS1globo.ts>`_.
164
165 A good way to visualize the structure of streams is by using
166 `DVBInspector <https://sourceforge.net/projects/dvbinspector/>`_.
167
168 vidtv_pes.[ch]
169 Implements the PES logic to convert encoder data into MPEG TS
170 packets. These can then be fed into a TS multiplexer and eventually
171 into userspace.
172
173 vidtv_encoder.h
174 An interface for vidtv encoders. New encoders can be added to this
175 driver by implementing the calls in this file.
176
177 vidtv_s302m.[ch]
178 Implements a S302M encoder to make it possible to insert PCM audio
179 data in the generated MPEG Transport Stream. The relevant
180 specification is available online as *SMPTE 302M-2007: Television -
181 Mapping of AES3 Data into MPEG-2 Transport Stream*.
182
183
184 The resulting MPEG Elementary Stream is conveyed in a private
185 stream with a S302M registration descriptor attached.
186
187 This shall enable passing an audio signal into userspace so it can
188 be decoded and played by media software. The corresponding decoder
189 in ffmpeg is located in 'libavcodec/s302m.c' and is experimental.
190
191 vidtv_channel.[ch]
192 Implements a 'channel' abstraction.
193
194 When vidtv boots, it will create some hardcoded channels:
195
196 #. Their services will be concatenated to populate the SDT.
197
198 #. Their programs will be concatenated to populate the PAT
199
200 #. Their events will be concatenated to populate the EIT
201
202 #. For each program in the PAT, a PMT section will be created
203
204 #. The PMT section for a channel will be assigned its streams.
205
206 #. Every stream will have its corresponding encoder polled in a
207 loop to produce TS packets.
208 These packets may be interleaved by the muxer and then delivered
209 to the bridge.
210
211 vidtv_mux.[ch]
212 Implements a MPEG TS mux, loosely based on the ffmpeg
213 implementation in "libavcodec/mpegtsenc.c"
214
215 The muxer runs a loop which is responsible for:
216
217 #. Keeping track of the amount of time elapsed since the last
218 iteration.
219
220 #. Polling encoders in order to fetch 'elapsed_time' worth of data.
221
222 #. Inserting PSI and/or PCR packets, if needed.
223
224 #. Padding the resulting stream with NULL packets if
225 necessary in order to maintain the chosen bit rate.
226
227 #. Delivering the resulting TS packets to the bridge
228 driver so it can pass them to the demux.
229
230 Testing vidtv with v4l-utils
231 ----------------------------
232
233 Using the tools in v4l-utils is a great way to test and inspect the output of
234 vidtv. It is hosted here: `v4l-utils Documentation
235 <https://linuxtv.org/wiki/index.php/V4l-utils>`_.
236
237 From its webpage::
238
239 The v4l-utils are a series of packages for handling media devices.
240
241 It is hosted at http://git.linuxtv.org/v4l-utils.git, and packaged
242 on most distributions.
243
244 It provides a series of libraries and utilities to be used to
245 control several aspect of the media boards.
246
247
248 Start by installing v4l-utils and then modprobing vidtv::
249
250 modprobe dvb_vidtv_bridge
251
252 If the driver is OK, it should load and its probing code will run. This will
253 pull in the tuner and demod drivers.
254
255 Using dvb-fe-tool
256 ~~~~~~~~~~~~~~~~~
257
258 The first step to check whether the demod loaded successfully is to run::
259
260 $ dvb-fe-tool
261 Device Dummy demod for DVB-T/T2/C/S/S2 (/dev/dvb/adapter0/frontend0) capabilities:
262 CAN_FEC_1_2
263 CAN_FEC_2_3
264 CAN_FEC_3_4
265 CAN_FEC_4_5
266 CAN_FEC_5_6
267 CAN_FEC_6_7
268 CAN_FEC_7_8
269 CAN_FEC_8_9
270 CAN_FEC_AUTO
271 CAN_GUARD_INTERVAL_AUTO
272 CAN_HIERARCHY_AUTO
273 CAN_INVERSION_AUTO
274 CAN_QAM_16
275 CAN_QAM_32
276 CAN_QAM_64
277 CAN_QAM_128
278 CAN_QAM_256
279 CAN_QAM_AUTO
280 CAN_QPSK
281 CAN_TRANSMISSION_MODE_AUTO
282 DVB API Version 5.11, Current v5 delivery system: DVBC/ANNEX_A
283 Supported delivery systems:
284 DVBT
285 DVBT2
286 [DVBC/ANNEX_A]
287 DVBS
288 DVBS2
289 Frequency range for the current standard:
290 From: 51.0 MHz
291 To: 2.15 GHz
292 Step: 62.5 kHz
293 Tolerance: 29.5 MHz
294 Symbol rate ranges for the current standard:
295 From: 1.00 MBauds
296 To: 45.0 MBauds
297
298 This should return what is currently set up at the demod struct, i.e.::
299
300 static const struct dvb_frontend_ops vidtv_demod_ops = {
301 .delsys = {
302 SYS_DVBT,
303 SYS_DVBT2,
304 SYS_DVBC_ANNEX_A,
305 SYS_DVBS,
306 SYS_DVBS2,
307 },
308
309 .info = {
310 .name = "Dummy demod for DVB-T/T2/C/S/S2",
311 .frequency_min_hz = 51 * MHz,
312 .frequency_max_hz = 2150 * MHz,
313 .frequency_stepsize_hz = 62500,
314 .frequency_tolerance_hz = 29500 * kHz,
315 .symbol_rate_min = 1000000,
316 .symbol_rate_max = 45000000,
317
318 .caps = FE_CAN_FEC_1_2 |
319 FE_CAN_FEC_2_3 |
320 FE_CAN_FEC_3_4 |
321 FE_CAN_FEC_4_5 |
322 FE_CAN_FEC_5_6 |
323 FE_CAN_FEC_6_7 |
324 FE_CAN_FEC_7_8 |
325 FE_CAN_FEC_8_9 |
326 FE_CAN_QAM_16 |
327 FE_CAN_QAM_64 |
328 FE_CAN_QAM_32 |
329 FE_CAN_QAM_128 |
330 FE_CAN_QAM_256 |
331 FE_CAN_QAM_AUTO |
332 FE_CAN_QPSK |
333 FE_CAN_FEC_AUTO |
334 FE_CAN_INVERSION_AUTO |
335 FE_CAN_TRANSMISSION_MODE_AUTO |
336 FE_CAN_GUARD_INTERVAL_AUTO |
337 FE_CAN_HIERARCHY_AUTO,
338 }
339
340 ....
341
342 For more information on dvb-fe-tools check its online documentation here:
343 `dvb-fe-tool Documentation
344 <https://www.linuxtv.org/wiki/index.php/Dvb-fe-tool>`_.
345
346 Using dvb-scan
347 ~~~~~~~~~~~~~~
348
349 In order to tune into a channel and read the PSI tables, we can use dvb-scan.
350
351 For this, one should provide a configuration file known as a 'scan file',
352 here's an example::
353
354 [Channel]
355 FREQUENCY = 474000000
356 MODULATION = QAM/AUTO
357 SYMBOL_RATE = 6940000
358 INNER_FEC = AUTO
359 DELIVERY_SYSTEM = DVBC/ANNEX_A
360
361 .. note::
362 The parameters depend on the video standard you're testing.
363
364 .. note::
365 Vidtv is a fake driver and does not validate much of the information
366 in the scan file. Just specifying 'FREQUENCY' and 'DELIVERY_SYSTEM'
367 should be enough for DVB-T/DVB-T2. For DVB-S/DVB-C however, you
368 should also provide 'SYMBOL_RATE'.
369
370 You can browse scan tables online here: `dvb-scan-tables
371 <https://git.linuxtv.org/dtv-scan-tables.git>`_.
372
373 Assuming this channel is named 'channel.conf', you can then run::
374
375 $ dvbv5-scan channel.conf
376 dvbv5-scan ~/vidtv.conf
377 ERROR command BANDWIDTH_HZ (5) not found during retrieve
378 Cannot calc frequency shift. Either bandwidth/symbol-rate is unavailable (yet).
379 Scanning frequency #1 330000000
380 (0x00) Signal= -68.00dBm
381 Scanning frequency #2 474000000
382 Lock (0x1f) Signal= -34.45dBm C/N= 33.74dB UCB= 0
383 Service Beethoven, provider LinuxTV.org: digital television
384
385 For more information on dvb-scan, check its documentation online here:
386 `dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_.
387
388 Using dvb-zap
389 ~~~~~~~~~~~~~
390
391 dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The
392 typical use is to tune into a channel and put it into record mode. The example
393 below - which is taken from the documentation - illustrates that\ [1]_::
394
395 $ dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10
396 using demux 'dvb0.demux0'
397 reading channels from file 'dvb_channel.conf'
398 tuning to 474000000 Hz
399 pass all PID's to TS
400 dvb_set_pesfilter 8192
401 dvb_dev_set_bufsize: buffer set to 6160384
402 Lock (0x1f) Quality= Good Signal= -34.66dBm C/N= 33.41dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0
403 Lock (0x1f) Quality= Good Signal= -34.57dBm C/N= 33.46dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0
404 Record to file 'music.ts' started
405 received 24587768 bytes (2401 Kbytes/sec)
406 Lock (0x1f) Quality= Good Signal= -34.42dBm C/N= 33.89dB UCB= 0 postBER= 0 preBER= 2.44x10^-3 PER= 0
407
408 .. [1] In this example, it records 10 seconds with all program ID's stored
409 at the music.ts file.
410
411
412 The channel can be watched by playing the contents of the stream with some
413 player that recognizes the MPEG-TS format, such as ``mplayer`` or ``vlc``.
414
415 By playing the contents of the stream one can visually inspect the workings of
416 vidtv, e.g., to play a recorded TS file with::
417
418 $ mplayer music.ts
419
420 or, alternatively, running this command on one terminal::
421
422 $ dvbv5-zap -c dvb_channel.conf "beethoven" -P -r &
423
424 And, on a second terminal, playing the contents from DVR interface with::
425
426 $ mplayer /dev/dvb/adapter0/dvr0
427
428 For more information on dvb-zap check its online documentation here:
429 `dvb-zap Documentation
430 <https://www.linuxtv.org/wiki/index.php/Dvbv5-zap>`_.
431 See also: `zap <https://www.linuxtv.org/wiki/index.php/Zap>`_.
432
433
434 What can still be improved in vidtv
435 -----------------------------------
436
437 Add *debugfs* integration
438 ~~~~~~~~~~~~~~~~~~~~~~~~~
439
440 Although frontend drivers provide DVBv5 statistics via the .read_status
441 call, a nice addition would be to make additional statistics available to
442 userspace via debugfs, which is a simple-to-use, RAM-based filesystem
443 specifically designed for debug purposes.
444
445 The logic for this would be implemented on a separate file so as not to
446 pollute the frontend driver. These statistics are driver-specific and can
447 be useful during tests.
448
449 The Siano driver is one example of a driver using
450 debugfs to convey driver-specific statistics to userspace and it can be
451 used as a reference.
452
453 This should be further enabled and disabled via a Kconfig
454 option for convenience.
455
456 Add a way to test video
457 ~~~~~~~~~~~~~~~~~~~~~~~
458
459 Currently, vidtv can only encode PCM audio. It would be great to implement
460 a barebones version of MPEG-2 video encoding so we can also test video. The
461 first place to look into is *ISO 13818-2: Information technology — Generic
462 coding of moving pictures and associated audio information — Part 2: Video*,
463 which covers the encoding of compressed video in MPEG Transport Streams.
464
465 This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg,
466 which resides at::
467
468 drivers/media/common/v4l2-tpg/
469
470
471 Add white noise simulation
472 ~~~~~~~~~~~~~~~~~~~~~~~~~~
473
474 The vidtv tuner already has code to identify whether the chosen frequency
475 is too far away from a table of valid frequencies. For now, this means that
476 the demodulator can eventually lose the lock on the signal, since the tuner will
477 report a bad signal quality.
478
479 A nice addition is to simulate some noise when the signal quality is bad by:
480
481 - Randomly dropping some TS packets. This will trigger a continuity error if the
482 continuity counter is updated but the packet is not passed on to the demux.
483
484 - Updating the error statistics accordingly (e.g. BER, etc).
485
486 - Simulating some noise in the encoded data.
487
488 Functions and structs used within vidtv
489 ---------------------------------------
490
491 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_bridge.h
492
493 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_channel.h
494
495 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_demod.h
496
497 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_encoder.h
498
499 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_mux.h
500
501 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_pes.h
502
503 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_psi.h
504
505 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_s302m.h
506
507 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_ts.h
508
509 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.h
510
511 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_common.c
512
513 .. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.c
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.