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