\chapter{Introduction}
%\addcontentsline{toc}{part}{Introduction}
%\chaptermark{Introduction}

\section{What you need to know}

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.

Various DVB standards documents are available from
\texttt{http://www.dvb.org/} and/or \texttt{http://www.etsi.org/}.

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++.

\section{History}

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.

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 \texttt{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.


\newpage
\section{Overview}

\begin{figure}[htbp]
  \begin{center}
    \includegraphics{dvbstb.ps}
    \caption{Components of a DVB card/STB}
    \label{fig:dvbstb}
  \end{center}
\end{figure}


A DVB PCI card or DVB set-top-box (STB) usually consists of the following
main hardware components:
\begin{itemize}
\item Frontend consisting of tuner and DVB demodulator

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.

\item Conditional Access (CA) hardware like CI adapters and smartcard slots

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. 

\item Demultiplexer which filters the incoming DVB stream

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.

\item MPEG2 audio and video decoder 

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.
\end{itemize}

Figure \ref{fig:dvbstb} shows a crude schematic of the control and data flow 
between those components.

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 
``internet over satellite'').
Also not every card or STB provides conditional access hardware.

\section{Linux DVB Devices}

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.

\smallskip
All devices can be found in the \texttt{/dev} tree under 
\texttt{/dev/dvb}.  The individual devices are called 
\begin{itemize}
\item \texttt{/dev/dvb/adapterN/audioM},
\item \texttt{/dev/dvb/adapterN/videoM},
\item \texttt{/dev/dvb/adapterN/frontendM},
\item \texttt{/dev/dvb/adapterN/netM},
\item \texttt{/dev/dvb/adapterN/demuxM},
\item \texttt{/dev/dvb/adapterN/caM},
\end{itemize}
where N enumerates the DVB PCI cards in a system starting from~0,
and M enumerates the devices of each type within each adapter, starting
from~0, too.
We will omit the ``\texttt{/dev/dvb/adapterN/}'' in the further dicussion of 
these devices.  The naming scheme for the devices is the same wheter devfs
is used or not.

More details about the data structures and function calls of 
all the devices are described in the following chapters.

\section{API include files}

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:

\begin{verbatim}
#include <linux/dvb/frontend.h>
\end{verbatim}

To enable applications to support different API version, an additional
include file \texttt{linux/dvb/version.h} exists, which defines the
constant \texttt{DVB\_API\_VERSION}. This document describes
\texttt{DVB\_API\_VERSION~3}.

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "dvbapi"
%%% End: 
