514 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3================================4vidtv: Virtual Digital TV driver5================================6 7Author: Daniel W. S. Almeida <dwlsalmeida@gmail.com>, June 2020.8 9Background10----------11 12Vidtv is a virtual DVB driver that aims to serve as a reference for driver13writers by serving as a template. It also validates the existing media DVB14APIs, 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 chosen19 frequency is too far away from a table of valid frequencies for a20 particular delivery system.21 22- A fake demod driver, which will constantly poll the fake signal quality23 returned by the tuner, simulating a device that can lose/reacquire a lock24 on the signal depending on the CNR levels.25 26- A fake bridge driver, which is the module responsible for modprobing the27 fake tuner and demod modules and implementing the demux logic. This module28 takes parameters at initialization that will dictate how the simulation29 behaves.30 31- Code responsible for encoding a valid MPEG Transport Stream, which is then32 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 MPEG34 Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave.35 Note that this particular encoder was chosen because it is the easiest36 way to encode PCM audio data in a MPEG Transport Stream.37 38Building vidtv39--------------40vidtv is a test driver and thus is **not** enabled by default when41compiling the kernel.42 43In order to enable compilation of vidtv:44 45- Enable **DVB_TEST_DRIVERS**, then46- Enable **DVB_VIDTV**47 48When compiled as a module, expect the following .ko files:49 50- dvb_vidtv_tuner.ko51 52- dvb_vidtv_demod.ko53 54- dvb_vidtv_bridge.ko55 56Running vidtv57-------------58When compiled as a module, run::59 60 modprobe vidtv61 62That's it! The bridge driver will initialize the tuner and demod drivers as63part 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 extended71LNBf, 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 vidtv76-------------------------------77Below is a list of all arguments that can be supplied to vidtv:78 79drop_tslock_prob_on_low_snr80 Probability of losing the TS lock if the signal quality is bad.81 This probability be used by the fake demodulator driver to82 eventually return a status of 0 when the signal quality is not83 good.84 85recover_tslock_prob_on_good_snr:86 Probability recovering the TS lock when the signal improves. This87 probability be used by the fake demodulator driver to eventually88 return a status of 0x1f when/if the signal quality improves.89 90mock_power_up_delay_msec91 Simulate a power up delay. Default: 0.92 93mock_tune_delay_msec94 Simulate a tune delay. Default 0.95 96vidtv_valid_dvb_t_freqs97 Valid DVB-T frequencies to simulate, in Hz.98 99vidtv_valid_dvb_c_freqs100 Valid DVB-C frequencies to simulate, in Hz.101 102vidtv_valid_dvb_s_freqs103 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_msec109 How often to send SI packets. Default: 40ms.110 111pcr_period_msec112 How often to send PCR packets. Default: 40ms.113 114mux_rate_kbytes_sec115 Attempt to maintain this bit rate by inserting TS null packets, if116 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 structure125------------------------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, adaptation141 fields, PCR packets and NULL packets.142 143vidtv_psi.[ch]144 This is the PSI generator. PSI packets contain general information145 about a MPEG Transport Stream. A PSI generator is needed so146 userspace apps can retrieve information about the Transport Stream147 and eventually tune into a (dummy) channel.148 149 Because the generator is implemented in a separate file, it can be150 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 *ETSI157 EN 300 468: Specification for Service Information (SI) in DVB158 systems*.159 160 It isn't strictly necessary, but using a real TS file helps when161 debugging PSI tables. Vidtv currently tries to replicate the PSI162 structure found in this file: `TS1Globo.ts163 <https://tsduck.io/streams/brazil-isdb-tb/TS1globo.ts>`_.164 165 A good way to visualize the structure of streams is by using166 `DVBInspector <https://sourceforge.net/projects/dvbinspector/>`_.167 168vidtv_pes.[ch]169 Implements the PES logic to convert encoder data into MPEG TS170 packets. These can then be fed into a TS multiplexer and eventually171 into userspace.172 173vidtv_encoder.h174 An interface for vidtv encoders. New encoders can be added to this175 driver by implementing the calls in this file.176 177vidtv_s302m.[ch]178 Implements a S302M encoder to make it possible to insert PCM audio179 data in the generated MPEG Transport Stream. The relevant180 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 private185 stream with a S302M registration descriptor attached.186 187 This shall enable passing an audio signal into userspace so it can188 be decoded and played by media software. The corresponding decoder189 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 PAT199 200 #. Their events will be concatenated to populate the EIT201 202 #. For each program in the PAT, a PMT section will be created203 204 #. The PMT section for a channel will be assigned its streams.205 206 #. Every stream will have its corresponding encoder polled in a207 loop to produce TS packets.208 These packets may be interleaved by the muxer and then delivered209 to the bridge.210 211vidtv_mux.[ch]212 Implements a MPEG TS mux, loosely based on the ffmpeg213 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 last218 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 if225 necessary in order to maintain the chosen bit rate.226 227 #. Delivering the resulting TS packets to the bridge228 driver so it can pass them to the demux.229 230Testing vidtv with v4l-utils231----------------------------232 233Using the tools in v4l-utils is a great way to test and inspect the output of234vidtv. It is hosted here: `v4l-utils Documentation235<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 packaged242 on most distributions.243 244 It provides a series of libraries and utilities to be used to245 control several aspect of the media boards.246 247 248Start by installing v4l-utils and then modprobing vidtv::249 250 modprobe dvb_vidtv_bridge251 252If the driver is OK, it should load and its probing code will run. This will253pull in the tuner and demod drivers.254 255Using dvb-fe-tool256~~~~~~~~~~~~~~~~~257 258The first step to check whether the demod loaded successfully is to run::259 260 $ dvb-fe-tool261 Device Dummy demod for DVB-T/T2/C/S/S2 (/dev/dvb/adapter0/frontend0) capabilities:262 CAN_FEC_1_2263 CAN_FEC_2_3264 CAN_FEC_3_4265 CAN_FEC_4_5266 CAN_FEC_5_6267 CAN_FEC_6_7268 CAN_FEC_7_8269 CAN_FEC_8_9270 CAN_FEC_AUTO271 CAN_GUARD_INTERVAL_AUTO272 CAN_HIERARCHY_AUTO273 CAN_INVERSION_AUTO274 CAN_QAM_16275 CAN_QAM_32276 CAN_QAM_64277 CAN_QAM_128278 CAN_QAM_256279 CAN_QAM_AUTO280 CAN_QPSK281 CAN_TRANSMISSION_MODE_AUTO282 DVB API Version 5.11, Current v5 delivery system: DVBC/ANNEX_A283 Supported delivery systems:284 DVBT285 DVBT2286 [DVBC/ANNEX_A]287 DVBS288 DVBS2289 Frequency range for the current standard:290 From: 51.0 MHz291 To: 2.15 GHz292 Step: 62.5 kHz293 Tolerance: 29.5 MHz294 Symbol rate ranges for the current standard:295 From: 1.00 MBauds296 To: 45.0 MBauds297 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 Documentation344<https://www.linuxtv.org/wiki/index.php/Dvb-fe-tool>`_.345 346Using dvb-scan347~~~~~~~~~~~~~~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 = 474000000356 MODULATION = QAM/AUTO357 SYMBOL_RATE = 6940000358 INNER_FEC = AUTO359 DELIVERY_SYSTEM = DVBC/ANNEX_A360 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 information366 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, you368 should also provide 'SYMBOL_RATE'.369 370You can browse scan tables online here: `dvb-scan-tables371<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.conf376 dvbv5-scan ~/vidtv.conf377 ERROR command BANDWIDTH_HZ (5) not found during retrieve378 Cannot calc frequency shift. Either bandwidth/symbol-rate is unavailable (yet).379 Scanning frequency #1 330000000380 (0x00) Signal= -68.00dBm381 Scanning frequency #2 474000000382 Lock (0x1f) Signal= -34.45dBm C/N= 33.74dB UCB= 0383 Service Beethoven, provider LinuxTV.org: digital television384 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-zap389~~~~~~~~~~~~~390 391dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The392typical use is to tune into a channel and put it into record mode. The example393below - which is taken from the documentation - illustrates that\ [1]_::394 395 $ dvbv5-zap -c dvb_channel.conf "beethoven" -o music.ts -P -t 10396 using demux 'dvb0.demux0'397 reading channels from file 'dvb_channel.conf'398 tuning to 474000000 Hz399 pass all PID's to TS400 dvb_set_pesfilter 8192401 dvb_dev_set_bufsize: buffer set to 6160384402 Lock (0x1f) Quality= Good Signal= -34.66dBm C/N= 33.41dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0403 Lock (0x1f) Quality= Good Signal= -34.57dBm C/N= 33.46dB UCB= 0 postBER= 0 preBER= 1.05x10^-3 PER= 0404 Record to file 'music.ts' started405 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= 0407 408.. [1] In this example, it records 10 seconds with all program ID's stored409 at the music.ts file.410 411 412The channel can be watched by playing the contents of the stream with some413player 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 of416vidtv, e.g., to play a recorded TS file with::417 418 $ mplayer music.ts419 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/dvr0427 428For more information on dvb-zap check its online documentation here:429`dvb-zap Documentation430<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 vidtv435-----------------------------------436 437Add *debugfs* integration438~~~~~~~~~~~~~~~~~~~~~~~~~439 440Although frontend drivers provide DVBv5 statistics via the .read_status441call, a nice addition would be to make additional statistics available to442userspace via debugfs, which is a simple-to-use, RAM-based filesystem443specifically designed for debug purposes.444 445The logic for this would be implemented on a separate file so as not to446pollute the frontend driver. These statistics are driver-specific and can447be useful during tests.448 449The Siano driver is one example of a driver using450debugfs to convey driver-specific statistics to userspace and it can be451used as a reference.452 453This should be further enabled and disabled via a Kconfig454option for convenience.455 456Add a way to test video457~~~~~~~~~~~~~~~~~~~~~~~458 459Currently, vidtv can only encode PCM audio. It would be great to implement460a barebones version of MPEG-2 video encoding so we can also test video. The461first place to look into is *ISO 13818-2: Information technology — Generic462coding 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 simulation472~~~~~~~~~~~~~~~~~~~~~~~~~~473 474The vidtv tuner already has code to identify whether the chosen frequency475is too far away from a table of valid frequencies. For now, this means that476the demodulator can eventually lose the lock on the signal, since the tuner will477report 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 the482 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 vidtv489---------------------------------------490 491.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_bridge.h492 493.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_channel.h494 495.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_demod.h496 497.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_encoder.h498 499.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_mux.h500 501.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_pes.h502 503.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_psi.h504 505.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_s302m.h506 507.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_ts.h508 509.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.h510 511.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_common.c512 513.. kernel-doc:: drivers/media/test-drivers/vidtv/vidtv_tuner.c514