Documentation/DocBook/media/dvb/intro.xml

   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
  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
  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
  34 available to all Linux developers and published it on
  35 <ulink url="http://www.linuxtv.org/" /> in September 2000.
  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 &#8220;internet over satellite&#8221;). 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
 132 <para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
 133 tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
 134 are 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
 164 from&#x00A0;0, and M enumerates the devices of each type within each
 165 adapter, starting from&#x00A0;0, too. We will omit the &#8220;<emphasis
 166 role="tt">/dev/dvb/adapterN/</emphasis>&#8221; in the further dicussion
 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
 182 <programlisting>
 183         #include &#x003C;linux/dvb/audio.h&#x003E;
 184 </programlisting>
 185 <programlisting>
 186         #include &#x003C;linux/dvb/ca.h&#x003E;
 187 </programlisting>
 188 <programlisting>
 189         #include &#x003C;linux/dvb/dmx.h&#x003E;
 190 </programlisting>
 191 <programlisting>
 192         #include &#x003C;linux/dvb/frontend.h&#x003E;
 193 </programlisting>
 194 <programlisting>
 195         #include &#x003C;linux/dvb/net.h&#x003E;
 196 </programlisting>
 197 <programlisting>
 198         #include &#x003C;linux/dvb/osd.h&#x003E;
 199 </programlisting>
 200 <programlisting>
 201         #include &#x003C;linux/dvb/video.h&#x003E;
 202 </programlisting>
 203
 204 <para>To enable applications to support different API version, an
 205 additional include file <emphasis
 206 role="tt">linux/dvb/version.h</emphasis> exists, which defines the
 207 constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
 208 describes <emphasis role="tt">DVB_API_VERSION&#x00A0;3</emphasis>.
 209 </para>
 210
 211 </section>
 212