1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
3.. _dvb_introdution:
4
5************
6Introduction
7************
8
9
10.. _requisites:
11
12What you need to know
13=====================
14
15The reader of this document is required to have some knowledge in the
16area of digital video broadcasting (Digital TV) and should be familiar with
17part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
18you should know what a program/transport stream (PS/TS) is and what is
19meant by a packetized elementary stream (PES) or an I-frame.
20
21Various Digital TV standards documents are available for download at:
22
23- European standards (DVB): http://www.dvb.org and/or http://www.etsi.org.
24- American standards (ATSC): https://www.atsc.org/standards/
25- Japanese standards (ISDB): http://www.dibeg.org/
26
27It is also necessary to know how to access Linux devices and how to
28use ioctl calls. This also includes the knowledge of C or C++.
29
30
31.. _history:
32
33History
34=======
35
36The first API for Digital TV cards we used at Convergence in late 1999 was an
37extension of the Video4Linux API which was primarily developed for frame
38grabber cards. As such it was not really well suited to be used for Digital
39TV cards and their new features like recording MPEG streams and filtering
40several section and PES data streams at the same time.
41
42In early 2000, Convergence was approached by Nokia with a proposal for a new
43standard Linux Digital TV API. As a commitment to the development of terminals
44based on open standards, Nokia and Convergence made it available to all
45Linux developers and published it on https://linuxtv.org in September
462000. With the Linux driver for the Siemens/Hauppauge DVB PCI card,
47Convergence provided a first implementation of the Linux Digital TV API.
48Convergence was the maintainer of the Linux Digital TV API in the early
49days.
50
51Now, the API is maintained by the LinuxTV community (i.e. you, the reader
52of this document). The Linux  Digital TV API is constantly reviewed and
53improved together with the improvements at the subsystem's core at the
54Kernel.
55
56
57.. _overview:
58
59Overview
60========
61
62
63.. _stb_components:
64
65.. kernel-figure:: dvbstb.svg
66    :alt:   dvbstb.svg
67    :align: center
68
69    Components of a Digital TV card/STB
70
71A Digital TV card or set-top-box (STB) usually consists of the
72following main hardware components:
73
74Frontend consisting of tuner and digital TV demodulator
75   Here the raw signal reaches the digital TV hardware from a satellite dish or
76   antenna or directly from cable. The frontend down-converts and
77   demodulates this signal into an MPEG transport stream (TS). In case
78   of a satellite frontend, this includes a facility for satellite
79   equipment control (SEC), which allows control of LNB polarization,
80   multi feed switches or dish rotors.
81
82Conditional Access (CA) hardware like CI adapters and smartcard slots
83   The complete TS is passed through the CA hardware. Programs to which
84   the user has access (controlled by the smart card) are decoded in
85   real time and re-inserted into the TS.
86
87   .. note::
88
89      Not every digital TV hardware provides conditional access hardware.
90
91Demultiplexer which filters the incoming Digital TV MPEG-TS stream
92   The demultiplexer splits the TS into its components like audio and
93   video streams. Besides usually several of such audio and video
94   streams it also contains data streams with information about the
95   programs offered in this or other streams of the same provider.
96
97Audio and video decoder
98   The main targets of the demultiplexer are audio and video
99   decoders. After decoding, they pass on the uncompressed audio and
100   video to the computer screen or to a TV set.
101
102   .. note::
103
104      Modern hardware usually doesn't have a separate decoder hardware, as
105      such functionality can be provided by the main CPU, by the graphics
106      adapter of the system or by a signal processing hardware embedded on
107      a Systems on a Chip (SoC) integrated circuit.
108
109      It may also not be needed for certain usages (e.g. for data-only
110      uses like "internet over satellite").
111
112:ref:`stb_components` shows a crude schematic of the control and data
113flow between those components.
114
115
116
117.. _dvb_devices:
118
119Linux Digital TV Devices
120========================
121
122The Linux Digital TV API lets you control these hardware components through
123currently six Unix-style character devices for video, audio, frontend,
124demux, CA and IP-over-DVB networking. The video and audio devices
125control the MPEG2 decoder hardware, the frontend device the tuner and
126the Digital TV demodulator. The demux device gives you control over the PES
127and section filters of the hardware. If the hardware does not support
128filtering these filters can be implemented in software. Finally, the CA
129device controls all the conditional access capabilities of the hardware.
130It can depend on the individual security requirements of the platform,
131if and how many of the CA functions are made available to the
132application through this device.
133
134All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The
135individual devices are called:
136
137-  ``/dev/dvb/adapterN/audioM``,
138
139-  ``/dev/dvb/adapterN/videoM``,
140
141-  ``/dev/dvb/adapterN/frontendM``,
142
143-  ``/dev/dvb/adapterN/netM``,
144
145-  ``/dev/dvb/adapterN/demuxM``,
146
147-  ``/dev/dvb/adapterN/dvrM``,
148
149-  ``/dev/dvb/adapterN/caM``,
150
151where ``N`` enumerates the Digital TV cards in a system starting from 0, and
152``M`` enumerates the devices of each type within each adapter, starting
153from 0, too. We will omit the "``/dev/dvb/adapterN/``\ " in the further
154discussion of these devices.
155
156More details about the data structures and function calls of all the
157devices are described in the following chapters.
158
159
160.. _include_files:
161
162API include files
163=================
164
165For each of the Digital TV devices a corresponding include file exists. The
166Digital TV API include files should be included in application sources with a
167partial path like:
168
169
170.. code-block:: c
171
172	#include <linux/dvb/ca.h>
173
174	#include <linux/dvb/dmx.h>
175
176	#include <linux/dvb/frontend.h>
177
178	#include <linux/dvb/net.h>
179
180
181To enable applications to support different API version, an additional
182include file ``linux/dvb/version.h`` exists, which defines the constant
183``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``.
184