1 files changed, 148 insertions, 0 deletions
diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
new file mode 100644
index 000000000..613bcd6c8
--- /dev/null
+++ b/dvb-spec/dvbapi/intro.tex
@@ -0,0 +1,148 @@
+\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: