From 9034551a3bbc76b79a152806c781b1b8e8ea3a9a Mon Sep 17 00:00:00 2001
From: rjkm <devnull@localhost>
Date: Sun, 16 Sep 2001 22:27:03 -0300
Subject: new API docs

---
 dvb-spec/dvbapi/intro.tex | 192 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 192 insertions(+)
 create mode 100644 dvb-spec/dvbapi/intro.tex

(limited to 'dvb-spec/dvbapi/intro.tex')

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: 
-- 
cgit v1.2.3


From d50611422c6fb579b75a45b4d36613147abb69e4 Mon Sep 17 00:00:00 2001
From: mocm <devnull@localhost>
Date: Thu, 14 Feb 2002 08:51:00 -0200
Subject: some updates and correctionsome updates and correctionss

---
 dvb-spec/dvbapi/intro.tex | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

(limited to 'dvb-spec/dvbapi/intro.tex')

diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
index acb6b4b85..e026a86e1 100644
--- a/dvb-spec/dvbapi/intro.tex
+++ b/dvb-spec/dvbapi/intro.tex
@@ -110,8 +110,7 @@ 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/frontend},
 \item \texttt{/dev/ost/sec},
 \item \texttt{/dev/ost/demux},
 \item \texttt{/dev/ost/ca},
@@ -151,7 +150,7 @@ 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 
+and a frontend which do not belong to the same card but have 
 the same number.
 
 With \textsl{devfs} we propose a different scheme for the device names.
@@ -169,14 +168,14 @@ 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
+/dev/dvb/card0/frontend0
                demux0
 
 /dev/dvb/card1/video0
                audio0
                demux0
                demux1
-               qpskfe0
+               frontend0
                sec0
 \end{verbatim}
 
-- 
cgit v1.2.3


From aed2950af0b53026e245705b265059ee9a439e1f Mon Sep 17 00:00:00 2001
From: mocm <devnull@localhost>
Date: Mon, 4 Mar 2002 09:27:48 -0300
Subject: some error corrections

---
 dvb-spec/dvbapi/intro.tex | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

(limited to 'dvb-spec/dvbapi/intro.tex')

diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
index e026a86e1..1d859fadb 100644
--- a/dvb-spec/dvbapi/intro.tex
+++ b/dvb-spec/dvbapi/intro.tex
@@ -68,7 +68,7 @@ time and re-inserted into the TS.
 
 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
+contains data streams with information about the programs offered in this
 or other streams of the same provider.
 
 \item MPEG2 audio and video decoder 
@@ -118,14 +118,6 @@ The individual devices are called
 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 
-- 
cgit v1.2.3


From ab85b007da42f42856a775d8cff97332093f5b34 Mon Sep 17 00:00:00 2001
From: holger <devnull@localhost>
Date: Thu, 10 Oct 2002 15:59:05 -0300
Subject: make room for the new HEAD trunk

---
 dvb-spec/dvbapi/intro.tex | 183 ----------------------------------------------
 1 file changed, 183 deletions(-)
 delete mode 100644 dvb-spec/dvbapi/intro.tex

(limited to 'dvb-spec/dvbapi/intro.tex')

diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
deleted file mode 100644
index 1d859fadb..000000000
--- a/dvb-spec/dvbapi/intro.tex
+++ /dev/null
@@ -1,183 +0,0 @@
-\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 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 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/frontend},
-\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. 
-
-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 not belong 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/frontend0
-               demux0
-
-/dev/dvb/card1/video0
-               audio0
-               demux0
-               demux1
-               frontend0
-               sec0
-\end{verbatim}
-
-
-\section{Using the Devices}
-
-\dots
-
-
-%%% Local Variables: 
-%%% mode: latex
-%%% TeX-master: "dvbapi"
-%%% End: 
-- 
cgit v1.2.3


From 5a523e605b9b6d1ae50d0707c1874c5b7f0959cc Mon Sep 17 00:00:00 2001
From: holger <devnull@localhost>
Date: Thu, 10 Oct 2002 16:22:27 -0300
Subject: the new HEAD

---
 dvb-spec/dvbapi/intro.tex | 183 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 dvb-spec/dvbapi/intro.tex

(limited to 'dvb-spec/dvbapi/intro.tex')

diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
new file mode 100644
index 000000000..1d859fadb
--- /dev/null
+++ b/dvb-spec/dvbapi/intro.tex
@@ -0,0 +1,183 @@
+\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 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 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/frontend},
+\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. 
+
+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 not belong 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/frontend0
+               demux0
+
+/dev/dvb/card1/video0
+               audio0
+               demux0
+               demux1
+               frontend0
+               sec0
+\end{verbatim}
+
+
+\section{Using the Devices}
+
+\dots
+
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: "dvbapi"
+%%% End: 
-- 
cgit v1.2.3


From 622f6e3335a0dd1a97cdaee9913c1f105f3e36fa Mon Sep 17 00:00:00 2001
From: js <devnull@localhost>
Date: Mon, 10 Feb 2003 10:18:16 -0200
Subject: - merged GNU FDL lincense from NEWSTRUCT branch - updated from
 DVB_API_VERSION 3 - various minor fixes/additions - bumped version number to
 1.0.0-pre1 to match wth upcoming   linuxtv-dvb driver release

---
 dvb-spec/dvbapi/intro.tex | 117 ++++++++++++++++------------------------------
 1 file changed, 41 insertions(+), 76 deletions(-)

(limited to 'dvb-spec/dvbapi/intro.tex')

diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex
index 1d859fadb..613bcd6c8 100644
--- a/dvb-spec/dvbapi/intro.tex
+++ b/dvb-spec/dvbapi/intro.tex
@@ -1,15 +1,21 @@
 \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. 
+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
@@ -26,11 +32,12 @@ 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. 
+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]
@@ -49,14 +56,10 @@ main hardware components:
 
 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.
-
+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
 
@@ -74,10 +77,11 @@ 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 
+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.
 
@@ -91,11 +95,9 @@ Also not every card or STB provides conditional access hardware.
 
 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. 
+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.
-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.
@@ -104,78 +106,41 @@ 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/ost}, where OST stands for Open Standards Terminal.
-The individual devices are called 
+\texttt{/dev/dvb}.  The individual devices are called 
 \begin{itemize}
-\item \texttt{/dev/ost/audio},
-\item \texttt{/dev/ost/video},
-\item \texttt{/dev/ost/frontend},
-\item \texttt{/dev/ost/sec},
-\item \texttt{/dev/ost/demux},
-\item \texttt{/dev/ost/ca},
+\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}
-but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of 
-these devices. 
-
-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.
+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}
 
-\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 not belong 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:
+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}
-/dev/dvb/card0/frontend0
-               demux0
-
-/dev/dvb/card1/video0
-               audio0
-               demux0
-               demux1
-               frontend0
-               sec0
+#include <linux/dvb/frontend.h>
 \end{verbatim}
 
-
-\section{Using the Devices}
-
-\dots
-
+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
-- 
cgit v1.2.3

