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 7the area of digital video broadcasting (DVB) and should be familiar with 8part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e 9you should know what a program/transport stream (PS/TS) is and what is 10meant by a packetized elementary stream (PES) or an I-frame.</para> 11 12<para>Various DVB standards documents are available from 13<ulink url="http://www.dvb.org" /> and/or 14<ulink url="http://www.etsi.org" />.</para> 15 16<para>It is also necessary to know how to access unix/linux devices and 17how 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 25was an extension of the Video4Linux API which was primarily developed 26for frame grabber cards. As such it was not really well suited to be 27used for DVB cards and their new features like recording MPEG streams 28and 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 32new standard Linux DVB API. As a commitment to the development of 33terminals based on open standards, Nokia and Convergence made it 34available to all Linux developers and published it on 35<ulink url="http://www.linuxtv.org/" /> in September 2000. 36Convergence is the maintainer of the Linux DVB API. Together with the 37LinuxTV community (i.e. you, the reader of this document), the Linux DVB 38API will be constantly reviewed and improved. With the Linux driver for 39the Siemens/Hauppauge DVB PCI card Convergence provides a first 40implementation 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 59following 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 67or antenna or directly from cable. The frontend down-converts and 68demodulates this signal into an MPEG transport stream (TS). In case of a 69satellite frontend, this includes a facility for satellite equipment 70control (SEC), which allows control of LNB polarization, multi feed 71switches 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 80which the user has access (controlled by the smart card) are decoded in 81real 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 88video streams. Besides usually several of such audio and video streams 89it also contains data streams with information about the programs 90offered 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 98video decoders. After decoding they pass on the uncompressed audio and 99video to the computer screen or (through a PAL/NTSC encoder) to a TV 100set.</para> 101 102 103</listitem> 104</itemizedlist> 105 106<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow 107between those components.</para> 108 109<para>On a DVB PCI card not all of these have to be present since some 110functionality can be provided by the main CPU of the PC (e.g. MPEG 111picture and sound decoding) or is not needed (e.g. for data-only uses 112like “internet over satellite”). Also not every card or STB 113provides 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 121through currently six Unix-style character devices for video, audio, 122frontend, demux, CA and IP-over-DVB networking. The video and audio 123devices control the MPEG2 decoder hardware, the frontend device the 124tuner and the DVB demodulator. The demux device gives you control over 125the PES and section filters of the hardware. If the hardware does not 126support filtering these filters can be implemented in software. Finally, 127the CA device controls all the conditional access capabilities of the 128hardware. It can depend on the individual security requirements of the 129platform, if and how many of the CA functions are made available to the 130application through this device.</para> 131 132<para>All devices can be found in the <emphasis role="tt">/dev</emphasis> 133tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices 134are called:</para> 135 136<itemizedlist> 137<listitem> 138 139<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para> 140</listitem> 141<listitem> 142<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para> 143</listitem> 144<listitem> 145<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para> 146</listitem> 147 <listitem> 148 149<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para> 150</listitem> 151 <listitem> 152 153<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para> 154</listitem> 155 <listitem> 156 157<para><emphasis role="tt">/dev/dvb/adapterN/dvrM</emphasis>,</para> 158</listitem> 159 <listitem> 160 161<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> 162 163<para>where N enumerates the DVB PCI cards in a system starting 164from 0, and M enumerates the devices of each type within each 165adapter, starting from 0, too. We will omit the “<emphasis 166role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion 167of these devices. The naming scheme for the devices is the same wheter 168devfs is used or not.</para> 169 170<para>More details about the data structures and function calls of all 171the 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. 179The DVB API include files should be included in application sources with 180a partial path like:</para> 181 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> 191<programlisting> 192 #include <linux/dvb/frontend.h> 193</programlisting> 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> 203 204<para>To enable applications to support different API version, an 205additional include file <emphasis 206role="tt">linux/dvb/version.h</emphasis> exists, which defines the 207constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document 208describes <emphasis role="tt">DVB_API_VERSION 5.8</emphasis>. 209</para> 210 211</section> 212 213
