[PATCH] dvb-api: update documentation, chapter1

[PATCH] dvb-api: update documentation, chapter1

[wk]

[-- Attachment #1: Type: text/plain, Size: 9291 bytes --]

Since dvb-api doc is still outdated by six years...


The following patch changes dvbapi.pdf as following:
_______________________________________________________________________________

- change from twosided book format to singlesided book format.
  * By doing so, the readability is improved and on the right-hand side
    is more space on every second page.

- change copyright notice on first page by adding "2008, 2009 
www.linuxtv.org"

- add "The Linux DVB Developers http://www.linuxtv.org" to 'written by'

- increase API Version number to 5

- change Version Number and date
  -- 24/07/2003    V 1.0.0
  ++ 22/02/2009    Version 1.1.0 <- unstable version now, every time api 
is changed version should be increased now

- chapter 1 - What you need to know
   * added goal: "consistent abstraction layer for
     different digital TV hardware, allowing software applications to be
     developed without hardware details as well as serving as driver 
developers reference"
   * added comment: odd api version numbers = unstable -> not to be used 
for driver/app development

- chapter 1 - history
  * add History of DVB API v 4
  * add comment LinuxTV project beeing an independend and non-profit 
community
  * add reasons for DVB API v 5 and decision on Plumbers Conference 2008 
towards S2API

- chapter 1 - Overview
  * changed "DVB PCI card" wherever found, since API doesnt depend on 
PCI bus
  * changed "MPEG picture and sound decoding" to "MPEG video and audio 
decoding",
    since mpeg picture is misleading

- fix some typos inside chapter 1
- fix "Overfull \hbox" warnings from chapter 1 (*only* chapter 1 for now..)

Signed-off-by: Winfried Koehler <handygewinnspiel@gmx.de>
_______________________________________________________________________________

Please response, comment, improve, review, apply. Do not ignore silently,
having a new API doc should be hard requirement for next kernel versions.

Regards, Winfried







diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/dvbapi.tex 
v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/dvbapi.tex
--- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/dvbapi.tex    2009-02-22 
17:07:48.123742503 +0100
+++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/dvbapi.tex    2009-02-21 
17:33:29.557033066 +0100
@@ -1,4 +1,4 @@
-\documentclass[a4paper,10pt]{book}
+\documentclass[a4paper,10pt,oneside]{book}
 \usepackage[dvips,colorlinks=true]{hyperref}
 
 \usepackage{times}
diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/intro.tex 
v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/intro.tex
--- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/intro.tex    2009-02-18 
13:49:37.000000000 +0100
+++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/intro.tex    2009-02-22 
16:03:12.610230293 +0100
@@ -7,36 +7,73 @@
 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/}.
+i.e you should know what a program stream or 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++.
 
+The goal of this API is to provide a consistent abstraction layer for
+different digital TV hardware, allowing software applications to be
+developed without hardware details as well as serving as driver
+developers reference.
+
+For this API documentation applies an even/odd versioning scheme, stating
+unstable or stable versions of that API. Only stable API versions should
+be used for developing drivers and applications.
+\newpage
 \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
+The first API for DVB cards was used at Convergence in late 1999
+as 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
+
+In early 2000, Convergence was 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.
 
 
+In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
development
+of
+\href 
{http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
API Version 4}
+with public discussion on the linux-dvb mailing list. The goal was a 
complete
+new API, reflecting that PCs and embedded platforms are diverging. On a PC
+usually a budget card provides the full raw transport stream and decoding
+and processing is main CPU's task. On embedded platforms, however, data is
+multiplexed by specialized hardware or firmware for direct application use
+which relieves the main CPU from these tasks. Therefore, Linux DVB
+API Version 4 was suggested, but unfortunally never completed.
+
+
+Today, the LinuxTV project is an independend and non-profit community 
project
+by DVB/V4L enthusiasts and developers interested in Digital TV and 
Analog TV,
+sharing the same hg tree.
+
+However, this document describes only the digital TV part.
+
+
+With the further development of newer DTV standards, the existing version
+3 of the Linux DVB API was no longer able to support all DTV standards and
+newer hardware. Two concurrent approaches to overcome the problem where
+proposed, \texttt{Multiproto} and \texttt{S2API}.
+
+At
+\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
Plumbers Conference 2008}
+the decision was made towards to S2API, basically an extension to
+\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
+
+
+This Linux DVB API documentation will be extended to reflect these 
additions.
 \newpage
 \section{Overview}
 
@@ -49,7 +86,7 @@ provides a first implementation of the L
 \end{figure}
 
 
-A DVB PCI card or DVB set-top-box (STB) usually consists of the following
+A DVB device or DVB set-top-box (STB) usually consists of the following
 main hardware components:
 \begin{itemize}
 \item Frontend consisting of tuner and DVB demodulator
@@ -85,10 +122,10 @@ a TV set.
 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'').
+On a DVB 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 video
+and audio decoding) or is not needed (e.g. for data-only uses like
+``internet over satellite''). In fact, almost all new DTV devices use 
the CPU for MPEG decoding.
 Also not every card or STB provides conditional access hardware.
 
 \section{Linux DVB Devices}
@@ -117,12 +154,11 @@ All devices can be found in the \texttt{
 \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,
+where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
+these devices.
 
 More details about the data structures and function calls of
 all the devices are described in the following chapters.
@@ -137,10 +173,13 @@ in application sources with a partial pa
 #include <linux/dvb/frontend.h>
 \end{verbatim}
 
-To enable applications to support different API version, an additional
+To enable applications to support different API versions, 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}.
+\texttt{DVB\_API\_VERSION~5}.
+
+Since API version 5 an API command for quering API version also exists,
+allowing user space applications to detect API version during runtime.
 
 %%% Local Variables:

 


[-- Attachment #2: api_chapter1.diff --]
[-- Type: text/plain, Size: 8323 bytes --]

diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/dvbapi.tex v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/dvbapi.tex
--- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/dvbapi.tex	2009-02-22 17:07:48.123742503 +0100
+++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/dvbapi.tex	2009-02-21 17:33:29.557033066 +0100
@@ -1,4 +1,4 @@
-\documentclass[a4paper,10pt]{book}
+\documentclass[a4paper,10pt,oneside]{book}
 \usepackage[dvips,colorlinks=true]{hyperref}
 
 \usepackage{times}
diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/intro.tex v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/intro.tex
--- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/intro.tex	2009-02-18 13:49:37.000000000 +0100
+++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/intro.tex	2009-02-22 16:03:12.610230293 +0100
@@ -7,36 +7,73 @@
 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/}.
+i.e you should know what a program stream or 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++.
 
+The goal of this API is to provide a consistent abstraction layer for 
+different digital TV hardware, allowing software applications to be
+developed without hardware details as well as serving as driver
+developers reference.
+
+For this API documentation applies an even/odd versioning scheme, stating
+unstable or stable versions of that API. Only stable API versions should
+be used for developing drivers and applications.
+\newpage
 \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 
+The first API for DVB cards was used at Convergence in late 1999
+as 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
+
+In early 2000, Convergence was 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.
 
 
+In 2003 Convergence and Toshiba Electronics Europe GmbH started the development
+of 
+\href {http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB API Version 4} 
+with public discussion on the linux-dvb mailing list. The goal was a complete 
+new API, reflecting that PCs and embedded platforms are diverging. On a PC 
+usually a budget card provides the full raw transport stream and decoding 
+and processing is main CPU's task. On embedded platforms, however, data is
+multiplexed by specialized hardware or firmware for direct application use 
+which relieves the main CPU from these tasks. Therefore, Linux DVB
+API Version 4 was suggested, but unfortunally never completed.
+
+
+Today, the LinuxTV project is an independend and non-profit community project
+by DVB/V4L enthusiasts and developers interested in Digital TV and Analog TV,
+sharing the same hg tree.
+
+However, this document describes only the digital TV part.
+
+
+With the further development of newer DTV standards, the existing version
+3 of the Linux DVB API was no longer able to support all DTV standards and
+newer hardware. Two concurrent approaches to overcome the problem where
+proposed, \texttt{Multiproto} and \texttt{S2API}.
+
+At 
+\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux Plumbers Conference 2008} 
+the decision was made towards to S2API, basically an extension to
+\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
+
+
+This Linux DVB API documentation will be extended to reflect these additions.
 \newpage
 \section{Overview}
 
@@ -49,7 +86,7 @@ provides a first implementation of the L
 \end{figure}
 
 
-A DVB PCI card or DVB set-top-box (STB) usually consists of the following
+A DVB device or DVB set-top-box (STB) usually consists of the following
 main hardware components:
 \begin{itemize}
 \item Frontend consisting of tuner and DVB demodulator
@@ -85,10 +122,10 @@ a TV set.
 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'').
+On a DVB 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 video
+and audio decoding) or is not needed (e.g. for data-only uses like 
+``internet over satellite''). In fact, almost all new DTV devices use the CPU for MPEG decoding.
 Also not every card or STB provides conditional access hardware.
 
 \section{Linux DVB Devices}
@@ -117,12 +154,11 @@ All devices can be found in the \texttt{
 \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,
+where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
+these devices.
 
 More details about the data structures and function calls of 
 all the devices are described in the following chapters.
@@ -137,10 +173,13 @@ in application sources with a partial pa
 #include <linux/dvb/frontend.h>
 \end{verbatim}
 
-To enable applications to support different API version, an additional
+To enable applications to support different API versions, 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}.
+\texttt{DVB\_API\_VERSION~5}.
+
+Since API version 5 an API command for quering API version also exists, 
+allowing user space applications to detect API version during runtime.
 
 %%% Local Variables: 
 %%% mode: latex
diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/title.tex v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/title.tex
--- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/title.tex	2009-02-18 13:49:37.000000000 +0100
+++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/title.tex	2009-02-22 09:33:54.766093761 +0100
@@ -1,16 +1,20 @@
 \pagenumbering{arabic}
 \pagestyle{empty}
-\title{\huge\textbf{LINUX DVB API Version 3}}
+\title{\huge\textbf{LINUX DVB API Version 5}}
 
 \author{
 \includegraphics{cimlogo.psi}\\
-  Copyright 2002, 2003 Convergence GmbH\\\\
+  Copyright:\\
+  2002, 2003 Convergence GmbH,\\
+  2008, 2009 www.linuxtv.org\\\\
   Written by Dr. Ralph J.K. Metzler\\
-  \texttt{<rjkm@metzlerbros.de>}\\\\
+  \texttt{<rjkm@metzlerbros.de>}\\
   and Dr. Marcus O.C. Metzler\\
-  \texttt{<mocm@metzlerbros.de>}\\
+  \texttt{<mocm@metzlerbros.de>},\\
+  and The Linux DVB developers\\
+  \texttt{http://www.linuxtv.org}\\\\
 }
-\date{24/07/2003\\V 1.0.0}
+\date{22/02/2009\\Version 1.1.0}
 
 \maketitle
 

Re: [PATCH] dvb-api: update documentation, chapter1

[Mauro Carvalho Chehab]

On Sun, 22 Feb 2009 18:39:33 +0100
wk <handygewinnspiel@gmx.de> wrote:

> Since dvb-api doc is still outdated by six years...
> 
> 
> The following patch changes dvbapi.pdf as following:
> _______________________________________________________________________________
> 
> - change from twosided book format to singlesided book format.
>   * By doing so, the readability is improved and on the right-hand side
>     is more space on every second page.
> 
> - change copyright notice on first page by adding "2008, 2009 
> www.linuxtv.org"
> 
> - add "The Linux DVB Developers http://www.linuxtv.org" to 'written by'
> 
> - increase API Version number to 5
> 
> - change Version Number and date
>   -- 24/07/2003    V 1.0.0
>   ++ 22/02/2009    Version 1.1.0 <- unstable version now, every time api 
> is changed version should be increased now
> 
> - chapter 1 - What you need to know
>    * added goal: "consistent abstraction layer for
>      different digital TV hardware, allowing software applications to be
>      developed without hardware details as well as serving as driver 
> developers reference"
>    * added comment: odd api version numbers = unstable -> not to be used 
> for driver/app development
> 
> - chapter 1 - history
>   * add History of DVB API v 4
>   * add comment LinuxTV project beeing an independend and non-profit 
> community
>   * add reasons for DVB API v 5 and decision on Plumbers Conference 2008 
> towards S2API
> 
> - chapter 1 - Overview
>   * changed "DVB PCI card" wherever found, since API doesnt depend on 
> PCI bus
>   * changed "MPEG picture and sound decoding" to "MPEG video and audio 
> decoding",
>     since mpeg picture is misleading
> 
> - fix some typos inside chapter 1
> - fix "Overfull \hbox" warnings from chapter 1 (*only* chapter 1 for now..)
> 
> Signed-off-by: Winfried Koehler <handygewinnspiel@gmx.de>
> _______________________________________________________________________________
> 
> Please response, comment, improve, review, apply. Do not ignore silently,
> having a new API doc should be hard requirement for next kernel versions.

It follows a few comments.

> 
> diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/dvbapi.tex 
> v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/dvbapi.tex
> --- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/dvbapi.tex    2009-02-22 
> 17:07:48.123742503 +0100
> +++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/dvbapi.tex    2009-02-21 
> 17:33:29.557033066 +0100
> @@ -1,4 +1,4 @@
> -\documentclass[a4paper,10pt]{book}
> +\documentclass[a4paper,10pt,oneside]{book}
>  \usepackage[dvips,colorlinks=true]{hyperref}
>  
>  \usepackage{times}
> diff -Nrup v4l-dvb-359d95e1d541/dvb-spec/dvbapi/intro.tex 
> v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/intro.tex
> --- v4l-dvb-359d95e1d541/dvb-spec/dvbapi/intro.tex    2009-02-18 
> 13:49:37.000000000 +0100
> +++ v4l-dvb-a7ea3df69673/dvb-spec/dvbapi/intro.tex    2009-02-22 
> 16:03:12.610230293 +0100
> @@ -7,36 +7,73 @@
>  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/}.
> +i.e you should know what a program stream or 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++.
>  
> +The goal of this API is to provide a consistent abstraction layer for
> +different digital TV hardware, allowing software applications to be
> +developed without hardware details as well as serving as driver
> +developers reference.
> +
> +For this API documentation applies an even/odd versioning scheme, stating
> +unstable or stable versions of that API. Only stable API versions should
> +be used for developing drivers and applications.

Hmm... I wouldn't add the above. I don't think we should use such versioning scheme for docs.

> +\newpage
>  \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
> +The first API for DVB cards was used at Convergence in late 1999
> +as 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
> +
> +In early 2000, Convergence was 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.
>  
>  
> +In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
> development
> +of
> +\href 
> {http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
> API Version 4}
> +with public discussion on the linux-dvb mailing list. The goal was a 
> complete
> +new API, reflecting that PCs and embedded platforms are diverging. On a PC
> +usually a budget card provides the full raw transport stream and decoding
> +and processing is main CPU's task. On embedded platforms, however, data is
> +multiplexed by specialized hardware or firmware for direct application use
> +which relieves the main CPU from these tasks. Therefore, Linux DVB
> +API Version 4 was suggested, but unfortunally never completed.

It seems better to say, instead, that "Version 4 was suggested, but it weren't completed nor implemented".

> +
> +
> +Today, the LinuxTV project is an independend and non-profit community 
> project

s/independend/independent/

> +by DVB/V4L enthusiasts and developers interested in Digital TV and 
> Analog TV,
> +sharing the same hg tree.
> +
> +However, this document describes only the digital TV part.

I would replace the last paragraph by:

"This document describes the digital TV API. For Analog TV and radio, please consult V4L2 API."

IMO, we should also add such cross-reference at the V4L2 API, and point both to
linuxtv.org website (so, adding the corresponding \href pointers), for those
interested on getting the other API to know here both are available.

> +
> +
> +With the further development of newer DTV standards, the existing version
> +3 of the Linux DVB API was no longer able to support all DTV standards and
> +newer hardware. Two concurrent approaches to overcome the problem where
> +proposed, \texttt{Multiproto} and \texttt{S2API}.
> +
> +At
> +\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
> Plumbers Conference 2008}
> +the decision was made towards to S2API, basically an extension to
> +\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
> +
> +
> +This Linux DVB API documentation will be extended to reflect these 
> additions.

While we don't finish adding the S2API parts, maybe we should say instead:

This document is currently under review to reflect the S2API additions. 

>  \newpage
>  \section{Overview}
>  
> @@ -49,7 +86,7 @@ provides a first implementation of the L
>  \end{figure}
>  
>  
> -A DVB PCI card or DVB set-top-box (STB) usually consists of the following
> +A DVB device or DVB set-top-box (STB) usually consists of the following
>  main hardware components:
>  \begin{itemize}
>  \item Frontend consisting of tuner and DVB demodulator
> @@ -85,10 +122,10 @@ a TV set.
>  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'').
> +On a DVB 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 video
> +and audio decoding) or is not needed (e.g. for data-only uses like
> +``internet over satellite''). In fact, almost all new DTV devices use 
> the CPU for MPEG decoding.
>  Also not every card or STB provides conditional access hardware.
>  
>  \section{Linux DVB Devices}
> @@ -117,12 +154,11 @@ All devices can be found in the \texttt{
>  \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,
> +where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
> +these devices.
>  
>  More details about the data structures and function calls of
>  all the devices are described in the following chapters.
> @@ -137,10 +173,13 @@ in application sources with a partial pa
>  #include <linux/dvb/frontend.h>
>  \end{verbatim}
>  
> -To enable applications to support different API version, an additional
> +To enable applications to support different API versions, 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}.
> +\texttt{DVB\_API\_VERSION~5}.
> +
> +Since API version 5 an API command for quering API version also exists,
> +allowing user space applications to detect API version during runtime.
>  
>  %%% Local Variables:
> 
>  
> 

Cheers,
Mauro

Re: [PATCH] dvb-api: update documentation, chapter1

[VDR User]

On Thu, Feb 26, 2009 at 7:14 AM, Mauro Carvalho Chehab
<mchehab@infradead.org> wrote:
> It seems better to say, instead, that "Version 4 was suggested, but it weren't completed nor implemented".

That's improper.  I think you mean, "Version 4 was suggested but
neither completed, nor implemented".

Why do I have a feeling even the updated doc will be full of spelling
& grammatical errors?  ;)

>> +This Linux DVB API documentation will be extended to reflect these
>> additions.
>
> While we don't finish adding the S2API parts, maybe we should say instead:
>
> This document is currently under review to reflect the S2API additions.

Maybe you should say, "This documentation is a work-in-progress and
doesn't contain the full scope of newer additions year, such as
S2API".

Also, you might want to consider changing "DVB cards" to "DVB
devices".  For example, I don't know anybody who refers to USB DVB
devices as 'DVB cards'.

Cheers,
-Derek

Re: [PATCH] dvb-api: update documentation, chapter1

[wk]

[-- Attachment #1: Type: text/plain, Size: 12323 bytes --]

Mauro Carvalho Chehab wrote:
>> +
>> +For this API documentation applies an even/odd versioning scheme, stating
>> +unstable or stable versions of that API. Only stable API versions should
>> +be used for developing drivers and applications.
>>     
>
> Hmm... I wouldn't add the above. I don't think we should use such versioning scheme for docs.
>
>   

I removed that lines.

Can you please comment, how the dvb-developers want to deal with in 
future with the transition to a updated documentation?
By looking at the differences between headers and doc, it will take at 
least one year or even longer to finish.

Only a comment "currently under review" is probably not sufficient here.
Would it help to add a extra page "Revision History" like its done on 
v4l api? If so, please suggest a format for the page.


>>  
>> +In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
>> development
>> +of
>> +\href 
>> {http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
>> API Version 4}
>> +with public discussion on the linux-dvb mailing list. The goal was a 
>> complete
>> +new API, reflecting that PCs and embedded platforms are diverging. On a PC
>> +usually a budget card provides the full raw transport stream and decoding
>> +and processing is main CPU's task. On embedded platforms, however, data is
>> +multiplexed by specialized hardware or firmware for direct application use
>> +which relieves the main CPU from these tasks. Therefore, Linux DVB
>> +API Version 4 was suggested, but unfortunally never completed.
>>     
>
> It seems better to say, instead, that "Version 4 was suggested, but it weren't completed nor implemented".
>
>   

I put in here as suggested by Derek:

"Version 4 was suggested but neither completed, nor implemented"


>> +Today, the LinuxTV project is an independend and non-profit community 
>> project
>>     
>
> s/independend/independent/
>
>   

Changed.

>> +by DVB/V4L enthusiasts and developers interested in Digital TV and 
>> Analog TV,
>> +sharing the same hg tree.
>> +
>> +However, this document describes only the digital TV part.
>>     
>
> I would replace the last paragraph by:
>
> "This document describes the digital TV API. For Analog TV and radio, please consult V4L2 API."
>
> IMO, we should also add such cross-reference at the V4L2 API, and point both to
> linuxtv.org website (so, adding the corresponding \href pointers), for those
> interested on getting the other API to know here both are available.
>
>   

Changed and linked to   
http://www.linuxtv.org/downloads/video4linux/API/V4L2_API/v4l2spec/v4l2.pdf

>> +
>> +
>> +With the further development of newer DTV standards, the existing version
>> +3 of the Linux DVB API was no longer able to support all DTV standards and
>> +newer hardware. Two concurrent approaches to overcome the problem where
>> +proposed, \texttt{Multiproto} and \texttt{S2API}.
>> +
>> +At
>> +\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
>> Plumbers Conference 2008}
>> +the decision was made towards to S2API, basically an extension to
>> +\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
>> +
>> +
>> +This Linux DVB API documentation will be extended to reflect these 
>> additions.
>>     
>
> While we don't finish adding the S2API parts, maybe we should say instead:
>
> This document is currently under review to reflect the S2API additions. 
>
>   

Changed, but please answer the question above.
Also changed: "dvb card" -> "dvb device" as suggested by Derek.

updated patch below.

-- Winfried

--------------------------------------------------------------------------------------------------------------------------------

diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex 
v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex    2009-02-23 
16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex    2009-02-26 
18:40:35.008186330 +0100
@@ -1,4 +1,4 @@
-\documentclass[a4paper,10pt]{book}
+\documentclass[a4paper,10pt,oneside]{book}
 \usepackage[dvips,colorlinks=true]{hyperref}
 
 \usepackage{times}
diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex 
v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex    2009-02-23 
16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex    2009-02-26 
20:04:57.245819770 +0100
@@ -7,49 +7,84 @@
 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/}.
+i.e you should know what a program stream or 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++.
 
+The goal of this API is to provide a consistent abstraction layer for
+different digital TV hardware, allowing software applications to be
+developed without hardware details as well as serving as driver
+developers reference.
+
+\newpage
 \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
+The first API for DVB devices was used at Convergence in late 1999
+as an extension of the Video4Linux API which was primarily
+developed for frame grabber devices.
+
+
+As such it was not really well suited to be used for DVB devices 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
+
+In early 2000, Convergence was 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.
 
 
+In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
development
+of
+\href 
{http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
API Version 4}
+with public discussion on the linux-dvb mailing list. The goal was a 
complete
+new API, reflecting that PCs and embedded platforms are diverging. On a PC
+usually a budget device provides the full raw transport stream and 
decoding
+and processing is main CPU's task. On embedded platforms, however, data is
+multiplexed by specialized hardware or firmware for direct application use
+which relieves the main CPU from these tasks. Therefore, Linux DVB
+API Version 4 was suggested but neither completed, nor implemented.
+
+
+Today, the LinuxTV project is an independent and non-profit community 
project
+by DVB/V4L enthusiasts and developers interested in Digital TV and 
Analog TV,
+sharing the same hg tree.
+
+This document describes the digital TV API. For Analog TV and radio, 
please consult
+\href{http://www.linuxtv.org/downloads/video4linux/API/V4L2_API/v4l2spec/v4l2.pdf}{V4L2 
API}.
+
+
+With the further development of newer DTV standards, the existing version
+3 of the Linux DVB API was no longer able to support all DTV standards and
+newer hardware. Two concurrent approaches to overcome the problem where
+proposed, \texttt{Multiproto} and \texttt{S2API}.
+
+At
+\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
Plumbers Conference 2008}
+the decision was made towards to S2API, basically an extension to
+\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
+
+
+This document is currently under review to reflect the S2API additions.
 \newpage
 \section{Overview}
 
 \begin{figure}[htbp]
   \begin{center}
     \includegraphics{dvbstb.ps}
-    \caption{Components of a DVB card/STB}
+    \caption{Components of a DVB device/STB}
     \label{fig:dvbstb}
   \end{center}
 \end{figure}
 
 
-A DVB PCI card or DVB set-top-box (STB) usually consists of the following
+A DVB device or DVB set-top-box (STB) usually consists of the following
 main hardware components:
 \begin{itemize}
 \item Frontend consisting of tuner and DVB demodulator
@@ -85,11 +120,11 @@ a TV set.
 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.
+On a DVB device not all of these have to be present since some
+functionality can be provided by the main CPU of the PC (e.g. MPEG video
+and audio decoding) or is not needed (e.g. for data-only uses like
+``internet over satellite''). In fact, almost all new DTV devices use 
the CPU for MPEG decoding.
+Also not every device or STB provides conditional access hardware.
 
 \section{Linux DVB Devices}
 
@@ -117,12 +152,11 @@ All devices can be found in the \texttt{
 \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,
+where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
+these devices.
 
 More details about the data structures and function calls of
 all the devices are described in the following chapters.
@@ -137,10 +171,13 @@ in application sources with a partial pa
 #include <linux/dvb/frontend.h>
 \end{verbatim}
 
-To enable applications to support different API version, an additional
+To enable applications to support different API versions, 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}.
+\texttt{DVB\_API\_VERSION~5}.
+
+Since API version 5 an API command for quering API version also exists,
+allowing user space applications to detect API version during runtime.
 
 %%% Local Variables:
 %%% mode: latex
diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex 
v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex    2009-02-23 
16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex    2009-02-26 
18:40:35.008186330 +0100
@@ -1,16 +1,20 @@
 \pagenumbering{arabic}
 \pagestyle{empty}
-\title{\huge\textbf{LINUX DVB API Version 3}}
+\title{\huge\textbf{LINUX DVB API Version 5}}
 
 \author{
 \includegraphics{cimlogo.psi}\\
-  Copyright 2002, 2003 Convergence GmbH\\\\
+  Copyright:\\
+  2002, 2003 Convergence GmbH,\\
+  2008, 2009 www.linuxtv.org\\\\
   Written by Dr. Ralph J.K. Metzler\\
-  \texttt{<rjkm@metzlerbros.de>}\\\\
+  \texttt{<rjkm@metzlerbros.de>}\\
   and Dr. Marcus O.C. Metzler\\
-  \texttt{<mocm@metzlerbros.de>}\\
+  \texttt{<mocm@metzlerbros.de>},\\
+  and The Linux DVB developers\\
+  \texttt{http://www.linuxtv.org}\\\\
 }
-\date{24/07/2003\\V 1.0.0}
+\date{22/02/2009\\Version 1.1.0}
 
 \maketitle
 




[-- Attachment #2: api_chapter1_1.diff --]
[-- Type: text/plain, Size: 8585 bytes --]

diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex	2009-02-23 16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex	2009-02-26 18:40:35.008186330 +0100
@@ -1,4 +1,4 @@
-\documentclass[a4paper,10pt]{book}
+\documentclass[a4paper,10pt,oneside]{book}
 \usepackage[dvips,colorlinks=true]{hyperref}
 
 \usepackage{times}
diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex	2009-02-23 16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex	2009-02-26 20:04:57.245819770 +0100
@@ -7,49 +7,84 @@
 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/}.
+i.e you should know what a program stream or 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++.
 
+The goal of this API is to provide a consistent abstraction layer for 
+different digital TV hardware, allowing software applications to be
+developed without hardware details as well as serving as driver
+developers reference.
+
+\newpage
 \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 
+The first API for DVB devices was used at Convergence in late 1999
+as an extension of the Video4Linux API which was primarily 
+developed for frame grabber devices.
+
+
+As such it was not really well suited to be used for DVB devices 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
+
+In early 2000, Convergence was 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.
 
 
+In 2003 Convergence and Toshiba Electronics Europe GmbH started the development
+of 
+\href {http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB API Version 4} 
+with public discussion on the linux-dvb mailing list. The goal was a complete 
+new API, reflecting that PCs and embedded platforms are diverging. On a PC 
+usually a budget device provides the full raw transport stream and decoding 
+and processing is main CPU's task. On embedded platforms, however, data is
+multiplexed by specialized hardware or firmware for direct application use 
+which relieves the main CPU from these tasks. Therefore, Linux DVB
+API Version 4 was suggested but neither completed, nor implemented.
+
+
+Today, the LinuxTV project is an independent and non-profit community project
+by DVB/V4L enthusiasts and developers interested in Digital TV and Analog TV,
+sharing the same hg tree.
+
+This document describes the digital TV API. For Analog TV and radio, please consult 
+\href{http://www.linuxtv.org/downloads/video4linux/API/V4L2_API/v4l2spec/v4l2.pdf}{V4L2 API}.
+
+
+With the further development of newer DTV standards, the existing version
+3 of the Linux DVB API was no longer able to support all DTV standards and
+newer hardware. Two concurrent approaches to overcome the problem where
+proposed, \texttt{Multiproto} and \texttt{S2API}.
+
+At 
+\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux Plumbers Conference 2008} 
+the decision was made towards to S2API, basically an extension to
+\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
+
+
+This document is currently under review to reflect the S2API additions.
 \newpage
 \section{Overview}
 
 \begin{figure}[htbp]
   \begin{center}
     \includegraphics{dvbstb.ps}
-    \caption{Components of a DVB card/STB}
+    \caption{Components of a DVB device/STB}
     \label{fig:dvbstb}
   \end{center}
 \end{figure}
 
 
-A DVB PCI card or DVB set-top-box (STB) usually consists of the following
+A DVB device or DVB set-top-box (STB) usually consists of the following
 main hardware components:
 \begin{itemize}
 \item Frontend consisting of tuner and DVB demodulator
@@ -85,11 +120,11 @@ a TV set.
 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.
+On a DVB device not all of these have to be present since some 
+functionality can be provided by the main CPU of the PC (e.g. MPEG video
+and audio decoding) or is not needed (e.g. for data-only uses like 
+``internet over satellite''). In fact, almost all new DTV devices use the CPU for MPEG decoding.
+Also not every device or STB provides conditional access hardware.
 
 \section{Linux DVB Devices}
 
@@ -117,12 +152,11 @@ All devices can be found in the \texttt{
 \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,
+where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
+these devices.
 
 More details about the data structures and function calls of 
 all the devices are described in the following chapters.
@@ -137,10 +171,13 @@ in application sources with a partial pa
 #include <linux/dvb/frontend.h>
 \end{verbatim}
 
-To enable applications to support different API version, an additional
+To enable applications to support different API versions, 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}.
+\texttt{DVB\_API\_VERSION~5}.
+
+Since API version 5 an API command for quering API version also exists, 
+allowing user space applications to detect API version during runtime.
 
 %%% Local Variables: 
 %%% mode: latex
diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex	2009-02-23 16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex	2009-02-26 18:40:35.008186330 +0100
@@ -1,16 +1,20 @@
 \pagenumbering{arabic}
 \pagestyle{empty}
-\title{\huge\textbf{LINUX DVB API Version 3}}
+\title{\huge\textbf{LINUX DVB API Version 5}}
 
 \author{
 \includegraphics{cimlogo.psi}\\
-  Copyright 2002, 2003 Convergence GmbH\\\\
+  Copyright:\\
+  2002, 2003 Convergence GmbH,\\
+  2008, 2009 www.linuxtv.org\\\\
   Written by Dr. Ralph J.K. Metzler\\
-  \texttt{<rjkm@metzlerbros.de>}\\\\
+  \texttt{<rjkm@metzlerbros.de>}\\
   and Dr. Marcus O.C. Metzler\\
-  \texttt{<mocm@metzlerbros.de>}\\
+  \texttt{<mocm@metzlerbros.de>},\\
+  and The Linux DVB developers\\
+  \texttt{http://www.linuxtv.org}\\\\
 }
-\date{24/07/2003\\V 1.0.0}
+\date{22/02/2009\\Version 1.1.0}
 
 \maketitle
 

Re: [PATCH] dvb-api: update documentation, chapter1

[VDR User]

On Thu, Feb 26, 2009 at 8:35 AM, VDR User <user.vdr@gmail.com> wrote:
>> It seems better to say, instead, that "Version 4 was suggested, but it weren't completed nor implemented".
>
> That's improper.  I think you mean, "Version 4 was suggested but
> neither completed, nor implemented".
>
> Why do I have a feeling even the updated doc will be full of spelling
> & grammatical errors?  ;)

See below for the irony.

>>> +This Linux DVB API documentation will be extended to reflect these
>>> additions.
>>
>> While we don't finish adding the S2API parts, maybe we should say instead:
>>
>> This document is currently under review to reflect the S2API additions.
>
> Maybe you should say, "This documentation is a work-in-progress and
> doesn't contain the full scope of newer additions year, such as
> S2API".

Err...  s/yet/year in that last line.  Oops! ;)

Re: [PATCH] dvb-api: update documentation, chapter1

[wk]

> Why do I have a feeling even the updated doc will be full of spelling
> & grammatical errors?  ;)
>
>   

Probably, because none of the writers so far where native English.
Therefore i'am really happy that *you* now took over all the 
responsibility to find all that spelling and grammatical errors.
;-)

> Also, you might want to consider changing "DVB cards" to "DVB
> devices".  For example, I don't know anybody who refers to USB DVB
> devices as 'DVB cards'.
>
>   

Yes, makes sense. But at the writing time of that API- more then 6 years 
ago - most probably nobody was thinking of USB for a DVB device.

--Winfried

Re: [PATCH] dvb-api: update documentation, chapter1

[Mauro Carvalho Chehab]

Hi wk,

Let's commit what we currently have. Could you please re-submit the patch
again, this time providing a proper description, and your SOB?

Cheers,
Mauro.

On Thu, 26 Feb 2009 20:19:41 +0100
wk <handygewinnspiel@gmx.de> wrote:

> Mauro Carvalho Chehab wrote:
> >> +
> >> +For this API documentation applies an even/odd versioning scheme, stating
> >> +unstable or stable versions of that API. Only stable API versions should
> >> +be used for developing drivers and applications.
> >>     
> >
> > Hmm... I wouldn't add the above. I don't think we should use such versioning scheme for docs.
> >
> >   
> 
> I removed that lines.
> 
> Can you please comment, how the dvb-developers want to deal with in 
> future with the transition to a updated documentation?
> By looking at the differences between headers and doc, it will take at 
> least one year or even longer to finish.
> 
> Only a comment "currently under review" is probably not sufficient here.
> Would it help to add a extra page "Revision History" like its done on 
> v4l api? If so, please suggest a format for the page.
> 
> 
> >>  
> >> +In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
> >> development
> >> +of
> >> +\href 
> >> {http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
> >> API Version 4}
> >> +with public discussion on the linux-dvb mailing list. The goal was a 
> >> complete
> >> +new API, reflecting that PCs and embedded platforms are diverging. On a PC
> >> +usually a budget card provides the full raw transport stream and decoding
> >> +and processing is main CPU's task. On embedded platforms, however, data is
> >> +multiplexed by specialized hardware or firmware for direct application use
> >> +which relieves the main CPU from these tasks. Therefore, Linux DVB
> >> +API Version 4 was suggested, but unfortunally never completed.
> >>     
> >
> > It seems better to say, instead, that "Version 4 was suggested, but it weren't completed nor implemented".
> >
> >   
> 
> I put in here as suggested by Derek:
> 
> "Version 4 was suggested but neither completed, nor implemented"
> 
> 
> >> +Today, the LinuxTV project is an independend and non-profit community 
> >> project
> >>     
> >
> > s/independend/independent/
> >
> >   
> 
> Changed.
> 
> >> +by DVB/V4L enthusiasts and developers interested in Digital TV and 
> >> Analog TV,
> >> +sharing the same hg tree.
> >> +
> >> +However, this document describes only the digital TV part.
> >>     
> >
> > I would replace the last paragraph by:
> >
> > "This document describes the digital TV API. For Analog TV and radio, please consult V4L2 API."
> >
> > IMO, we should also add such cross-reference at the V4L2 API, and point both to
> > linuxtv.org website (so, adding the corresponding \href pointers), for those
> > interested on getting the other API to know here both are available.
> >
> >   
> 
> Changed and linked to   
> http://www.linuxtv.org/downloads/video4linux/API/V4L2_API/v4l2spec/v4l2.pdf
> 
> >> +
> >> +
> >> +With the further development of newer DTV standards, the existing version
> >> +3 of the Linux DVB API was no longer able to support all DTV standards and
> >> +newer hardware. Two concurrent approaches to overcome the problem where
> >> +proposed, \texttt{Multiproto} and \texttt{S2API}.
> >> +
> >> +At
> >> +\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
> >> Plumbers Conference 2008}
> >> +the decision was made towards to S2API, basically an extension to
> >> +\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
> >> +
> >> +
> >> +This Linux DVB API documentation will be extended to reflect these 
> >> additions.
> >>     
> >
> > While we don't finish adding the S2API parts, maybe we should say instead:
> >
> > This document is currently under review to reflect the S2API additions. 
> >
> >   
> 
> Changed, but please answer the question above.
> Also changed: "dvb card" -> "dvb device" as suggested by Derek.
> 
> updated patch below.
> 
> -- Winfried
> 
> --------------------------------------------------------------------------------------------------------------------------------
> 
> diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex 
> v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex
> --- v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex    2009-02-23 
> 16:26:38.000000000 +0100
> +++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex    2009-02-26 
> 18:40:35.008186330 +0100
> @@ -1,4 +1,4 @@
> -\documentclass[a4paper,10pt]{book}
> +\documentclass[a4paper,10pt,oneside]{book}
>  \usepackage[dvips,colorlinks=true]{hyperref}
>  
>  \usepackage{times}
> diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex 
> v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex
> --- v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex    2009-02-23 
> 16:26:38.000000000 +0100
> +++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex    2009-02-26 
> 20:04:57.245819770 +0100
> @@ -7,49 +7,84 @@
>  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/}.
> +i.e you should know what a program stream or 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++.
>  
> +The goal of this API is to provide a consistent abstraction layer for
> +different digital TV hardware, allowing software applications to be
> +developed without hardware details as well as serving as driver
> +developers reference.
> +
> +\newpage
>  \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
> +The first API for DVB devices was used at Convergence in late 1999
> +as an extension of the Video4Linux API which was primarily
> +developed for frame grabber devices.
> +
> +
> +As such it was not really well suited to be used for DVB devices 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
> +
> +In early 2000, Convergence was 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.
>  
>  
> +In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
> development
> +of
> +\href 
> {http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
> API Version 4}
> +with public discussion on the linux-dvb mailing list. The goal was a 
> complete
> +new API, reflecting that PCs and embedded platforms are diverging. On a PC
> +usually a budget device provides the full raw transport stream and 
> decoding
> +and processing is main CPU's task. On embedded platforms, however, data is
> +multiplexed by specialized hardware or firmware for direct application use
> +which relieves the main CPU from these tasks. Therefore, Linux DVB
> +API Version 4 was suggested but neither completed, nor implemented.
> +
> +
> +Today, the LinuxTV project is an independent and non-profit community 
> project
> +by DVB/V4L enthusiasts and developers interested in Digital TV and 
> Analog TV,
> +sharing the same hg tree.
> +
> +This document describes the digital TV API. For Analog TV and radio, 
> please consult
> +\href{http://www.linuxtv.org/downloads/video4linux/API/V4L2_API/v4l2spec/v4l2.pdf}{V4L2 
> API}.
> +
> +
> +With the further development of newer DTV standards, the existing version
> +3 of the Linux DVB API was no longer able to support all DTV standards and
> +newer hardware. Two concurrent approaches to overcome the problem where
> +proposed, \texttt{Multiproto} and \texttt{S2API}.
> +
> +At
> +\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
> Plumbers Conference 2008}
> +the decision was made towards to S2API, basically an extension to
> +\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
> +
> +
> +This document is currently under review to reflect the S2API additions.
>  \newpage
>  \section{Overview}
>  
>  \begin{figure}[htbp]
>    \begin{center}
>      \includegraphics{dvbstb.ps}
> -    \caption{Components of a DVB card/STB}
> +    \caption{Components of a DVB device/STB}
>      \label{fig:dvbstb}
>    \end{center}
>  \end{figure}
>  
>  
> -A DVB PCI card or DVB set-top-box (STB) usually consists of the following
> +A DVB device or DVB set-top-box (STB) usually consists of the following
>  main hardware components:
>  \begin{itemize}
>  \item Frontend consisting of tuner and DVB demodulator
> @@ -85,11 +120,11 @@ a TV set.
>  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.
> +On a DVB device not all of these have to be present since some
> +functionality can be provided by the main CPU of the PC (e.g. MPEG video
> +and audio decoding) or is not needed (e.g. for data-only uses like
> +``internet over satellite''). In fact, almost all new DTV devices use 
> the CPU for MPEG decoding.
> +Also not every device or STB provides conditional access hardware.
>  
>  \section{Linux DVB Devices}
>  
> @@ -117,12 +152,11 @@ All devices can be found in the \texttt{
>  \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,
> +where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
> +these devices.
>  
>  More details about the data structures and function calls of
>  all the devices are described in the following chapters.
> @@ -137,10 +171,13 @@ in application sources with a partial pa
>  #include <linux/dvb/frontend.h>
>  \end{verbatim}
>  
> -To enable applications to support different API version, an additional
> +To enable applications to support different API versions, 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}.
> +\texttt{DVB\_API\_VERSION~5}.
> +
> +Since API version 5 an API command for quering API version also exists,
> +allowing user space applications to detect API version during runtime.
>  
>  %%% Local Variables:
>  %%% mode: latex
> diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex 
> v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex
> --- v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex    2009-02-23 
> 16:26:38.000000000 +0100
> +++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex    2009-02-26 
> 18:40:35.008186330 +0100
> @@ -1,16 +1,20 @@
>  \pagenumbering{arabic}
>  \pagestyle{empty}
> -\title{\huge\textbf{LINUX DVB API Version 3}}
> +\title{\huge\textbf{LINUX DVB API Version 5}}
>  
>  \author{
>  \includegraphics{cimlogo.psi}\\
> -  Copyright 2002, 2003 Convergence GmbH\\\\
> +  Copyright:\\
> +  2002, 2003 Convergence GmbH,\\
> +  2008, 2009 www.linuxtv.org\\\\
>    Written by Dr. Ralph J.K. Metzler\\
> -  \texttt{<rjkm@metzlerbros.de>}\\\\
> +  \texttt{<rjkm@metzlerbros.de>}\\
>    and Dr. Marcus O.C. Metzler\\
> -  \texttt{<mocm@metzlerbros.de>}\\
> +  \texttt{<mocm@metzlerbros.de>},\\
> +  and The Linux DVB developers\\
> +  \texttt{http://www.linuxtv.org}\\\\
>  }
> -\date{24/07/2003\\V 1.0.0}
> +\date{22/02/2009\\Version 1.1.0}
>  
>  \maketitle
>  
> 
> 
> 




Cheers,
Mauro

[PATCH] dvb-api: update documentation, chapter1 (Resubmit)

[wk]

Mauro Carvalho Chehab schrieb:
> Hi wk,
>
> Let's commit what we currently have. Could you please re-submit the patch
> again, this time providing a proper description, and your SOB?
>
> Cheers,
> Mauro.
>   
The attached patch provides the following changes to DVB API:
- files changed
      - dvbapi.tex
      - intro.tex
      - title.tex

- change page format from "twosided book" to "onesided book" to improve 
readability
- fix several latex compiling warnings "Overfull \hbox" due to too long 
lines.
- replace in chapter 1 all occurrencies of "DVB PCI card" with "DVB device"

- change First Page:
      - add "and The Linux DVB developers" to Copyright
      - add "2008, 2009 www.linuxtv.org" to Copyright
      - change version and date to "22/02/2009 Version 1.1.0"

- change Chapter 1, Section 1.2 History:
      - remove line that Convergence is maintainer of doc, since in fact 
linuxtv.org is currently maintaining it.
      - remove line "Together with the LinuxTV community (i.e. you, the 
reader of this document),
                    the Linux DVB API will be constantly reviewed and 
improved."
      - remove line "With the Linux driver for the Siemens/Hauppauge DVB 
PCI card Convergence
                     provides a first implementation of the Linux DVB API"
      - add comment about neither completed, nor implemented DVB API v4
      - add comment about being project independent and non-profit
      - add comment describing digital part only and cross-reference to 
V4L2 API on linuxtv
      - add comment about need for API extension for newer DTV standards
      - add comment about Multiproto and S2API and decision on plumbers 
conference 2k8
      - add comment about version now called v5

- change Chapter 1, Section 1.3 Overview:
      -  change "MPEG picture and sound decoding" to "MPEG video and 
audio decoding"

- change Chapter 1, Section 1.4 Linux DVB Devices
      -  remove reference to no longer used devfs

- change Chapter 1, Section 1.5 API include files
      -  fix typo: "to support different API version" -> "to support 
different API versions"
      -  add "Since API version 5 an API command for quering API version 
also exists,
                    allowing user space applications to detect API 
version during runtime"

          =>  see also:   
http://www.linuxtv.org/news.php?entry=2008-09-23.mchehab
                  "Adding an API command for querying DVB version, to 
allow an easier detection by userspaceapplications"


Signed-off-by: Winfried Koehler <handygew...@gmx.de>

---------------------------------------------------------------------------- 

diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex 
v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/dvbapi.tex    2009-02-23 
16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/dvbapi.tex    2009-02-26 
18:40:35.008186330 +0100
@@ -1,4 +1,4 @@
-\documentclass[a4paper,10pt]{book}
+\documentclass[a4paper,10pt,oneside]{book}
 \usepackage[dvips,colorlinks=true]{hyperref}
 
 \usepackage{times}
diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex 
v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/intro.tex    2009-02-23 
16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/intro.tex    2009-02-26 
20:04:57.245819770 +0100
@@ -7,49 +7,84 @@
 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/}.
+i.e you should know what a program stream or 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++.
 
+The goal of this API is to provide a consistent abstraction layer for
+different digital TV hardware, allowing software applications to be
+developed without hardware details as well as serving as driver
+developers reference.
+
+\newpage
 \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
+The first API for DVB devices was used at Convergence in late 1999
+as an extension of the Video4Linux API which was primarily
+developed for frame grabber devices.
+
+
+As such it was not really well suited to be used for DVB devices 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
+
+In early 2000, Convergence was 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.
 
 
+In 2003 Convergence and Toshiba Electronics Europe GmbH started the 
development
+of
+\href 
{http://www.linuxtv.org/downloads/linux-dvb-api-v4/linux-dvb-api-v4-0-3.pdf}{DVB 
API Version 4}
+with public discussion on the linux-dvb mailing list. The goal was a 
complete
+new API, reflecting that PCs and embedded platforms are diverging. On a PC
+usually a budget device provides the full raw transport stream and 
decoding
+and processing is main CPU's task. On embedded platforms, however, data is
+multiplexed by specialized hardware or firmware for direct application use
+which relieves the main CPU from these tasks. Therefore, Linux DVB
+API Version 4 was suggested but neither completed, nor implemented.
+
+
+Today, the LinuxTV project is an independent and non-profit community 
project
+by DVB/V4L enthusiasts and developers interested in Digital TV and 
Analog TV,
+sharing the same hg tree.
+
+This document describes the digital TV API. For Analog TV and radio, 
please consult
+\href{http://www.linuxtv.org/downloads/video4linux/API/V4L2_API/v4l2spec/v4l2.pdf}{V4L2 
API}.
+
+
+With the further development of newer DTV standards, the existing version
+3 of the Linux DVB API was no longer able to support all DTV standards and
+newer hardware. Two concurrent approaches to overcome the problem where
+proposed, \texttt{Multiproto} and \texttt{S2API}.
+
+At
+\href {http://www.linuxtv.org/news.php?entry=2008-09-19.mchehab}{Linux 
Plumbers Conference 2008}
+the decision was made towards to S2API, basically an extension to
+\texttt{DVB API Version 3} called \texttt{DVB API Version 5}.
+
+
+This document is currently under review to reflect the S2API additions.
 \newpage
 \section{Overview}
 
 \begin{figure}[htbp]
   \begin{center}
     \includegraphics{dvbstb.ps}
-    \caption{Components of a DVB card/STB}
+    \caption{Components of a DVB device/STB}
     \label{fig:dvbstb}
   \end{center}
 \end{figure}
 
 
-A DVB PCI card or DVB set-top-box (STB) usually consists of the following
+A DVB device or DVB set-top-box (STB) usually consists of the following
 main hardware components:
 \begin{itemize}
 \item Frontend consisting of tuner and DVB demodulator
@@ -85,11 +120,11 @@ a TV set.
 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.
+On a DVB device not all of these have to be present since some
+functionality can be provided by the main CPU of the PC (e.g. MPEG video
+and audio decoding) or is not needed (e.g. for data-only uses like
+``internet over satellite''). In fact, almost all new DTV devices use 
the CPU for MPEG decoding.
+Also not every device or STB provides conditional access hardware.
 
 \section{Linux DVB Devices}
 
@@ -117,12 +152,11 @@ All devices can be found in the \texttt{
 \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,
+where N enumerates the DVB adapters (pci cards, usb devices, ..) 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.
+these devices.
 
 More details about the data structures and function calls of
 all the devices are described in the following chapters.
@@ -137,10 +171,13 @@ in application sources with a partial pa
 #include <linux/dvb/frontend.h>
 \end{verbatim}
 
-To enable applications to support different API version, an additional
+To enable applications to support different API versions, 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}.
+\texttt{DVB\_API\_VERSION~5}.
+
+Since API version 5 an API command for quering API version also exists,
+allowing user space applications to detect API version during runtime.
 
 %%% Local Variables:
 %%% mode: latex
diff -Nurp v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex 
v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex
--- v4l-dvb-17554cc18063/dvb-spec/dvbapi/title.tex    2009-02-23 
16:26:38.000000000 +0100
+++ v4l-dvb-17554cc18063_1/dvb-spec/dvbapi/title.tex    2009-02-26 
18:40:35.008186330 +0100
@@ -1,16 +1,20 @@
 \pagenumbering{arabic}
 \pagestyle{empty}
-\title{\huge\textbf{LINUX DVB API Version 3}}
+\title{\huge\textbf{LINUX DVB API Version 5}}
 
 \author{
 \includegraphics{cimlogo.psi}\\
-  Copyright 2002, 2003 Convergence GmbH\\\\
+  Copyright:\\
+  2002, 2003 Convergence GmbH,\\
+  2008, 2009 www.linuxtv.org\\\\
   Written by Dr. Ralph J.K. Metzler\\
-  \texttt{<rjkm@metzlerbros.de>}\\\\
+  \texttt{<rjkm@metzlerbros.de>}\\
   and Dr. Marcus O.C. Metzler\\
-  \texttt{<mocm@metzlerbros.de>}\\
+  \texttt{<mocm@metzlerbros.de>},\\
+  and The Linux DVB developers\\
+  \texttt{http://www.linuxtv.org}\\\\
 }
-\date{24/07/2003\\V 1.0.0}
+\date{22/02/2009\\Version 1.1.0}
 
 \maketitle