new API docs

1 files changed, 192 insertions, 0 deletions

diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
new file mode 100644
index 000000000..acb6b4b85
--- /dev/null
+++ b/dvb-spec/dvbapi/intro.tex
@@ -0,0 +1,192 @@
+\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  ISO/IEC 13818, 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. 
+
+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 upon. 
+With the Linux driver for the Siemens/Hauppauge DVB PCI card Convergence 
+provides a first implementation of the Linux DVB API.
+
+
+\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).
+
+\item SEC for controlling external hardware like LNBs and antennas
+
+This part of the hardware can send signals back through the satellite
+cable to control the polarization of the LNB, to switch between 
+different LNBs or even to control the movements of a dish rotor.
+
+
+\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 strams 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 the 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, SEC, demux and CA. 
+The video and audio devices control the MPEG2 decoder hardware,
+the frontend device the tuner and the DVB demodulator.
+External hardware like DiSEqC switches and rotors can be controlled 
+through the SEC device. 
+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.
+
+All devices can be found in the \texttt{/dev} tree under 
+\texttt{/dev/ost}, where OST stands for Open Standards Terminal.
+The individual devices are called 
+\begin{itemize}
+\item \texttt{/dev/ost/audio},
+\item \texttt{/dev/ost/video},
+\item \texttt{/dev/ost/qpskfe},
+\item \texttt{/dev/ost/qamfe},
+\item \texttt{/dev/ost/sec},
+\item \texttt{/dev/ost/demux},
+\item \texttt{/dev/ost/ca},
+\end{itemize}
+but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of 
+these devices. 
+
+%Thus, the \texttt{audio} and \texttt{video} devices directly control 
+%the MPEG2 decoder audio and video decoder, respectively. 
+%Depending on the kind of frontend present (satellite, cable or
+%terrestrial), it will be controlled either through the 
+%\texttt{qpsk} or \texttt{qamfe} device. 
+%DiSEqC or other kinds of control signals can be sent to the 
+%antenna hardware through the \texttt{sec} device.
+
+If more than one card is present in the system the other cards
+can be accessed through the corresponding devices with the
+card's number appended. \texttt{/dev/ost/demux0} (which 
+is identical to \texttt{/dev/ost/demux}) would, e.g.,  control the 
+demultiplexer of the first card, while \texttt{/dev/ost/demux1}
+would control the demultiplexer of the second card, and so on.
+
+More details about the data structures and function calls of 
+all the devices are described in the following chapters.
+
+
+\section{DVB Devices with Devfs}
+
+Recent Linux kernel versions support a special file system called 
+\textsl{devfs} which is a replacement for the traditional 
+device directory. 
+With devfs a Linux DVB driver will only create those device file entries
+which actually exist. 
+It also makes dealing with more complex DVB hardware much easier.
+The device structure described above is not well suited to deal 
+with multiple DVB cards with more than one frontend or demultiplexer.
+Consider, e.g., two DVB cards, one with two frontends and
+one demultiplexer, the other with one frontend and two demultiplexers.
+If we just assign them consecutive numbers, there would be a demultiplexer
+and a frontend which do notbelong to the same card but have 
+the same number.
+
+With \textsl{devfs} we propose a different scheme for the device names.
+The root directory for all DVB cards will be \texttt{/dev/dvb}. 
+Each card gets assigned a sub-directory with the name \texttt{/dev/card0},
+\texttt{/dev/card1}, etc.
+The files created in these sub-directories will correspond directly to the 
+hardware actually present on the card. 
+Thus, if the first card has one QAM frontend, one demultiplexer
+and otherwise no other hardware, 
+only \texttt{/dev/dvb/card0/qamfe0} and \texttt{/dev/dvb/card0/demux0} 
+will be created.
+When a second DVB-S card with one frontend (including SEC) device,
+two demultiplexers and an MPEG2 audio/video decoder is added, the
+complete \texttt{/dev/dvb} tree will look like this:
+
+\begin{verbatim}
+/dev/dvb/card0/qam0
+               demux0
+
+/dev/dvb/card1/video0
+               audio0
+               demux0
+               demux1
+               qpskfe0
+               sec0
+\end{verbatim}
+
+
+\section{Using the Devices}
+
+\dots
+
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "dvbapi"
+%%% End: