cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

vidtv.rst (16186B)


      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 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