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 65You can optionally define some command-line arguments to vidtv. 66 67Command-line arguments to vidtv 68------------------------------- 69Below is a list of all arguments that can be supplied to vidtv: 70 71drop_tslock_prob_on_low_snr 72 Probability of losing the TS lock if the signal quality is bad. 73 This probability be used by the fake demodulator driver to 74 eventually return a status of 0 when the signal quality is not 75 good. 76 77recover_tslock_prob_on_good_snr: 78 Probability recovering the TS lock when the signal improves. This 79 probability be used by the fake demodulator driver to eventually 80 return a status of 0x1f when/if the signal quality improves. 81 82mock_power_up_delay_msec 83 Simulate a power up delay. Default: 0. 84 85mock_tune_delay_msec 86 Simulate a tune delay. Default 0. 87 88vidtv_valid_dvb_t_freqs 89 Valid DVB-T frequencies to simulate. 90 91vidtv_valid_dvb_c_freqs 92 Valid DVB-C frequencies to simulate. 93 94vidtv_valid_dvb_s_freqs 95 Valid DVB-C frequencies to simulate. 96 97max_frequency_shift_hz, 98 Maximum shift in HZ allowed when tuning in a channel. 99 100si_period_msec 101 How often to send SI packets. Default: 40ms. 102 103pcr_period_msec 104 How often to send PCR packets. Default: 40ms. 105 106mux_rate_kbytes_sec 107 Attempt to maintain this bit rate by inserting TS null packets, if 108 necessary. Default: 4096. 109 110pcr_pid, 111 PCR PID for all channels. Default: 0x200. 112 113mux_buf_sz_pkts, 114 Size for the mux buffer in multiples of 188 bytes. 115 116vidtv internal structure 117------------------------ 118The kernel modules are split in the following way: 119 120vidtv_tuner.[ch] 121 Implements a fake tuner DVB driver. 122 123vidtv_demod.[ch] 124 Implements a fake demodulator DVB driver. 125 126vidtv_bridge.[ch] 127 Implements a bridge driver. 128 129The MPEG related code is split in the following way: 130 131vidtv_ts.[ch] 132 Code to work with MPEG TS packets, such as TS headers, adaptation 133 fields, PCR packets and NULL packets. 134 135vidtv_psi.[ch] 136 This is the PSI generator. PSI packets contain general information 137 about a MPEG Transport Stream. A PSI generator is needed so 138 userspace apps can retrieve information about the Transport Stream 139 and eventually tune into a (dummy) channel. 140 141 Because the generator is implemented in a separate file, it can be 142 reused elsewhere in the media subsystem. 143 144 Currently vidtv supports working with 3 PSI tables: PAT, PMT and 145 SDT. 146 147 The specification for PAT and PMT can be found in *ISO 13818-1: 148 Systems*, while the specification for the SDT can be found in *ETSI 149 EN 300 468: Specification for Service Information (SI) in DVB 150 systems*. 151 152 It isn't strictly necessary, but using a real TS file helps when 153 debugging PSI tables. Vidtv currently tries to replicate the PSI 154 structure found in this file: `TS1Globo.ts 155 <https://tsduck.io/streams/brazil-isdb-tb/TS1globo.ts>`_. 156 157 A good way to visualize the structure of streams is by using 158 `DVBInspector <https://sourceforge.net/projects/dvbinspector/>`_. 159 160vidtv_pes.[ch] 161 Implements the PES logic to convert encoder data into MPEG TS 162 packets. These can then be fed into a TS multiplexer and eventually 163 into userspace. 164 165vidtv_encoder.h 166 An interface for vidtv encoders. New encoders can be added to this 167 driver by implementing the calls in this file. 168 169vidtv_s302m.[ch] 170 Implements a S302M encoder to make it possible to insert PCM audio 171 data in the generated MPEG Transport Stream. The relevant 172 specification is available online as *SMPTE 302M-2007: Television - 173 Mapping of AES3 Data into MPEG-2 Transport Stream*. 174 175 176 The resulting MPEG Elementary Stream is conveyed in a private 177 stream with a S302M registration descriptor attached. 178 179 This shall enable passing an audio signal into userspace so it can 180 be decoded and played by media software. The corresponding decoder 181 in ffmpeg is located in 'libavcodec/s302m.c' and is experimental. 182 183vidtv_channel.[ch] 184 Implements a 'channel' abstraction. 185 186 When vidtv boots, it will create some hardcoded channels: 187 188 #. Their services will be concatenated to populate the SDT. 189 190 #. Their programs will be concatenated to populate the PAT 191 192 #. For each program in the PAT, a PMT section will be created 193 194 #. The PMT section for a channel will be assigned its streams. 195 196 #. Every stream will have its corresponding encoder polled in a 197 loop to produce TS packets. 198 These packets may be interleaved by the muxer and then delivered 199 to the bridge. 200 201vidtv_mux.[ch] 202 Implements a MPEG TS mux, loosely based on the ffmpeg 203 implementation in "libavcodec/mpegtsenc.c" 204 205 The muxer runs a loop which is responsible for: 206 207 #. Keeping track of the amount of time elapsed since the last 208 iteration. 209 210 #. Polling encoders in order to fetch 'elapsed_time' worth of data. 211 212 #. Inserting PSI and/or PCR packets, if needed. 213 214 #. Padding the resulting stream with NULL packets if 215 necessary in order to maintain the chosen bit rate. 216 217 #. Delivering the resulting TS packets to the bridge 218 driver so it can pass them to the demux. 219 220Testing vidtv with v4l-utils 221---------------------------- 222 223Using the tools in v4l-utils is a great way to test and inspect the output of 224vidtv. It is hosted here: `v4l-utils Documentation 225<https://linuxtv.org/wiki/index.php/V4l-utils>`_. 226 227From its webpage:: 228 229 The v4l-utils are a series of packages for handling media devices. 230 231 It is hosted at http://git.linuxtv.org/v4l-utils.git, and packaged 232 on most distributions. 233 234 It provides a series of libraries and utilities to be used to 235 control several aspect of the media boards. 236 237 238Start by installing v4l-utils and then modprobing vidtv:: 239 240 modprobe dvb_vidtv_bridge 241 242If the driver is OK, it should load and its probing code will run. This will 243pull in the tuner and demod drivers. 244 245Using dvb-fe-tool 246~~~~~~~~~~~~~~~~~ 247 248The first step to check whether the demod loaded successfully is to run:: 249 250 $ dvb-fe-tool 251 252This should return what is currently set up at the demod struct, i.e.:: 253 254 static const struct dvb_frontend_ops vidtv_demod_ops = { 255 .delsys = { 256 SYS_DVBT, 257 SYS_DVBT2, 258 SYS_DVBC_ANNEX_A, 259 SYS_DVBS, 260 SYS_DVBS2, 261 }, 262 263 .info = { 264 .name = "Dummy demod for DVB-T/T2/C/S/S2", 265 .frequency_min_hz = 51 * MHz, 266 .frequency_max_hz = 2150 * MHz, 267 .frequency_stepsize_hz = 62500, 268 .frequency_tolerance_hz = 29500 * kHz, 269 .symbol_rate_min = 1000000, 270 .symbol_rate_max = 45000000, 271 272 .caps = FE_CAN_FEC_1_2 | 273 FE_CAN_FEC_2_3 | 274 FE_CAN_FEC_3_4 | 275 FE_CAN_FEC_4_5 | 276 FE_CAN_FEC_5_6 | 277 FE_CAN_FEC_6_7 | 278 FE_CAN_FEC_7_8 | 279 FE_CAN_FEC_8_9 | 280 FE_CAN_QAM_16 | 281 FE_CAN_QAM_64 | 282 FE_CAN_QAM_32 | 283 FE_CAN_QAM_128 | 284 FE_CAN_QAM_256 | 285 FE_CAN_QAM_AUTO | 286 FE_CAN_QPSK | 287 FE_CAN_FEC_AUTO | 288 FE_CAN_INVERSION_AUTO | 289 FE_CAN_TRANSMISSION_MODE_AUTO | 290 FE_CAN_GUARD_INTERVAL_AUTO | 291 FE_CAN_HIERARCHY_AUTO, 292 } 293 294 .... 295 296For more information on dvb-fe-tools check its online documentation here: 297`dvb-fe-tool Documentation 298<https://www.linuxtv.org/wiki/index.php/Dvb-fe-tool>`_. 299 300Using dvb-scan 301~~~~~~~~~~~~~~ 302 303In order to tune into a channel and read the PSI tables, we can use dvb-scan. 304 305For this, one should provide a configuration file known as a 'scan file', 306here's an example:: 307 308 [Channel] 309 FREQUENCY = 330000000 310 MODULATION = QAM/AUTO 311 SYMBOL_RATE = 6940000 312 INNER_FEC = AUTO 313 DELIVERY_SYSTEM = DVBC/ANNEX_A 314 315.. note:: 316 The parameters depend on the video standard you're testing. 317 318.. note:: 319 Vidtv is a fake driver and does not validate much of the information 320 in the scan file. Just specifying 'FREQUENCY' and 'DELIVERY_SYSTEM' 321 should be enough for DVB-T/DVB-T2. For DVB-S/DVB-C however, you 322 should also provide 'SYMBOL_RATE'. 323 324You can browse scan tables online here: `dvb-scan-tables 325<https://git.linuxtv.org/dtv-scan-tables.git>`_. 326 327Assuming this channel is named 'channel.conf', you can then run:: 328 329 $ dvbv5-scan channel.conf 330 331For more information on dvb-scan, check its documentation online here: 332`dvb-scan Documentation <https://www.linuxtv.org/wiki/index.php/Dvbscan>`_. 333 334Using dvb-zap 335~~~~~~~~~~~~~ 336 337dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The 338typical use is to tune into a channel and put it into record mode. The example 339below - which is taken from the documentation - illustrates that:: 340 341 $ dvbv5-zap -c dvb_channel.conf "trilhas sonoras" -r 342 using demux '/dev/dvb/adapter0/demux0' 343 reading channels from file 'dvb_channel.conf' 344 service has pid type 05: 204 345 tuning to 573000000 Hz 346 audio pid 104 347 dvb_set_pesfilter 104 348 Lock (0x1f) Quality= Good Signal= 100.00% C/N= -13.80dB UCB= 70 postBER= 3.14x10^-3 PER= 0 349 DVR interface '/dev/dvb/adapter0/dvr0' can now be opened 350 351The channel can be watched by playing the contents of the DVR interface, with 352some player that recognizes the MPEG-TS format, such as *mplayer* or *vlc*. 353 354By playing the contents of the stream one can visually inspect the workings of 355vidtv, e.g.:: 356 357 $ mplayer /dev/dvb/adapter0/dvr0 358 359For more information on dvb-zap check its online documentation here: 360`dvb-zap Documentation 361<https://www.linuxtv.org/wiki/index.php/Dvbv5-zap>`_. 362See also: `zap <https://www.linuxtv.org/wiki/index.php/Zap>`_. 363 364 365What can still be improved in vidtv 366----------------------------------- 367 368Add *debugfs* integration 369~~~~~~~~~~~~~~~~~~~~~~~~~ 370 371Although frontend drivers provide DVBv5 statistics via the .read_status 372call, a nice addition would be to make additional statistics available to 373userspace via debugfs, which is a simple-to-use, RAM-based filesystem 374specifically designed for debug purposes. 375 376The logic for this would be implemented on a separate file so as not to 377pollute the frontend driver. These statistics are driver-specific and can 378be useful during tests. 379 380The Siano driver is one example of a driver using 381debugfs to convey driver-specific statistics to userspace and it can be 382used as a reference. 383 384This should be further enabled and disabled via a Kconfig 385option for convenience. 386 387Add a way to test video 388~~~~~~~~~~~~~~~~~~~~~~~ 389 390Currently, vidtv can only encode PCM audio. It would be great to implement 391a barebones version of MPEG-2 video encoding so we can also test video. The 392first place to look into is *ISO 13818-2: Information technology — Generic 393coding of moving pictures and associated audio information — Part 2: Video*, 394which covers the encoding of compressed video in MPEG Transport Streams. 395 396This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg, 397which resides at:: 398 399 drivers/media/common/v4l2-tpg/ 400 401 402Add white noise simulation 403~~~~~~~~~~~~~~~~~~~~~~~~~~ 404 405The vidtv tuner already has code to identify whether the chosen frequency 406is too far away from a table of valid frequencies. For now, this means that 407the demodulator can eventually lose the lock on the signal, since the tuner will 408report a bad signal quality. 409 410A nice addition is to simulate some noise when the signal quality is bad by: 411 412- Randomly dropping some TS packets. This will trigger a continuity error if the 413 continuity counter is updated but the packet is not passed on to the demux. 414 415- Updating the error statistics accordingly (e.g. BER, etc). 416 417- Simulating some noise in the encoded data. 418