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 reponsible 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 3 PSI tables: PAT, PMT and 153 SDT. 154 155 The specification for PAT and PMT can be found in *ISO 13818-1: 156 Systems*, while the specification for the SDT 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 #. For each program in the PAT, a PMT section will be created 201 202 #. The PMT section for a channel will be assigned its streams. 203 204 #. Every stream will have its corresponding encoder polled in a 205 loop to produce TS packets. 206 These packets may be interleaved by the muxer and then delivered 207 to the bridge. 208 209vidtv_mux.[ch] 210 Implements a MPEG TS mux, loosely based on the ffmpeg 211 implementation in "libavcodec/mpegtsenc.c" 212 213 The muxer runs a loop which is responsible for: 214 215 #. Keeping track of the amount of time elapsed since the last 216 iteration. 217 218 #. Polling encoders in order to fetch 'elapsed_time' worth of data. 219 220 #. Inserting PSI and/or PCR packets, if needed. 221 222 #. Padding the resulting stream with NULL packets if 223 necessary in order to maintain the chosen bit rate. 224 225 #. Delivering the resulting TS packets to the bridge 226 driver so it can pass them to the demux. 227 228Testing vidtv with v4l-utils 229---------------------------- 230 231Using the tools in v4l-utils is a great way to test and inspect the output of 232vidtv. It is hosted here: `v4l-utils Documentation 233<https://linuxtv.org/wiki/index.php/V4l-utils>`_. 234 235From its webpage:: 236 237 The v4l-utils are a series of packages for handling media devices. 238 239 It is hosted at http://git.linuxtv.org/v4l-utils.git, and packaged 240 on most distributions. 241 242 It provides a series of libraries and utilities to be used to 243 control several aspect of the media boards. 244 245 246Start by installing v4l-utils and then modprobing vidtv:: 247 248 modprobe dvb_vidtv_bridge 249 250If the driver is OK, it should load and its probing code will run. This will 251pull in the tuner and demod drivers. 252 253Using dvb-fe-tool 254~~~~~~~~~~~~~~~~~ 255 256The first step to check whether the demod loaded successfully is to run:: 257 258 $ dvb-fe-tool 259 260This should return what is currently set up at the demod struct, i.e.:: 261 262 static const struct dvb_frontend_ops vidtv_demod_ops = { 263 .delsys = { 264 SYS_DVBT, 265 SYS_DVBT2, 266 SYS_DVBC_ANNEX_A, 267 SYS_DVBS, 268 SYS_DVBS2, 269 }, 270 271 .info = { 272 .name = "Dummy demod for DVB-T/T2/C/S/S2", 273 .frequency_min_hz = 51 * MHz, 274 .frequency_max_hz = 2150 * MHz, 275 .frequency_stepsize_hz = 62500, 276 .frequency_tolerance_hz = 29500 * kHz, 277 .symbol_rate_min = 1000000, 278 .symbol_rate_max = 45000000, 279 280 .caps = FE_CAN_FEC_1_2 | 281 FE_CAN_FEC_2_3 | 282 FE_CAN_FEC_3_4 | 283 FE_CAN_FEC_4_5 | 284 FE_CAN_FEC_5_6 | 285 FE_CAN_FEC_6_7 | 286 FE_CAN_FEC_7_8 | 287 FE_CAN_FEC_8_9 | 288 FE_CAN_QAM_16 | 289 FE_CAN_QAM_64 | 290 FE_CAN_QAM_32 | 291 FE_CAN_QAM_128 | 292 FE_CAN_QAM_256 | 293 FE_CAN_QAM_AUTO | 294 FE_CAN_QPSK | 295 FE_CAN_FEC_AUTO | 296 FE_CAN_INVERSION_AUTO | 297 FE_CAN_TRANSMISSION_MODE_AUTO | 298 FE_CAN_GUARD_INTERVAL_AUTO | 299 FE_CAN_HIERARCHY_AUTO, 300 } 301 302 .... 303 304For more information on dvb-fe-tools check its online documentation here: 305`dvb-fe-tool Documentation 306<https://www.linuxtv.org/wiki/index.php/Dvb-fe-tool>`_. 307 308Using dvb-scan 309~~~~~~~~~~~~~~ 310 311In order to tune into a channel and read the PSI tables, we can use dvb-scan. 312 313For this, one should provide a configuration file known as a 'scan file', 314here's an example:: 315 316 [Channel] 317 FREQUENCY = 330000000 318 MODULATION = QAM/AUTO 319 SYMBOL_RATE = 6940000 320 INNER_FEC = AUTO 321 DELIVERY_SYSTEM = DVBC/ANNEX_A 322 323.. note:: 324 The parameters depend on the video standard you're testing. 325 326.. note:: 327 Vidtv is a fake driver and does not validate much of the information 328 in the scan file. Just specifying 'FREQUENCY' and 'DELIVERY_SYSTEM' 329 should be enough for DVB-T/DVB-T2. For DVB-S/DVB-C however, you 330 should also provide 'SYMBOL_RATE'. 331 332You can browse scan tables online here: `dvb-scan-tables 333<https://git.linuxtv.org/dtv-scan-tables.git>`_. 334 335Assuming this channel is named 'channel.conf', you can then run:: 336 337 $ dvbv5-scan channel.conf 338 339For more information on dvb-scan, check its documentation online here: 340`dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_. 341 342Using dvb-zap 343~~~~~~~~~~~~~ 344 345dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The 346typical use is to tune into a channel and put it into record mode. The example 347below - which is taken from the documentation - illustrates that:: 348 349 $ dvbv5-zap -c dvb_channel.conf "trilhas sonoras" -r 350 using demux '/dev/dvb/adapter0/demux0' 351 reading channels from file 'dvb_channel.conf' 352 service has pid type 05: 204 353 tuning to 573000000 Hz 354 audio pid 104 355 dvb_set_pesfilter 104 356 Lock (0x1f) Quality= Good Signal= 100.00% C/N= -13.80dB UCB= 70 postBER= 3.14x10^-3 PER= 0 357 DVR interface '/dev/dvb/adapter0/dvr0' can now be opened 358 359The channel can be watched by playing the contents of the DVR interface, with 360some player that recognizes the MPEG-TS format, such as *mplayer* or *vlc*. 361 362By playing the contents of the stream one can visually inspect the workings of 363vidtv, e.g.:: 364 365 $ mplayer /dev/dvb/adapter0/dvr0 366 367For more information on dvb-zap check its online documentation here: 368`dvb-zap Documentation 369<https://www.linuxtv.org/wiki/index.php/Dvbv5-zap>`_. 370See also: `zap <https://www.linuxtv.org/wiki/index.php/Zap>`_. 371 372 373What can still be improved in vidtv 374----------------------------------- 375 376Add *debugfs* integration 377~~~~~~~~~~~~~~~~~~~~~~~~~ 378 379Although frontend drivers provide DVBv5 statistics via the .read_status 380call, a nice addition would be to make additional statistics available to 381userspace via debugfs, which is a simple-to-use, RAM-based filesystem 382specifically designed for debug purposes. 383 384The logic for this would be implemented on a separate file so as not to 385pollute the frontend driver. These statistics are driver-specific and can 386be useful during tests. 387 388The Siano driver is one example of a driver using 389debugfs to convey driver-specific statistics to userspace and it can be 390used as a reference. 391 392This should be further enabled and disabled via a Kconfig 393option for convenience. 394 395Add a way to test video 396~~~~~~~~~~~~~~~~~~~~~~~ 397 398Currently, vidtv can only encode PCM audio. It would be great to implement 399a barebones version of MPEG-2 video encoding so we can also test video. The 400first place to look into is *ISO 13818-2: Information technology — Generic 401coding of moving pictures and associated audio information — Part 2: Video*, 402which covers the encoding of compressed video in MPEG Transport Streams. 403 404This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg, 405which resides at:: 406 407 drivers/media/common/v4l2-tpg/ 408 409 410Add white noise simulation 411~~~~~~~~~~~~~~~~~~~~~~~~~~ 412 413The vidtv tuner already has code to identify whether the chosen frequency 414is too far away from a table of valid frequencies. For now, this means that 415the demodulator can eventually lose the lock on the signal, since the tuner will 416report a bad signal quality. 417 418A nice addition is to simulate some noise when the signal quality is bad by: 419 420- Randomly dropping some TS packets. This will trigger a continuity error if the 421 continuity counter is updated but the packet is not passed on to the demux. 422 423- Updating the error statistics accordingly (e.g. BER, etc). 424 425- Simulating some noise in the encoded data. 426