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