1.. SPDX-License-Identifier: GPL-2.0
2
3================================
4vidtv: Virtual Digital TV driver
5================================
6
7Author: Daniel W. S. Almeida <dwlsalmeida@gmail.com>, June 2020.
8
9Background
10----------
11
12Vidtv is a virtual DVB driver that aims to serve as a reference for driver
13writers by serving as a template. It also validates the existing media DVB
14APIs, thus helping userspace application writers.
15
16Currently, 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
38Building vidtv
39--------------
40vidtv is a test driver and thus is **not** enabled by default when
41compiling the kernel.
42
43In order to enable compilation of vidtv:
44
45- Enable **DVB_TEST_DRIVERS**, then
46- Enable **DVB_VIDTV**
47
48When 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
56Running vidtv
57-------------
58When compiled as a module, run::
59
60	modprobe vidtv
61
62That's it! The bridge driver will initialize the tuner and demod drivers as
63part of its own initialization.
64
65By 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
70For satellite systems, the driver simulates an universal extended
71LNBf, with frequencies at Ku-Band, ranging from 10.7 GHz to 12.75 GHz.
72
73You can optionally define some command-line arguments to vidtv.
74
75Command-line arguments to vidtv
76-------------------------------
77Below is a list of all arguments that can be supplied to vidtv:
78
79drop_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
85recover_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
90mock_power_up_delay_msec
91	Simulate a power up delay.  Default: 0.
92
93mock_tune_delay_msec
94	Simulate a tune delay.  Default 0.
95
96vidtv_valid_dvb_t_freqs
97	Valid DVB-T frequencies to simulate, in Hz.
98
99vidtv_valid_dvb_c_freqs
100	Valid DVB-C frequencies to simulate, in Hz.
101
102vidtv_valid_dvb_s_freqs
103	Valid DVB-S/S2 frequencies to simulate at Ku-Band, in kHz.
104
105max_frequency_shift_hz,
106	Maximum shift in HZ allowed when tuning in a channel.
107
108si_period_msec
109	How often to send SI packets.  Default: 40ms.
110
111pcr_period_msec
112	How often to send PCR packets.  Default: 40ms.
113
114mux_rate_kbytes_sec
115	Attempt to maintain this bit rate by inserting TS null packets, if
116	necessary.  Default: 4096.
117
118pcr_pid,
119	PCR PID for all channels.  Default: 0x200.
120
121mux_buf_sz_pkts,
122	Size for the mux buffer in multiples of 188 bytes.
123
124vidtv internal structure
125------------------------
126The kernel modules are split in the following way:
127
128vidtv_tuner.[ch]
129	Implements a fake tuner DVB driver.
130
131vidtv_demod.[ch]
132	Implements a fake demodulator DVB driver.
133
134vidtv_bridge.[ch]
135	Implements a bridge driver.
136
137The MPEG related code is split in the following way:
138
139vidtv_ts.[ch]
140	Code to work with MPEG TS packets, such as TS headers, adaptation
141	fields, PCR packets and NULL packets.
142
143vidtv_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
168vidtv_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
173vidtv_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
177vidtv_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
191vidtv_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
211vidtv_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
230Testing vidtv with v4l-utils
231----------------------------
232
233Using the tools in v4l-utils is a great way to test and inspect the output of
234vidtv. It is hosted here: `v4l-utils Documentation
235<https://linuxtv.org/wiki/index.php/V4l-utils>`_.
236
237From 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
248Start by installing v4l-utils and then modprobing vidtv::
249
250	modprobe dvb_vidtv_bridge
251
252If the driver is OK, it should load and its probing code will run. This will
253pull in the tuner and demod drivers.
254
255Using dvb-fe-tool
256~~~~~~~~~~~~~~~~~
257
258The 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
298This 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
342For 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
346Using dvb-scan
347~~~~~~~~~~~~~~
348
349In order to tune into a channel and read the PSI tables, we can use dvb-scan.
350
351For this, one should provide a configuration file known as a 'scan file',
352here'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
370You can browse scan tables online here: `dvb-scan-tables
371<https://git.linuxtv.org/dtv-scan-tables.git>`_.
372
373Assuming 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
385For more information on dvb-scan, check its documentation online here:
386`dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_.
387
388Using dvb-zap
389~~~~~~~~~~~~~
390
391dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The
392typical use is to tune into a channel and put it into record mode. The example
393below - 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
412The channel can be watched by playing the contents of the stream with some
413player that  recognizes the MPEG-TS format, such as ``mplayer`` or ``vlc``.
414
415By playing the contents of the stream one can visually inspect the workings of
416vidtv, e.g., to play a recorded TS file with::
417
418	$ mplayer music.ts
419
420or, alternatively, running this command on one terminal::
421
422	$ dvbv5-zap -c dvb_channel.conf "beethoven" -P -r &
423
424And, on a second terminal, playing the contents from DVR interface with::
425
426	$ mplayer /dev/dvb/adapter0/dvr0
427
428For more information on dvb-zap check its online documentation here:
429`dvb-zap Documentation
430<https://www.linuxtv.org/wiki/index.php/Dvbv5-zap>`_.
431See also: `zap <https://www.linuxtv.org/wiki/index.php/Zap>`_.
432
433
434What can still be improved in vidtv
435-----------------------------------
436
437Add *debugfs* integration
438~~~~~~~~~~~~~~~~~~~~~~~~~
439
440Although frontend drivers provide DVBv5 statistics via the .read_status
441call, a nice addition would be to make additional statistics available to
442userspace via debugfs, which is a simple-to-use, RAM-based filesystem
443specifically designed for debug purposes.
444
445The logic for this would be implemented on a separate file so as not to
446pollute the frontend driver.  These statistics are driver-specific and can
447be useful during tests.
448
449The Siano driver is one example of a driver using
450debugfs to convey driver-specific statistics to userspace and it can be
451used as a reference.
452
453This should be further enabled and disabled via a Kconfig
454option for convenience.
455
456Add a way to test video
457~~~~~~~~~~~~~~~~~~~~~~~
458
459Currently, vidtv can only encode PCM audio. It would be great to implement
460a barebones version of MPEG-2 video encoding so we can also test video. The
461first place to look into is *ISO 13818-2: Information technology — Generic
462coding of moving pictures and associated audio information — Part 2: Video*,
463which covers the encoding of compressed video in MPEG Transport Streams.
464
465This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg,
466which resides at::
467
468	drivers/media/common/v4l2-tpg/
469
470
471Add white noise simulation
472~~~~~~~~~~~~~~~~~~~~~~~~~~
473
474The vidtv tuner already has code to identify whether the chosen frequency
475is too far away from a table of valid frequencies. For now, this means that
476the demodulator can eventually lose the lock on the signal, since the tuner will
477report a bad signal quality.
478
479A 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
488Functions 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
514