archive mirror
 help / color / mirror / Atom feed
From: "Daniel W. S. Almeida" <>
	"Daniel W. S. Almeida" <>,
Subject: [Linux-kernel-mentees] [v9 4/4] media: Documentation: vidtv: Add ReST documentation for vidtv
Date: Tue, 18 Aug 2020 19:50:41 -0300	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

From: "Daniel W. S. Almeida" <>

Add documentation for the Virtual Digital TV driver (vidtv) in the
Restructured Text (ReST) format.

This discusses:
- What is vidtv
- Why vidtv is needed
- How to build and run vidtv
- How vidtv is structured
- How to test vidtv
- How to improve vidtv

Signed-off-by: Daniel W. S. Almeida <>
 .../driver-api/media/drivers/index.rst        |   1 +
 .../driver-api/media/drivers/vidtv.rst        | 417 ++++++++++++++++++
 2 files changed, 418 insertions(+)
 create mode 100644 Documentation/driver-api/media/drivers/vidtv.rst

diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst
index 0df85fc96605..5f340cfdb4cc 100644
--- a/Documentation/driver-api/media/drivers/index.rst
+++ b/Documentation/driver-api/media/drivers/index.rst
@@ -35,4 +35,5 @@ Digital TV drivers

+	vidtv
diff --git a/Documentation/driver-api/media/drivers/vidtv.rst b/Documentation/driver-api/media/drivers/vidtv.rst
new file mode 100644
index 000000000000..303227a67f60
--- /dev/null
+++ b/Documentation/driver-api/media/drivers/vidtv.rst
@@ -0,0 +1,417 @@
+.. SPDX-License-Identifier: GPL-2.0
+vidtv: Virtual Digital TV driver
+Author: Daniel W. S. Almeida <>, June 2020.
+Vidtv is a virtual DVB driver that aims to serve as a reference for driver
+writers by serving as a template. It also validates the existing media DVB
+APIs, thus helping userspace application writers.
+Currently, it consists of:
+- A fake tuner driver, which will report a bad signal quality if the chosen
+  frequency is too far away from a table of valid frequencies for a
+  particular delivery system.
+- A fake demod driver, which will constantly poll the fake signal quality
+  returned by the tuner, simulating a device that can lose/reacquire a lock
+  on the signal depending on the CNR levels.
+- A fake bridge driver, which is the module responsible for modprobing the
+  fake tuner and demod modules and implementing the demux logic. This module
+  takes parameters at initialization that will dictate how the simulation
+  behaves.
+- Code reponsible for encoding a valid MPEG Transport Stream, which is then
+  passed to the bridge driver. This fake stream contains some hardcoded content.
+  For now, we have a single, audio-only channel containing a single MPEG
+  Elementary Stream, which in turn contains a SMPTE 302m encoded sine-wave.
+  Note that this particular encoder was chosen because it is the easiest
+  way to encode PCM audio data in a MPEG Transport Stream.
+Building vidtv
+vidtv is a test driver and thus is **not** enabled by default when
+compiling the kernel.
+In order to enable compilation of vidtv:
+- Enable **DVB_TEST_DRIVERS**, then
+- Enable **DVB_VIDTV**
+When compiled as a module, expect the following .ko files:
+- dvb_vidtv_tuner.ko
+- dvb_vidtv_demod.ko
+- dvb_vidtv_bridge.ko
+Running vidtv
+When compiled as a module, run::
+	modprobe dvb_vidtv_bridge
+That's it! The bridge driver will initialize the tuner and demod drivers as
+part of its own initialization.
+You can optionally define some command-line arguments to vidtv.
+Command-line arguments to vidtv
+Below is a list of all arguments that can be supplied to vidtv:
+	Probability of losing the TS lock if the signal quality is bad.
+	This probability be used by the fake demodulator driver to
+	eventually return a status of 0 when the signal quality is not
+	good.
+	Probability recovering the TS lock when the signal improves. This
+	probability be used by the fake demodulator driver to eventually
+	return a status of 0x1f when/if the signal quality improves.
+	Simulate a power up delay.  Default: 0.
+	Simulate a tune delay.  Default 0.
+	Valid DVB-T frequencies to simulate.
+ 	Valid DVB-C frequencies to simulate.
+	Valid DVB-C frequencies to simulate.
+	Maximum shift in HZ allowed when tuning in a channel.
+	How often to send SI packets.  Default: 40ms.
+	How often to send PCR packets.  Default: 40ms.
+	Attempt to maintain this bit rate by inserting TS null packets, if
+	necessary.  Default: 4096.
+	PCR PID for all channels.  Default: 0x200.
+	Size for the mux buffer in multiples of 188 bytes.
+vidtv internal structure
+The kernel modules are split in the following way:
+	Implements a fake tuner DVB driver.
+	Implements a fake demodulator DVB driver.
+	Implements a bridge driver.
+The MPEG related code is split in the following way:
+	Code to work with MPEG TS packets, such as TS headers, adaptation
+	fields, PCR packets and NULL packets.
+	This is the PSI generator.  PSI packets contain general information
+	about a MPEG Transport Stream.  A PSI generator is needed so
+	userspace apps can retrieve information about the Transport Stream
+	and eventually tune into a (dummy) channel.
+	Because the generator is implemented in a separate file, it can be
+	reused elsewhere in the media subsystem.
+	Currently vidtv supports working with 3 PSI tables: PAT, PMT and
+	SDT.
+	The specification for PAT and PMT can be found in *ISO 13818-1:
+	Systems*, while the specification for the SDT can be found in *ETSI
+	EN 300 468: Specification for Service Information (SI) in DVB
+	systems*.
+	It isn't strictly necessary, but using a real TS file helps when
+	debugging PSI tables. Vidtv currently tries to replicate the PSI
+	structure found in this file: `TS1Globo.ts
+	<>`_.
+	A good way to visualize the structure of streams is by using
+	`DVBInspector <>`_.
+	Implements the PES logic to convert encoder data into MPEG TS
+	packets. These can then be fed into a TS multiplexer and eventually
+	into userspace.
+	An interface for vidtv encoders. New encoders can be added to this
+	driver by implementing the calls in this file.
+	Implements a S302M encoder to make it possible to insert PCM audio
+	data in the generated MPEG Transport Stream. The relevant
+	specification is available online as *SMPTE 302M-2007: Television -
+	Mapping of AES3 Data into MPEG-2 Transport Stream*.
+	The resulting MPEG Elementary Stream is conveyed in a private
+	stream with a S302M registration descriptor attached.
+	This shall enable passing an audio signal into userspace so it can
+	be decoded and played by media software. The corresponding decoder
+	in ffmpeg is located in 'libavcodec/s302m.c' and is experimental.
+	Implements a 'channel' abstraction.
+	When vidtv boots, it will create some hardcoded channels:
+	#. Their services will be concatenated to populate the SDT.
+	#. Their programs will be concatenated to populate the PAT
+	#. For each program in the PAT, a PMT section will be created
+	#. The PMT section for a channel will be assigned its streams.
+	#. Every stream will have its corresponding encoder polled in a
+	   loop to produce TS packets.
+	   These packets may be interleaved by the muxer and then delivered
+	   to the bridge.
+	Implements a MPEG TS mux, loosely based on the ffmpeg
+	implementation in "libavcodec/mpegtsenc.c"
+	The muxer runs a loop which is responsible for:
+	#. Keeping track of the amount of time elapsed since the last
+	   iteration.
+	#. Polling encoders in order to fetch 'elapsed_time' worth of data.
+	#. Inserting PSI and/or PCR packets, if needed.
+	#. Padding the resulting stream with NULL packets if
+	   necessary in order to maintain the chosen bit rate.
+	#. Delivering the resulting TS packets to the bridge
+	   driver so it can pass them to the demux.
+Testing vidtv with v4l-utils
+Using the tools in v4l-utils is a great way to test and inspect the output of
+vidtv. It is hosted here: `v4l-utils Documentation
+From its webpage::
+	The v4l-utils are a series of packages for handling media devices.
+	It is hosted at, and packaged
+	on most distributions.
+	It provides a series of libraries and utilities to be used to
+	control several aspect of the media boards.
+Start by installing v4l-utils and then modprobing vidtv::
+	modprobe dvb_vidtv_bridge
+If the driver is OK, it should load and its probing code will run. This will
+pull in the tuner and demod drivers.
+Using dvb-fe-tool
+The first step to check whether the demod loaded successfully is to run::
+	$ dvb-fe-tool
+This should return what is currently set up at the demod struct, i.e.::
+	static const struct dvb_frontend_ops vidtv_demod_ops = {
+		.delsys = {
+			SYS_DVBT2,
+			SYS_DVBS2,
+		},
+		.info = {
+			.name                   = "Dummy demod for DVB-T/T2/C/S/S2",
+			.frequency_min_hz       = 51 * MHz,
+			.frequency_max_hz       = 2150 * MHz,
+			.frequency_stepsize_hz  = 62500,
+			.frequency_tolerance_hz = 29500 * kHz,
+			.symbol_rate_min        = 1000000,
+			.symbol_rate_max        = 45000000,
+			.caps = FE_CAN_FEC_1_2 |
+				FE_CAN_FEC_2_3 |
+				FE_CAN_FEC_3_4 |
+				FE_CAN_FEC_4_5 |
+				FE_CAN_FEC_5_6 |
+				FE_CAN_FEC_6_7 |
+				FE_CAN_FEC_7_8 |
+				FE_CAN_FEC_8_9 |
+				FE_CAN_QAM_16 |
+				FE_CAN_QAM_64 |
+				FE_CAN_QAM_32 |
+				FE_CAN_QAM_128 |
+				FE_CAN_QAM_256 |
+				FE_CAN_QPSK |
+		}
+		....
+For more information on dvb-fe-tools check its online documentation here:
+`dvb-fe-tool Documentation
+Using dvb-scan
+In order to tune into a channel and read the PSI tables, we can use dvb-scan.
+For this, one should provide a configuration file known as a 'scan file',
+here's an example::
+	[Channel]
+	FREQUENCY = 330000000
+	SYMBOL_RATE = 6940000
+.. note::
+	The parameters depend on the video standard you're testing.
+.. note::
+	Vidtv is a fake driver and does not validate much of the information
+	in the scan file. Just specifying 'FREQUENCY' and 'DELIVERY_SYSTEM'
+	should be enough for DVB-T/DVB-T2. For DVB-S/DVB-C however, you
+	should also provide 'SYMBOL_RATE'.
+You can browse scan tables online here: `dvb-scan-tables
+Assuming this channel is named 'channel.conf', you can then run::
+        $ dvbv5-scan channel.conf
+For more information on dvb-scan, check its documentation online here:
+`dvb-scan Documentation <>`_.
+Using dvb-zap
+dvbv5-zap is a command line tool that can be used to record MPEG-TS to disk. The
+typical use is to tune into a channel and put it into record mode. The example
+below - which is taken from the documentation - illustrates that::
+        $ dvbv5-zap -c dvb_channel.conf "trilhas sonoras" -r
+        using demux '/dev/dvb/adapter0/demux0'
+        reading channels from file 'dvb_channel.conf'
+        service has pid type 05:  204
+        tuning to 573000000 Hz
+        audio pid 104
+          dvb_set_pesfilter 104
+        Lock   (0x1f) Quality= Good Signal= 100.00% C/N= -13.80dB UCB= 70 postBER= 3.14x10^-3 PER= 0
+        DVR interface '/dev/dvb/adapter0/dvr0' can now be opened
+The channel can be watched by playing the contents of the DVR interface, with
+some player that recognizes the MPEG-TS format, such as *mplayer* or *vlc*.
+By playing the contents of the stream one can visually inspect the workings of
+vidtv, e.g.::
+	$ mplayer /dev/dvb/adapter0/dvr0
+For more information on dvb-zap check its online documentation here:
+`dvb-zap Documentation
+See also: `zap <>`_.
+What can still be improved in vidtv
+Add *debugfs* integration
+Although frontend drivers provide DVBv5 statistics via the .read_status
+call, a nice addition would be to make additional statistics available to
+userspace via debugfs, which is a simple-to-use, RAM-based filesystem
+specifically designed for debug purposes.
+The logic for this would be implemented on a separate file so as not to
+pollute the frontend driver.  These statistics are driver-specific and can
+be useful during tests.
+The Siano driver is one example of a driver using
+debugfs to convey driver-specific statistics to userspace and it can be
+used as a reference.
+This should be further enabled and disabled via a Kconfig
+option for convenience.
+Add a way to test video
+Currently, vidtv can only encode PCM audio. It would be great to implement
+a barebones version of MPEG-2 video encoding so we can also test video. The
+first place to look into is *ISO 13818-2: Information technology — Generic
+coding of moving pictures and associated audio information — Part 2: Video*,
+which covers the encoding of compressed video in MPEG Transport Streams.
+This might optionally use the Video4Linux2 Test Pattern Generator, v4l2-tpg,
+which resides at::
+	drivers/media/common/v4l2-tpg/
+Add white noise simulation
+The vidtv tuner already has code to identify whether the chosen frequency
+is too far away from a table of valid frequencies. For now, this means that
+the demodulator can eventually lose the lock on the signal, since the tuner will
+report a bad signal quality.
+A nice addition is to simulate some noise when the signal quality is bad by:
+- Randomly dropping some TS packets. This will trigger a continuity error if the
+  continuity counter is updated but the packet is not passed on to the demux.
+- Updating the error statistics accordingly (e.g. BER, etc).
+- Simulating some noise in the encoded data.

Linux-kernel-mentees mailing list

      parent reply	other threads:[~2020-08-18 22:51 UTC|newest]

Thread overview: 5+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-18 22:50 [Linux-kernel-mentees] [v9 0/4] media: vidtv: Implement a virtual DVB driver Daniel W. S. Almeida
2020-08-18 22:50 ` [Linux-kernel-mentees] [v9 1/4] media: vidtv: implement a tuner driver Daniel W. S. Almeida
2020-08-18 22:50 ` [Linux-kernel-mentees] [v9 2/4] media: vidtv: implement a demodulator driver Daniel W. S. Almeida
2020-08-18 22:50 ` [Linux-kernel-mentees] [v9 3/4] media: vidtv: add a bridge driver Daniel W. S. Almeida
2020-08-18 22:50 ` Daniel W. S. Almeida [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).