<title>Introduction</title>
  
  <section id="requisites">
  <title>What you need to know</title>
  
  <para>The reader of this document is required to have some knowledge in
  the area of digital video broadcasting (DVB) and should be familiar with
  part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
  you should know what a program/transport stream (PS/TS) is and what is
  meant by a packetized elementary stream (PES) or an I-frame.</para>
  
  <para>Various DVB standards documents are available from
  <ulink url="http://www.dvb.org" /> and/or
  <ulink url="http://www.etsi.org" />.</para>
  
  <para>It is also necessary to know how to access unix/linux devices and
  how to use ioctl calls. This also includes the knowledge of C or C++.
  </para>
  </section>
  
  <section id="history">
  <title>History</title>
  
  <para>The first API for DVB cards we used at Convergence in late 1999
  was an extension of the Video4Linux API which was primarily developed
  for frame grabber cards. As such it was not really well suited to be
  used for DVB cards and their new features like recording MPEG streams
  and filtering several section and PES data streams at the same time.
  </para>
  
  <para>In early 2000, we were approached by Nokia with a proposal for a
  new standard Linux DVB API. As a commitment to the development of
  terminals based on open standards, Nokia and Convergence made it
  available to all Linux developers and published it on
  <ulink url="http://www.linuxtv.org/" /> in September 2000.
  Convergence is the maintainer of the Linux DVB API. Together with the
  LinuxTV community (i.e. you, the reader of this document), the Linux DVB
  API will be constantly reviewed and improved. With the Linux driver for
  the Siemens/Hauppauge DVB PCI card Convergence provides a first
  implementation of the Linux DVB API.</para>
  </section>
  
  <section id="overview">
  <title>Overview</title>
  
  <figure id="stb_components">
  <title>Components of a DVB card/STB</title>
  <mediaobject>
  <imageobject>
  <imagedata fileref="dvbstb.pdf" format="PS" />
  </imageobject>
  <imageobject>
  <imagedata fileref="dvbstb.png" format="PNG" />
  </imageobject>
  </mediaobject>
  </figure>
  
  <para>A DVB PCI card or DVB set-top-box (STB) usually consists of the
  following main hardware components: </para>
  
  <itemizedlist>
   <listitem>
  
  <para>Frontend consisting of tuner and DVB demodulator</para>
  
  <para>Here the raw signal reaches the DVB hardware from a satellite dish
  or antenna or directly from cable. The frontend down-converts and
  demodulates this signal into an MPEG transport stream (TS). In case of a
  satellite frontend, this includes a facility for satellite equipment
  control (SEC), which allows control of LNB polarization, multi feed
  switches or dish rotors.</para>
  
  </listitem>
   <listitem>
  
  <para>Conditional Access (CA) hardware like CI adapters and smartcard slots
  </para>
  
  <para>The complete TS is passed through the CA hardware. Programs to
  which the user has access (controlled by the smart card) are decoded in
  real time and re-inserted into the TS.</para>
  
  </listitem>
   <listitem>
   <para>Demultiplexer which filters the incoming DVB stream</para>
  
  <para>The demultiplexer splits the TS into its components like audio and
  video streams. Besides usually several of such audio and video streams
  it also contains data streams with information about the programs
  offered in this or other streams of the same provider.</para>
  
  </listitem>
  <listitem>
  
  <para>MPEG2 audio and video decoder</para>
  
  <para>The main targets of the demultiplexer are the MPEG2 audio and
  video decoders. After decoding they pass on the uncompressed audio and
  video to the computer screen or (through a PAL/NTSC encoder) to a TV
  set.</para>
  
  
  </listitem>
  </itemizedlist>
  
  <para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
  between those components.</para>
  
  <para>On a DVB PCI card not all of these have to be present since some
  functionality can be provided by the main CPU of the PC (e.g. MPEG
  picture and sound decoding) or is not needed (e.g. for data-only uses
  like &#8220;internet over satellite&#8221;). Also not every card or STB
  provides conditional access hardware.</para>
  
  </section>
  
  <section id="dvb_devices">
  <title>Linux DVB Devices</title>
  
  <para>The Linux DVB API lets you control these hardware components
  through currently six Unix-style character devices for video, audio,
  frontend, demux, CA and IP-over-DVB networking. The video and audio
  devices control the MPEG2 decoder hardware, the frontend device the
  tuner and the DVB demodulator. The demux device gives you control over
  the PES and section filters of the hardware. If the hardware does not
  support filtering these filters can be implemented in software. Finally,
  the CA device controls all the conditional access capabilities of the
  hardware. It can depend on the individual security requirements of the
  platform, if and how many of the CA functions are made available to the
  application through this device.</para>
  
  <para>All devices can be found in the <constant>/dev</constant>
  tree under <constant>/dev/dvb</constant>. The individual devices
  are called:</para>
  
  <itemizedlist>
  <listitem>
  
  <para><constant>/dev/dvb/adapterN/audioM</constant>,</para>
  </listitem>
  <listitem>
  <para><constant>/dev/dvb/adapterN/videoM</constant>,</para>
  </listitem>
  <listitem>
  <para><constant>/dev/dvb/adapterN/frontendM</constant>,</para>
  </listitem>
   <listitem>
  
  <para><constant>/dev/dvb/adapterN/netM</constant>,</para>
  </listitem>
   <listitem>
  
  <para><constant>/dev/dvb/adapterN/demuxM</constant>,</para>
  </listitem>
   <listitem>
  
  <para><constant>/dev/dvb/adapterN/dvrM</constant>,</para>
  </listitem>
   <listitem>
  
  <para><constant>/dev/dvb/adapterN/caM</constant>,</para></listitem></itemizedlist>
  
  <para>where N enumerates the DVB PCI cards in a system starting
  from&#x00A0;0, and M enumerates the devices of each type within each
  adapter, starting from&#x00A0;0, too. We will omit the &#8220;
  <constant>/dev/dvb/adapterN/</constant>&#8221; in the further discussion
  of these devices.</para>
  
  <para>More details about the data structures and function calls of all
  the devices are described in the following chapters.</para>
  
  </section>
  
  <section id="include_files">
  <title>API include files</title>
  
  <para>For each of the DVB devices a corresponding include file exists.
  The DVB API include files should be included in application sources with
  a partial path like:</para>
  
  <programlisting>
  	#include &#x003C;linux/dvb/audio.h&#x003E;
  </programlisting>
  <programlisting>
  	#include &#x003C;linux/dvb/ca.h&#x003E;
  </programlisting>
  <programlisting>
  	#include &#x003C;linux/dvb/dmx.h&#x003E;
  </programlisting>
  <programlisting>
  	#include &#x003C;linux/dvb/frontend.h&#x003E;
  </programlisting>
  <programlisting>
  	#include &#x003C;linux/dvb/net.h&#x003E;
  </programlisting>
  <programlisting>
  	#include &#x003C;linux/dvb/osd.h&#x003E;
  </programlisting>
  <programlisting>
  	#include &#x003C;linux/dvb/video.h&#x003E;
  </programlisting>
  
  <para>To enable applications to support different API version, an
  additional include file
  <constant>linux/dvb/version.h</constant> exists, which defines the
  constant <constant>DVB_API_VERSION</constant>. This document
  describes <constant>DVB_API_VERSION 5.10</constant>.
  </para>
  
  </section>