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