diff options
author | Mauro Carvalho Chehab <mchehab@redhat.com> | 2009-09-06 10:48:52 -0300 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2009-09-06 10:48:52 -0300 |
commit | 89577c08b573b6e0d0474da70483aa7b8faea4b9 (patch) | |
tree | 0763b1657c4f1793781be245d5ba687b517f6524 /dvb-spec | |
parent | 00c1eda676d0707af2602f156278772fe3c30cb8 (diff) | |
download | mediapointer-dvb-s2-89577c08b573b6e0d0474da70483aa7b8faea4b9.tar.gz mediapointer-dvb-s2-89577c08b573b6e0d0474da70483aa7b8faea4b9.tar.bz2 |
dvb-spec: Start a DocBook XML 4.1.2 version of DVB API docs
From: Mauro Carvalho Chehab <mchehab@redhat.com>
This is an unfinished work. It is a port of DVB API verison 3 from LaTex
into DocBook.
Currently, only chapters 1 and 2 were converted. Still pending the
conversion of the remaining chapters and a good style revision after the
end of the conversion.
Priority: normal
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'dvb-spec')
-rw-r--r-- | dvb-spec/sgml/Makefile | 135 | ||||
-rw-r--r-- | dvb-spec/sgml/README | 13 | ||||
-rw-r--r-- | dvb-spec/sgml/custom.dsl | 52 | ||||
-rw-r--r-- | dvb-spec/sgml/custom.xsl | 29 | ||||
-rw-r--r-- | dvb-spec/sgml/devices.sgml | 0 | ||||
-rw-r--r-- | dvb-spec/sgml/dvbapi-complete.sgml | 9878 | ||||
-rw-r--r-- | dvb-spec/sgml/dvbapi.sgml | 97 | ||||
-rw-r--r-- | dvb-spec/sgml/dvbstb.pdf | bin | 0 -> 1786 bytes | |||
-rw-r--r-- | dvb-spec/sgml/dvbstb.png | bin | 0 -> 22655 bytes | |||
-rw-r--r-- | dvb-spec/sgml/examples.sgml | 0 | ||||
-rw-r--r-- | dvb-spec/sgml/fdl.sgml | 0 | ||||
-rw-r--r-- | dvb-spec/sgml/frontend.sgml | 1816 | ||||
-rw-r--r-- | dvb-spec/sgml/intro.sgml | 191 |
13 files changed, 12211 insertions, 0 deletions
diff --git a/dvb-spec/sgml/Makefile b/dvb-spec/sgml/Makefile new file mode 100644 index 000000000..f39d7a97c --- /dev/null +++ b/dvb-spec/sgml/Makefile @@ -0,0 +1,135 @@ +SHELL=/bin/bash + +SGMLS = \ + dvbapi.sgml \ + intro.sgml \ + frontend.sgml \ + devices.sgml \ + examples.sgml \ + fdl.sgml \ + entities.sgml \ + +PDFPICS = \ + dvbstb.pdf \ + +GIFPICS = \ + dvbstb.png \ + +# Some Jade warnings for authors. +WARN = +#WARN = -w all -w duplicate -w net + +# Stylesheet customization. + # docbook/db2 syntax +CUSTOM_HTML = --dsl custom.dsl\#html +CUSTOM_PRINT = --dsl custom.dsl\#print + # xmlto syntax +CUSTOM_HTML_XMLTO = -m custom.xsl +CUSTOM_PRINT_XMLTO = -m custom.xsl + +all: html-single + +html: html-build.stamp + +html-single: html-single-build.stamp + +pdf: pdf-build.stamp + +man: man-build.stamp + +man_install: man-build.stamp + install -d /usr/local/man/man2 + install -b man/* /usr/local/man/man2 + +entities.sgml: Makefile + echo "<!-- Generated file! Do not edit. -->" >$@ + echo -e "\n<!-- Subsections -->" >>$@ + for file in $(SGMLS) ; do \ + entity=`echo "$$file" | sed 's/.sgml//;s/\./-/g'` ; \ + if ! echo "$$file" | \ + grep -q -E -e '^(func|vidioc|pixfmt)-' ; then \ + echo "<!ENTITY sub-$$entity SYSTEM \"$$file\">" >>$@ ; \ + fi ; \ + done + +# Jade can auto-generate a list-of-tables, which includes all structs, +# but we only want data types, all types, and sorted please. +indices.sgml: Makefile + echo "<!-- Generated file! Do not edit. -->" >$@ + echo -e "\n<index><title>List of Types</title>" >>$@ + for ident in $(TYPES) ; do \ + id=`echo $$ident | tr _ -` ; \ + echo "<indexentry><primaryie><link" \ + "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \ + done + for ident in $(ENUMS) ; do \ + echo "<indexentry><primaryie>enum <link" \ + "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \ + done + for ident in $(STRUCTS) ; do \ + id=`echo $$ident | tr _ -` ; \ + echo "<indexentry><primaryie>struct <link" \ + "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \ + done + echo "</index>" >>$@ + +# HTML version. +html-build.stamp: Makefile $(SGMLS) $(GIFPICS) + rm -rf dvbapi + if which xmlto >/dev/null ; then \ + xmlto xhtml $(WARN) $(CUSTOM_HTML_XMLTO) -o dvbapi dvbapi.sgml ; \ + elif which docbook2html >/dev/null ; then \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + docbook2html $(WARN) $$DCL $(CUSTOM_HTML) --output dvbapi dvbapi.sgml ; \ + else \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + db2html $(WARN) $$DCL $(CUSTOM_HTML) --output dvbapi dvbapi.sgml ; \ + fi + cp $(GIFPICS) dvbapi/ + cd dvbapi ; \ + test -e index.html || ln -s book1.htm index.html ; \ + test -e capture-example.html || \ + ln -s `grep -l getopt_long *.htm` capture-example.html + chmod a+rX -R dvbapi + touch html-build.stamp + +# For online version. When you have a dial-up connection a single file +# is more convenient than clicking through dozens of pages. +html-single-build.stamp: Makefile $(SGMLS) $(GIFPICS) + rm -rf dvbapi-single + if which xmlto >/dev/null ; then \ + xmlto html-nochunks $(WARN) $(CUSTOM_HTML_XMLTO) -o dvbapi-single dvbapi.sgml ; \ + elif which docbook2html >/dev/null ; then \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + docbook2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \ + --output dvbapi-single dvbapi.sgml ; \ + else \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + db2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \ + --output dvbapi-single dvbapi.sgml ; \ + fi + cp $(GIFPICS) dvbapi-single/ + chmod a+rX -R dvbapi-single + touch html-single-build.stamp + +# For printing. +pdf-build.stamp: Makefile $(SGMLS) $(PDFPICS) + if which db2pdf >/dev/null ; then \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl|head -1`"; \ + db2pdf $$DCL $(WARN) $(CUSTOM_PRINT) dvbapi.sgml ; \ + elif which xmlto >/dev/null ; then \ + xmlto pdf $(WARN) $(CUSTOM_HTML_XMLTO) -o dvbapi-single dvbapi.sgml ; \ + else \ + export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \ + docbook2pdf $$DCL $(WARN) $(CUSTOM_PRINT) dvbapi.sgml ; \ + fi + touch pdf-build.stamp + + +# For man +man-build.stamp: Makefile $(SGMLS) $(PDFPICS) + xmlto man $(WARN) $(CUSTOM_HTML_XMLTO) -o man dvbapi.sgml + +distclean clean: + rm -f *.stamp + rm -f indices.sgml entities.sgml diff --git a/dvb-spec/sgml/README b/dvb-spec/sgml/README new file mode 100644 index 000000000..99dd5fef3 --- /dev/null +++ b/dvb-spec/sgml/README @@ -0,0 +1,13 @@ +This directory doesn't contain the official DVB API + +It contains an effort of porting it from LaTex to Docbook XML 4.1.2 + +It is still a work undergoing. Contributions are welcome. + +CURRENT STATUS: + +Chapters 1 and 2 were converted. The remaining chapters aren't yet. + +File dvbapi-complete.sgml is a temporary file generated by a tool that +automatically do the conversion. While it doesn't compile, it is a good +starting point for the conversion. diff --git a/dvb-spec/sgml/custom.dsl b/dvb-spec/sgml/custom.dsl new file mode 100644 index 000000000..12a5e91d4 --- /dev/null +++ b/dvb-spec/sgml/custom.dsl @@ -0,0 +1,52 @@ +<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ +<!ENTITY % html "IGNORE"> +<![%html;[ +<!ENTITY % print "IGNORE"> +<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl> +]]> +<!ENTITY % print "INCLUDE"> +<![%print;[ +<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl> +]]> +]> + +<style-sheet> + +<style-specification id="print" use="docbook"> +<style-specification-body> + +<!-- See docbook-dsssl-1.x/doc --> +(define %generate-reference-toc% #t) +(define %refentry-new-page% #t) +(define %number-programlisting-lines% #f) +(define %section-autolabel% #t) +(define bop-footnotes #t) +<!-- (define %show-comments% #f) --> +(define ($generate-book-lot-list$) + (list (normalize "figure") + (normalize "example"))) +<!-- A4 | USletter --> +(define %paper-type% "A4") + +</style-specification-body> +</style-specification> + +<style-specification id="html" use="docbook"> +<style-specification-body> + +<!-- See docbook-dsssl-1.x/doc --> +(define %generate-reference-toc% #t) +(define %number-programlisting-lines% #f) +(define %section-autolabel% #t) +(define bop-footnotes #t) +<!-- (define %show-comments% #f) --> +(define ($generate-book-lot-list$) + (list (normalize "figure") + (normalize "example"))) + +</style-specification-body> +</style-specification> + +<external-specification id="docbook" document="docbook.dsl"> + +</style-sheet> diff --git a/dvb-spec/sgml/custom.xsl b/dvb-spec/sgml/custom.xsl new file mode 100644 index 000000000..e1556c37c --- /dev/null +++ b/dvb-spec/sgml/custom.xsl @@ -0,0 +1,29 @@ +<?xml version="1.0" encoding="UTF-8"?> +<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> + +<!-- Extension for HTML files --> +<param name="html.ext" select="'.html'"/> + +<!-- Generate TOCs for book, article, part --> +<param name="generate.book.toc">1</param> +<param name="generate.article.toc">0</param> +<param name="generate.part.toc">0</param> +<param name="toc.chapter.depth">0</param> + +<param name="refentry.separator">1</param> + +<param name="chunk.first.sections">1</param> +<param name="chunk.id.as.filename">1</param> +<param name="chunk.separate.lots">1</param> + +<param name="funcsynopsis.style">ansi</param> +<param name="funcsynopsis.tabular.threshold">80</param> +<param name="funcsynopsis.decoration">1</param> + +<param name="chapter.autolabel">1</param> +<param name="section.autolabel">1</param> +<param name="section.label.includes.component.label">1</param> +<param name="toc.section.depth">3</param> + +<param name="paper.type">A4</param> +</stylesheet> diff --git a/dvb-spec/sgml/devices.sgml b/dvb-spec/sgml/devices.sgml new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/dvb-spec/sgml/devices.sgml diff --git a/dvb-spec/sgml/dvbapi-complete.sgml b/dvb-spec/sgml/dvbapi-complete.sgml new file mode 100644 index 000000000..56edcf023 --- /dev/null +++ b/dvb-spec/sgml/dvbapi-complete.sgml @@ -0,0 +1,9878 @@ +<!DOCTYPE article [<!ENTITY % docbook.dtd PUBLIC +"-//OASIS//DTD DocBook XML V4.2CR1//EN" +"http://www.oasis-open.org/docbook/xml/4.2CR1/docbookx.dtd"> +%docbook.dtd; +] > +<!--translated from dvbapi.tex, on 2009-09-06 01:50:00, +by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,refcaption --> + <?xtpipes file="docbook.4xt" ?> + <article role="book"> +<para role="maketitle"> +<note role="title"> +<para><emphasis role="bf">LINUX DVB API Version 3</emphasis></para></note> + <note role="author"> +<para><personname><othername> <graphic width="34.12749pt" fileref="cimlogo.psi" ></graphic> + Copyright 2002, 2003 Convergence GmbH + Written by Dr. Ralph J.K. Metzler + <emphasis role="tt"><rjkm@metzlerbros.de></emphasis> + and Dr. Marcus O.C. Metzler + <emphasis role="tt"><mocm@metzlerbros.de></emphasis> + </othername></personname></para></note> +<note role="date"> +<para>24/07/2003 +V 1.0.0</para></note> +</para> +<para>Permission is granted to copy, distribute and/or modify this document under the terms of +the GNU Free Documentation License, Version 1.1 or any later version published by the Free +Software Foundation. A copy of the license is included in the chapter entitled ”GNU Free +Documentation License”. +</para> + + + +<section +role="likechapter"><title>Contents</title> + <toc><tocpart> + </tocpart></toc> + + + +<section +role="chapter"><title>Introduction</title> + <section +role="section"><title><abbrev role="title-mark">1.1</abbrev>What you need to know</title> +<para>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. +</para> +<para>Various DVB standards documents are available from <emphasis role="tt">http://www.dvb.org/</emphasis> and/or +<emphasis role="tt">http://www.etsi.org/</emphasis>. +</para> +<para>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++. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">1.2</abbrev>History</title> +<para>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. +</para> +<para>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 +<emphasis role="tt">http://www.linuxtv.org/</emphasis> 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. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">1.3</abbrev>Overview</title> + <figure><title/><blockquote> +<section role="center"><title/> +<para><graphic width="306.14374pt" fileref="dvbstb.ps" ></graphic> +<blockquote role="caption"><title role="caption">Figure 1.1</title> +<para>Components of a DVB card/STB</para></blockquote> +</para></section> + </blockquote></figure> +<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the following main +hardware components: +</para> +<itemizedlist> + <listitem> +<para>Frontend consisting of tuner and DVB demodulator +</para> +<para>Here the raw signal reaches the DVB hardware from a satellite dish or antenna + or directly from cable. The frontend down-converts and demodulates this signal + into an MPEG transport stream (TS). In case of a satellite frontend, this includes + a facility for satellite equipment control (SEC), which allows control of LNB + polarization, multi feed switches or dish rotors. +</para> +</listitem> + <listitem> +<para>Conditional Access (CA) hardware like CI adapters and smartcard slots +</para> +<para>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. +</para> +</listitem> + <listitem> +<para>Demultiplexer which filters the incoming DVB stream +</para> +<para>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. +</para> +</listitem> + <listitem> +<para>MPEG2 audio and video decoder +</para> +<para>The main targets of the demultiplexer are the MPEG2 audio and video decoders. + After decoding they pass on the uncompressed audio and video to the computer + screen or (through a PAL/NTSC encoder) to a TV set.</para></listitem></itemizedlist> +<para>Figure ?? shows a crude schematic of the control and data flow between those +components. +</para> +<para>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. +</para> +</section><section +role="section"><title><abbrev role="title-mark">1.4</abbrev>Linux DVB Devices</title> +<para>The Linux DVB API lets you control these hardware components through currently six +Unix-style character devices for video, audio, frontend, demux, CA and IP-over-DVB +networking. The video and audio devices control the MPEG2 decoder hardware, the frontend +device the tuner and the DVB demodulator. The demux device gives you control over the PES +and section filters of the hardware. If the hardware does not support filtering these filters can +be implemented in software. Finally, the CA device controls all the conditional access +capabilities of the hardware. It can depend on the individual security requirements of the +platform, if and how many of the CA functions are made available to the application through +this device. +</para> +<para>All devices can be found in the <emphasis role="tt">/dev</emphasis> tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices are +called +</para> +<itemizedlist> + <listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>, +</para> +</listitem> + <listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>, +</para> +</listitem> + <listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>, +</para> +</listitem> + <listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>, +</para> +</listitem> + <listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>, +</para> +</listitem> + <listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> +<para>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 +“<emphasis role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion of these devices. The naming scheme +for the devices is the same wheter devfs is used or not. +</para> +<para>More details about the data structures and function calls of all the devices are described in +the following chapters. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">1.5</abbrev>API include files</title> +<para>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: +</para> +<programlisting> + #include <linux/dvb/frontend.h> +</programlisting> +<para>To enable applications to support different API version, an additional include file +<emphasis role="tt">linux/dvb/version.h</emphasis> exists, which defines the constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This +document describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>. +</para> + +</section></section><section +role="chapter"><title>DVB Frontend API</title> +<para>The DVB frontend device controls the tuner and DVB demodulator hardware. It can be +accessed through <emphasis role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and ioctl +definitions can be accessed by including <emphasis role="tt">linux/dvb/frontend.h</emphasis> in your +application. +</para> +<para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) and DVB-T +(terrestrial). Transmission via the internet (DVB-IP) is not yet handled by this API but a +future extension is possible. For DVB-S the frontend device also supports satellite equipment +control (SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification is +available from Eutelsat <emphasis role="tt">http://www.eutelsat.org/</emphasis>. +</para> +<para>Note that the DVB API may also be used for MPEG decoder-only PCI cards, in which +case there exists no frontend device. +</para> +<section +role="section"><title><abbrev role="title-mark">2.1</abbrev>Frontend Data Types</title> + +<section +role="subsection"><title><abbrev role="title-mark">2.1.1</abbrev>frontend type</title> +<para>For historical reasons frontend types are named after the type of modulation used in +transmission. +</para> +<programlisting> + typedef enum fe_type { + FE_QPSK, /⋆ DVB-S ⋆/ + FE_QAM, /⋆ DVB-C ⋆/ + FE_OFDM /⋆ DVB-T ⋆/ + } fe_type_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.2</abbrev>frontend capabilities</title> +<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for +a specific frontend type. +</para> +<programlisting> + typedef enum fe_caps { + FE_IS_STUPID = 0, + FE_CAN_INVERSION_AUTO = 0x1, + FE_CAN_FEC_1_2 = 0x2, + FE_CAN_FEC_2_3 = 0x4, + FE_CAN_FEC_3_4 = 0x8, + FE_CAN_FEC_4_5 = 0x10, + FE_CAN_FEC_5_6 = 0x20, + FE_CAN_FEC_6_7 = 0x40, + FE_CAN_FEC_7_8 = 0x80, + FE_CAN_FEC_8_9 = 0x100, + FE_CAN_FEC_AUTO = 0x200, + FE_CAN_QPSK = 0x400, + FE_CAN_QAM_16 = 0x800, + FE_CAN_QAM_32 = 0x1000, + FE_CAN_QAM_64 = 0x2000, + FE_CAN_QAM_128 = 0x4000, + FE_CAN_QAM_256 = 0x8000, + FE_CAN_QAM_AUTO = 0x10000, + FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, + FE_CAN_BANDWIDTH_AUTO = 0x40000, + FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, + FE_CAN_HIERARCHY_AUTO = 0x100000, + FE_CAN_MUTE_TS = 0x80000000, + FE_CAN_CLEAN_SETUP = 0x40000000 + } fe_caps_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.3</abbrev>frontend information</title> +<para>Information about the frontend ca be queried with FE_GET_INFO (??). +</para> +<programlisting> + struct dvb_frontend_info { + char name[128]; + fe_type_t type; + uint32_t frequency_min; + uint32_t frequency_max; + uint32_t frequency_stepsize; + uint32_t frequency_tolerance; + uint32_t symbol_rate_min; + uint32_t symbol_rate_max; + uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ + uint32_t notifier_delay; /⋆ ms ⋆/ + fe_caps_t caps; + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.4</abbrev>diseqc master command</title> +<para>A message sent from the frontend to DiSEqC capable equipment. +</para> +<programlisting> + struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.5</abbrev>diseqc slave reply</title> +<para>A reply to the frontend from DiSEqC 2.0 capable equipment. +</para> +<programlisting> + struct dvb_diseqc_slave_reply { + uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ + int timeout; /⋆ return from ioctl after timeout ms with ⋆/ + }; /⋆ errorcode when no message was received ⋆/ +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.6</abbrev>SEC voltage</title> +<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation +(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched +consistently to the DiSEqC commands as described in the DiSEqC spec. +</para> +<programlisting> + typedef enum fe_sec_voltage { + SEC_VOLTAGE_13, + SEC_VOLTAGE_18 + } fe_sec_voltage_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.7</abbrev>SEC continuous tone</title> +<para>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the +high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to +be switched consistently to the DiSEqC commands as described in the DiSEqC +spec. +</para> +<programlisting> + typedef enum fe_sec_tone_mode { + SEC_TONE_ON, + SEC_TONE_OFF + } fe_sec_tone_mode_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.8</abbrev>SEC tone burst</title> +<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select +between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to +be switched consistently to the DiSEqC commands as described in the DiSEqC +spec. +</para> +<programlisting> + typedef enum fe_sec_mini_cmd { + SEC_MINI_A, + SEC_MINI_B + } fe_sec_mini_cmd_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.9</abbrev>frontend status</title> +<para>Several functions of the frontend device use the fe_status data type defined +by +</para> +<programlisting> + typedef enum fe_status { + FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ + FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ + FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ + FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ + FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ + FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ + FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ + } fe_status_t; /⋆ application is recommned to reset ⋆/ +</programlisting> +<para>to indicate the current state and/or state changes of the frontend hardware. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.10</abbrev>frontend parameters</title> +<para>The kind of parameters passed to the frontend device for tuning depend on the kind of +hardware you are using. All kinds of parameters are combined as a union in the +FrontendParameters structure: +</para> +<programlisting> + struct dvb_frontend_parameters { + uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ + /⋆ intermediate frequency in kHz for QPSK ⋆/ + fe_spectral_inversion_t inversion; + union { + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; + } u; + }; +</programlisting> +<para>For satellite QPSK frontends you have to use the <remark role="obeylines-h">QPSKParameters</remark> member defined +by +</para> +<programlisting> + struct dvb_qpsk_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + }; +</programlisting> +<para>for cable QAM frontend you use the <remark role="obeylines-h">QAMParameters</remark> structure +</para> +<programlisting> + struct dvb_qam_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ + }; +</programlisting> +<para>DVB-T frontends are supported by the <remark role="obeylines-h">OFDMParamters</remark> structure +</para> +<programlisting> + struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ + fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ + fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; + }; +</programlisting> +<para>In the case of QPSK frontends the <remark role="obeylines-h">Frequency</remark> field specifies the intermediate +frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of +the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and +OFDM frontends the Frequency specifies the absolute frequency and is given in +Hz. +</para> +<para>The Inversion field can take one of these values: +</para> +<programlisting> + typedef enum fe_spectral_inversion { + INVERSION_OFF, + INVERSION_ON, + INVERSION_AUTO + } fe_spectral_inversion_t; +</programlisting> +<para>It indicates if spectral inversion should be presumed or not. In the automatic setting +(<remark role="obeylines-h">INVERSION_AUTO</remark>) the hardware will try to figure out the correct setting by +itself. +</para> +<para>The possible values for the <remark role="obeylines-h">FEC_inner</remark> field are +</para> +<programlisting> + typedef enum fe_code_rate { + FEC_NONE = 0, + FEC_1_2, + FEC_2_3, + FEC_3_4, + FEC_4_5, + FEC_5_6, + FEC_6_7, + FEC_7_8, + FEC_8_9, + FEC_AUTO + } fe_code_rate_t; +</programlisting> +<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto +detection. +</para> +<para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature +modulation mode which can be one of the following: +</para> +<programlisting> + typedef enum fe_modulation { + QPSK, + QAM_16, + QAM_32, + QAM_64, + QAM_128, + QAM_256, + QAM_AUTO + } fe_modulation_t; +</programlisting> +<para>Finally, there are several more parameters for OFDM: +</para> +<programlisting> + typedef enum fe_transmit_mode { + TRANSMISSION_MODE_2K, + TRANSMISSION_MODE_8K, + TRANSMISSION_MODE_AUTO + } fe_transmit_mode_t; +</programlisting> + <programlisting> + typedef enum fe_bandwidth { + BANDWIDTH_8_MHZ, + BANDWIDTH_7_MHZ, + BANDWIDTH_6_MHZ, + BANDWIDTH_AUTO + } fe_bandwidth_t; +</programlisting> + <programlisting> + typedef enum fe_guard_interval { + GUARD_INTERVAL_1_32, + GUARD_INTERVAL_1_16, + GUARD_INTERVAL_1_8, + GUARD_INTERVAL_1_4, + GUARD_INTERVAL_AUTO + } fe_guard_interval_t; +</programlisting> + <programlisting> + typedef enum fe_hierarchy { + HIERARCHY_NONE, + HIERARCHY_1, + HIERARCHY_2, + HIERARCHY_4, + HIERARCHY_AUTO + } fe_hierarchy_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.1.11</abbrev>frontend events</title> + <programlisting> + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; +</programlisting> + </section></section><section +role="section"><title><abbrev role="title-mark">2.2</abbrev>Frontend Function Calls</title> + +<section +role="subsection"><title><abbrev role="title-mark">2.2.1</abbrev>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) + for subsequent use. Usually the first thing to do after a successful open is to + find out the frontend type with FE_GET_INFO. +<para>The device can be opened in read-only mode, which only allows monitoring of + device status and statistics, or read/write mode, which allows any kind of use + (e.g. performing tuning operations.) +</para> +<para>In a system with multiple front-ends, it is usually the case that multiple devices + cannot be open in read/write mode simultaneously. As long as a front-end + device is opened in read/write mode, other open() calls in read/write mode will + either fail or block, depending on whether non-blocking or blocking mode was + specified. A front-end device opened in blocking mode can later be put into + non-blocking mode (and vice versa) using the F_SETFL command of the fcntl + system call. This is a standard system call, documented in the Linux manual + page for fcntl. When an open() call has succeeded, the device will be ready + for use in the specified mode. This implies that the corresponding hardware is + powered up, and that other front-ends may have been powered down to make + that possible.</para> +</entry> + </row></tbody></tgroup></informaltable> +</para> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific video device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.2</abbrev>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened front-end device. After closing + a front-end device, its corresponding hardware might be powered down + automatically.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.3</abbrev>FE_READ_STATUS<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns status information about the front-end. This call only + requires read-only access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_READ_STATUS, + fe_status_t ⋆status);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_STATUS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct fe_status_t + *status</para> +</entry><entry + align="char"> +<para>Points to the location where the front-end status word is + to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.4</abbrev>FE_READ_BER<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the bit error rate for the signal currently + received/demodulated by the front-end. For this command, read-only access to + the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_READ_BER, + uint32_t ⋆ber);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_BER for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>uint32_t *ber</para> +</entry><entry + align="char"> +<para>The bit error rate is stored into *ber.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ber points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSIGNAL</para> +</entry><entry + align="char"> +<para>There is no signal, thus no meaningful bit error rate. Also + returned if the front-end is not turned on.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.5</abbrev>FE_READ_SNR<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the signal-to-noise ratio for the signal currently received + by the front-end. For this command, read-only access to the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_READ_SNR, int16_t + ⋆snr);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_SNR for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int16_t *snr</para> +</entry><entry + align="char"> +<para>The signal-to-noise ratio is stored into *snr.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>snr points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSIGNAL</para> +</entry><entry + align="char"> +<para>There is no signal, thus no meaningful signal strength + value. Also returned if front-end is not turned on.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.6</abbrev>FE_READ_SIGNAL_STRENGTH<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the signal strength value for the signal currently received + by the front-end. For this command, read-only access to the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = + FE_READ_SIGNAL_STRENGTH, int16_t ⋆strength);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_SIGNAL_STRENGTH for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>int16_t *strength</para> +</entry><entry + align="char"> +<para>The signal strength value is stored into *strength.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSIGNAL</para> +</entry><entry + align="char"> +<para>There is no signal, thus no meaningful signal strength + value. Also returned if front-end is not turned on.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.7</abbrev>FE_READ_UNCORRECTED_BLOCKS<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the number of uncorrected blocks detected by the device + driver during its lifetime. For meaningful measurements, the increment in block + count during a specific time interval should be calculated. For this command, + read-only access to the device is sufficient.</para> +</entry> + </row><row><entry + align="char"> +<para>Note that the counter will wrap to zero after its maximum count has been + reached.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = + FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_UNCORRECTED_BLOCKS for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>uint32_t *ublocks</para> +</entry><entry + align="char"> +<para>The total number of uncorrected blocks seen by the driver + so far.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ublocks points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.8</abbrev>FE_SET_FRONTEND<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call starts a tuning operation using specified parameters. The result + of this call will be successful if the parameters were valid and the tuning could + be initiated. The result of the tuning operation in itself, however, will arrive + asynchronously as an event (see documentation for FE_GET_EVENT and + FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before + the previous one was completed, the previous operation will be aborted in favor + of the new one. This command requires read/write access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_SET_FRONTEND, + struct dvb_frontend_parameters ⋆p);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_FRONTEND for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_parameters + *p</para> +</entry><entry + align="char"> +<para>Points to parameters for tuning operation.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>p points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Maximum supported symbol rate reached.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.9</abbrev>FE_GET_FRONTEND<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call queries the currently effective frontend parameters. For this + command, read-only access to the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_GET_FRONTEND, + struct dvb_frontend_parameters ⋆p);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_FRONTEND for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_parameters + *p</para> +</entry><entry + align="char"> +<para>Points to parameters for tuning operation.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>p points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Maximum supported symbol rate reached.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.10</abbrev>FE_GET_EVENT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns a frontend event if available. If an event is not + available, the behavior depends on whether the device is in blocking or + non-blocking mode. In the latter case, the call fails immediately with errno + set to EWOULDBLOCK. In the former case, the call blocks until an event + becomes available.</para> +</entry> + </row><row><entry + align="char"> +<para>The standard Linux poll() and/or select() system calls can be used with the + device file descriptor to watch for new events. For select(), the file descriptor + should be included in the exceptfds argument, and for poll(), POLLPRI should + be specified as the wake-up condition. Since the event queue allocated is + rather small (room for 8 events), the queue must be serviced regularly to avoid + overflow. If an overflow happens, the oldest event is discarded from the queue, + and an error (EOVERFLOW) occurs the next time the queue is read. After + reporting the error condition in this fashion, subsequent FE_GET_EVENT + calls will return events from the queue as usual.</para> +</entry> + </row><row><entry + align="char"> +<para>For the sake of implementation simplicity, this command requires read/write + access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = QPSK_GET_EVENT, + struct dvb_frontend_event ⋆ev);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_GET_EVENT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_event + *ev</para> +</entry><entry + align="char"> +<para>Points to the location where the event,</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>if any, is to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ev points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>There is no event pending, and the device is in + non-blocking mode.</para> +</entry> + </row><row><entry + align="char"> +<para>EOVERFLOW</para> +</entry><entry + align="char"> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>Overflow in event queue - one or more events were lost.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.11</abbrev>FE_GET_INFO<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns information about the front-end. This call only requires + read-only access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(int fd, int request = FE_GET_INFO, struct + dvb_frontend_info ⋆info);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_GET_INFO for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_info + *info</para> +</entry><entry + align="char"> +<para>Points to the location where the front-end information is + to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>info points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.12</abbrev>FE_DISEQC_RESET_OVERLOAD<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>If the bus has been automatically powered off due to power overload, this ioctl + call restores the power to the bus. The call requires read/write access to the + device. This call has no effect if the device is manually powered off. Not all + DVB adapters support this ioctl.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_RESET_OVERLOAD);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_RESET_OVERLOAD for this + command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.13</abbrev>FE_DISEQC_SEND_MASTER_CMD<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to send a a DiSEqC command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_SEND_MASTER_CMD, struct + dvb_diseqc_master_cmd ⋆cmd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_SEND_MASTER_CMD for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_diseqc_master_cmd + *cmd</para> +</entry><entry + align="char"> +<para>Pointer to the command to be transmitted.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>Seq points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>The data structure referred to by seq is invalid in some + way.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.14</abbrev>FE_DISEQC_RECV_SLAVE_REPLY<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_RECV_SLAVE_REPLY, struct + dvb_diseqc_slave_reply ⋆reply);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_RECV_SLAVE_REPLY for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_diseqc_slave_reply + *reply</para> +</entry><entry + align="char"> +<para>Pointer to the command to be received.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>Seq points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>The data structure referred to by seq is invalid in some + way.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.15</abbrev>FE_DISEQC_SEND_BURST<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to send a 22KHz tone burst.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_SEND_BURST, fe_sec_mini_cmd_t burst);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_SEND_BURST for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>fe_sec_mini_cmd_t + burst</para> +</entry><entry + align="char"> +<para>burst A or B.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>Seq points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>The data structure referred to by seq is invalid in some + way.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.16</abbrev>FE_SET_TONE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This call is used to set the generation of the continuous 22kHz tone. This call + requires read/write permissions.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_SET_TONE, + fe_sec_tone_mode_t tone);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_TONE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>fe_sec_tone_mode_t + tone</para> +</entry><entry + align="char"> +<para>The requested tone generation mode (on/off).</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>File not opened with read permissions.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.17</abbrev>FE_SET_VOLTAGE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This call is used to set the bus voltage. This call requires read/write + permissions.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_SET_VOLTAGE, + fe_sec_voltage_t voltage);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_VOLTAGE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>fe_sec_voltage_t + voltage</para> +</entry><entry + align="char"> +<para>The requested bus voltage.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>File not opened with read permissions.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">2.2.18</abbrev>FE_ENABLE_HIGH_LNB_VOLTAGE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate + for long cables). This call requires read/write permissions. Not all DVB + adapters support this ioctl.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_ENABLE_HIGH_LNB_VOLTAGE, int high);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_VOLTAGE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int high</para> +</entry><entry + align="char"> +<para>The requested bus voltage.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>File not opened with read permissions.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section></section></section><section +role="chapter"><title>DVB Demux Device</title> +<para>The DVB demux device controls the filters of the DVB hardware/software. It can be +accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be +accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application. +</para> +<section +role="section"><title><abbrev role="title-mark">3.1</abbrev>Demux Data Types</title> + +<section +role="subsection"><title><abbrev role="title-mark">3.1.1</abbrev>dmx_output_t</title> + <programlisting> + typedef enum + { + DMX_OUT_DECODER, + DMX_OUT_TAP, + DMX_OUT_TS_TAP + } dmx_output_t; +</programlisting> +<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is +called. +</para> +<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>, +which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was +specified. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.2</abbrev>dmx_input_t</title> + <programlisting> + typedef enum + { + DMX_IN_FRONTEND, + DMX_IN_DVR + } dmx_input_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.3</abbrev>dmx_pes_type_t</title> + <programlisting> + typedef enum + { + DMX_PES_AUDIO, + DMX_PES_VIDEO, + DMX_PES_TELETEXT, + DMX_PES_SUBTITLE, + DMX_PES_PCR, + DMX_PES_OTHER + } dmx_pes_type_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.4</abbrev>dmx_event_t</title> + <programlisting> + typedef enum + { + DMX_SCRAMBLING_EV, + DMX_FRONTEND_EV + } dmx_event_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.5</abbrev>dmx_scrambling_status_t</title> + <programlisting> + typedef enum + { + DMX_SCRAMBLING_OFF, + DMX_SCRAMBLING_ON + } dmx_scrambling_status_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.6</abbrev>struct dmx_filter</title> + <programlisting> + typedef struct dmx_filter + { + uint8_t filter[DMX_FILTER_SIZE]; + uint8_t mask[DMX_FILTER_SIZE]; + } dmx_filter_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.7</abbrev>struct dmx_sct_filter_params</title> + <programlisting> + struct dmx_sct_filter_params + { + uint16_t pid; + dmx_filter_t filter; + uint32_t timeout; + uint32_t flags; + #define DMX_CHECK_CRC 1 + #define DMX_ONESHOT 2 + #define DMX_IMMEDIATE_START 4 + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.8</abbrev>struct dmx_pes_filter_params</title> + <programlisting> + struct dmx_pes_filter_params + { + uint16_t pid; + dmx_input_t input; + dmx_output_t output; + dmx_pes_type_t pes_type; + uint32_t flags; + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.9</abbrev>struct dmx_event</title> + <programlisting> + struct dmx_event + { + dmx_event_t event; + time_t timeStamp; + union + { + dmx_scrambling_status_t scrambling; + } u; + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.1.10</abbrev>struct dmx_stc</title> + <programlisting> + struct dmx_stc { + unsigned int num; /⋆ input : which STC? 0..N ⋆/ + unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/ + uint64_t stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/ + }; +</programlisting> + </section></section><section +role="section"><title><abbrev role="title-mark">3.2</abbrev>Demux Function Calls</title> + +<section +role="subsection"><title><abbrev role="title-mark">3.2.1</abbrev>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call, used with a device name of /dev/dvb/adapter0/demux0, + allocates a new filter and returns a handle which can be used for subsequent + control of that filter. This call has to be made for each filter to be used, i.e. every + returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0 + is a logical device to be used for retrieving Transport Streams for digital + video recording. When reading from this device a transport stream containing + the packets from all PES filters set in the corresponding demux device + (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A + recorded Transport Stream is replayed by writing to this device. +<para>The significance of blocking or non-blocking mode is described in the + documentation for functions where there is a difference. It does not affect the + semantics of the open() call itself. A device opened in blocking mode can later + be put into non-blocking mode (and vice versa) using the F_SETFL command + of the fcntl system call.</para> +</entry> + </row></tbody></tgroup></informaltable> +</para> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of demux device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EMFILE</para> +</entry><entry + align="char"> +<para>“Too many open files”, i.e. no more filters available.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>The driver failed to allocate enough memory.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.2</abbrev>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call deactivates and deallocates a filter that was previously + allocated via the open() call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.3</abbrev>read()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call returns filtered data, which might be section or PES data. The + filtered data is transferred from the driver’s internal circular buffer to buf. The + maximum amount of data to be transferred is implied by count.</para> +</entry> + </row><row><entry + align="char"> +<para>When returning section data the driver always tries to return a complete single + section (even though buf would provide buffer space for more data). If the size + of the buffer is smaller than the section as much as possible will be returned, + and the remaining data will be provided in subsequent calls.</para> +</entry> + </row><row><entry + align="char"> +<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum + sized sections) by default. The size of this buffer may be changed by using the + DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if + the read operations are not performed fast enough, this may result in a buffer + overflow error. In this case EOVERFLOW will be returned, and the circular + buffer will be emptied. This call is blocking if there is no data to return, i.e. the + process will be put to sleep waiting for data, unless the O_NONBLOCK flag + is specified.</para> +</entry> + </row><row><entry + align="char"> +<para>Note that in order to be able to read, the filtering process has to be started + by defining either a section or a PES filter by means of the ioctl functions, + and then starting the filtering process via the DMX_START ioctl function + or by setting the DMX_IMMEDIATE_START flag. If the reading is done + from a logical DVR demux device, the data will constitute a Transport Stream + including the packets from all PES filters in the corresponding demux device + /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>size_t read(int fd, void ⋆buf, size_t count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer to be used for returned filtered data.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>No data to return and O_NONBLOCK was specified.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>ECRC</para> +</entry><entry + align="char"> +<para>Last section had a CRC error - no data returned. The + buffer is flushed.</para> +</entry> + </row><row><entry + align="char"> +<para>EOVERFLOW</para> +</entry><entry + align="char"> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>The filtered data was not read from the buffer in due + time, resulting in non-read data being lost. The buffer is + flushed.</para> +</entry> + </row><row><entry + align="char"> +<para>ETIMEDOUT</para> +</entry><entry + align="char"> +<para>The section was not loaded within the stated timeout + period. See ioctl DMX_SET_FILTER for how to set a + timeout.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>The driver failed to write to the callers buffer due to an + invalid *buf pointer.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.4</abbrev>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, + associated with the physical demux device that provides the actual DVR + functionality. It is used for replay of a digitally recorded Transport Stream. + Matching filters have to be defined in the corresponding physical demux + device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is + implied by count.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>ssize_t write(int fd, const void ⋆buf, size_t + count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer containing the Transport Stream.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>No data was written. This + might happen if O_NONBLOCK was specified and there + is no more buffer space available (if O_NONBLOCK is + not specified the function will block until buffer space is + available).</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>This error code indicates that there are conflicting + requests. The corresponding demux device is setup to + receive data from the front- end. Make sure that these + filters are stopped and that the filters with input set to + DMX_IN_DVR are started.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.5</abbrev>DMX_START<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to start the actual filtering operation defined via the ioctl + calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_START);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_START for this command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument, i.e. no filtering parameters provided via + the DMX_SET_FILTER or DMX_SET_PES_FILTER + functions.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>This error code indicates that there are conflicting + requests. There are active filters filtering data from + another input source. Make sure that these filters are + stopped before starting this filter.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.6</abbrev>DMX_STOP<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to stop the actual filtering operation defined via the + ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via + the DMX_START command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_STOP);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_STOP for this command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.7</abbrev>DMX_SET_FILTER<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call sets up a filter according to the filter and mask parameters + provided. A timeout may be defined stating number of seconds to wait for a + section to be loaded. A value of 0 means that no timeout should be applied. + Finally there is a flag field where it is possible to state whether a section should + be CRC-checked, whether the filter should be a ”one-shot” filter, i.e. if the + filtering operation should be stopped after the first section is received, and + whether the filtering operation should be started immediately (without waiting + for a DMX_START ioctl call). If a filter was previously set-up, this filter will + be canceled, and the receive buffer will be flushed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_SET_FILTER, + struct dmx_sct_filter_params ⋆params);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_FILTER for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dmx_sct_filter_params + *params</para> +</entry><entry + align="char"> +<para>Pointer to structure containing filter parameters.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.8</abbrev>DMX_SET_PES_FILTER<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call sets up a PES filter according to the parameters provided. By a + PES filter is meant a filter that is based just on the packet identifier (PID), i.e. + no PES header or payload filtering capability is supported.</para> +</entry> + </row><row><entry + align="char"> +<para>The transport stream destination for the filtered output may be set. Also the + PES type may be stated in order to be able to e.g. direct a video stream directly + to the video decoder. Finally there is a flag field where it is possible to state + whether the filtering operation should be started immediately (without waiting + for a DMX_START ioctl call). If a filter was previously set-up, this filter will + be cancelled, and the receive buffer will be flushed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER, + struct dmx_pes_filter_params ⋆params);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_PES_FILTER for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dmx_pes_filter_params + *params</para> +</entry><entry + align="char"> +<para>Pointer to structure containing filter parameters.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>This error code indicates that there are conflicting + requests. There are active filters filtering data from + another input source. Make sure that these filters are + stopped before starting this filter.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.9</abbrev>DMX_SET_BUFFER_SIZE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to set the size of the circular buffer used for filtered data. + The default size is two maximum sized sections, i.e. if this function is not called + a buffer size of 2 * 4096 bytes will be used.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = + DMX_SET_BUFFER_SIZE, unsigned long size);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_BUFFER_SIZE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned long size</para> +</entry><entry + align="char"> +<para>Size of circular buffer.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>The driver was not able to allocate a buffer of the + requested size.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.10</abbrev>DMX_GET_EVENT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns an event if available. If an event is not available, + the behavior depends on whether the device is in blocking or non-blocking + mode. In the latter case, the call fails immediately with errno set to + EWOULDBLOCK. In the former case, the call blocks until an event becomes + available.</para> +</entry> + </row><row><entry + align="char"> +<para>The standard Linux poll() and/or select() system calls can be used with the + device file descriptor to watch for new events. For select(), the file descriptor + should be included in the exceptfds argument, and for poll(), POLLPRI should + be specified as the wake-up condition. Only the latest event for each filter is + saved.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_GET_EVENT, + struct dmx_event ⋆ev);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_GET_EVENT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct dmx_event *ev</para> +</entry><entry + align="char"> +<para>Pointer to the location where the event is to be stored.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ev points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>There is no event pending, and the device is in + non-blocking mode.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">3.2.11</abbrev>DMX_GET_STC<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the current value of the system time counter (which is driven + by a PES filter of type DMX_PES_PCR). Some hardware supports more than one + STC, so you must specify which one by setting the num field of stc before the ioctl + (range 0...n). The result is returned in form of a ratio with a 64 bit numerator + and a 32 bit denominator, so the real 90kHz STC value is stc->stc / + stc->base + .</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_GET_STC, struct + dmx_stc ⋆stc);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_GET_STC for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct dmx_stc *stc</para> +</entry><entry + align="char"> +<para>Pointer to the location where the stc is to be stored.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>stc points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid stc number.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + </section></section></section><section +role="chapter"><title>DVB Video Device</title> +<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It +can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and +ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your +application. +</para> +<para>Note that the DVB video device only controls decoding of the MPEG video stream, not +its presentation on the TV or computer screen. On PCs this is typically handled by an +associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output +windows. +</para> +<para>Some DVB cards don’t have their own MPEG decoder, which results in the omission of +the audio and video device as well as the video4linux device. +</para> +<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only +supported on some MPEG decoders made for DVD playback. +</para> +<section +role="section"><title><abbrev role="title-mark">4.1</abbrev>Video Data Types</title> + +<section +role="subsection"><title><abbrev role="title-mark">4.1.1</abbrev>video_format_t</title> +<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by +</para> +<programlisting> + typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9 + } video_format_t; +</programlisting> +<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio +the output hardware (e.g. TV) has. It is also used in the data structures video_status +(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by +VIDEO_GET_EVENT (??) which report about the display format of the current video +stream. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.2</abbrev>video_display_format_t</title> +<para>In case the display format of the video stream and of the display hardware differ the +application has to specify how to handle the cropping of the picture. This can be done using +the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts +</para> +<programlisting> + typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT + } video_display_format_t; +</programlisting> +<para>as argument. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.3</abbrev>video stream source</title> +<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take +the following values, depending on whether we are replaying from an internal (demuxer) or +external (user write) source. +</para> +<programlisting> + typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY + } video_stream_source_t; +</programlisting> +<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the +DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY +is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system +call. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.4</abbrev>video play state</title> +<para>The following values can be returned by the VIDEO_GET_STATUS call representing the +state of video playback. +</para> +<programlisting> + typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED + } video_play_state_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.5</abbrev>struct video_event</title> +<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT +call. +</para> +<programlisting> + struct video_event { + int32_t type; + time_t timestamp; + union { + video_format_t video_format; + } u; + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.6</abbrev>struct video_status</title> +<para>The VIDEO_GET_STATUS call returns the following structure informing about various +states of the playback operation. +</para> +<programlisting> + struct video_status { + boolean video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; + }; +</programlisting> +<para>If video_blank is set video will be blanked out if the channel is changed or if playback is +stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is +currently frozen, stopped, or being played back. The stream_source corresponds to the seleted +source for the video stream. It can come either from the demultiplexer or from memory. +The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently +played video stream. Finally, display_format corresponds to the selected cropping +mode in case the source video format is not the same as the format of the output +device. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.7</abbrev>struct video_still_picture</title> +<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the +following structure. +</para> +<programlisting> + /⋆ pointer to and size of a single iframe in memory ⋆/ + struct video_still_picture { + char ⋆iFrame; + int32_t size; + }; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.8</abbrev>video capabilities</title> +<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following +bits set according to the hardwares capabilities. +</para> +<programlisting> + /⋆ bit definitions for capabilities: ⋆/ + /⋆ can the hardware decode MPEG1 and/or MPEG2? ⋆/ + #define VIDEO_CAP_MPEG1 1 + #define VIDEO_CAP_MPEG2 2 + /⋆ can you send a system and/or program stream to video device? + (you still have to open the video and the audio device but only + send the stream to the video device) ⋆/ + #define VIDEO_CAP_SYS 4 + #define VIDEO_CAP_PROG 8 + /⋆ can the driver also handle SPU, NAVI and CSS encoded data? + (CSS API is not present yet) ⋆/ + #define VIDEO_CAP_SPU 16 + #define VIDEO_CAP_NAVI 32 + #define VIDEO_CAP_CSS 64 +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.9</abbrev>video system</title> +<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The +following system types can be set: +</para> +<programlisting> + typedef enum { + VIDEO_SYSTEM_PAL, + VIDEO_SYSTEM_NTSC, + VIDEO_SYSTEM_PALN, + VIDEO_SYSTEM_PALNc, + VIDEO_SYSTEM_PALM, + VIDEO_SYSTEM_NTSC60, + VIDEO_SYSTEM_PAL60, + VIDEO_SYSTEM_PALM60 + } video_system_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.10</abbrev>struct video_highlight</title> +<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The +call expects the following format for that information: +</para> +<programlisting> + typedef + struct video_highlight { + boolean active; /⋆ 1=show highlight, 0=hide highlight ⋆/ + uint8_t contrast1; /⋆ 7- 4 Pattern pixel contrast ⋆/ + /⋆ 3- 0 Background pixel contrast ⋆/ + uint8_t contrast2; /⋆ 7- 4 Emphasis pixel-2 contrast ⋆/ + /⋆ 3- 0 Emphasis pixel-1 contrast ⋆/ + uint8_t color1; /⋆ 7- 4 Pattern pixel color ⋆/ + /⋆ 3- 0 Background pixel color ⋆/ + uint8_t color2; /⋆ 7- 4 Emphasis pixel-2 color ⋆/ + /⋆ 3- 0 Emphasis pixel-1 color ⋆/ + uint32_t ypos; /⋆ 23-22 auto action mode ⋆/ + /⋆ 21-12 start y ⋆/ + /⋆ 9- 0 end y ⋆/ + uint32_t xpos; /⋆ 23-22 button color number ⋆/ + /⋆ 21-12 start x ⋆/ + /⋆ 9- 0 end x ⋆/ + } video_highlight_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.11</abbrev>video SPU</title> +<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the +following format: +</para> +<programlisting> + typedef + struct video_spu { + boolean active; + int stream_id; + } video_spu_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.12</abbrev>video SPU palette</title> +<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: +</para> +<programlisting> + typedef + struct video_spu_palette{ + int length; + uint8_t ⋆palette; + } video_spu_palette_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.13</abbrev>video NAVI pack</title> +<para>In order to get the navigational data the following structure has to be passed to the ioctl +VIDEO_GET_NAVI: +</para> +<programlisting> + typedef + struct video_navi_pack{ + int length; /⋆ 0 ... 1024 ⋆/ + uint8_t data[1024]; + } video_navi_pack_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.1.14</abbrev>video attributes</title> +<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: +</para> +<programlisting> + typedef uint16_t video_attributes_t; + /⋆ bits: descr. ⋆/ + /⋆ 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) ⋆/ + /⋆ 13-12 TV system (0=525/60, 1=625/50) ⋆/ + /⋆ 11-10 Aspect ratio (0=4:3, 3=16:9) ⋆/ + /⋆ 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca ⋆/ + /⋆ 7 line 21-1 data present in GOP (1=yes, 0=no) ⋆/ + /⋆ 6 line 21-2 data present in GOP (1=yes, 0=no) ⋆/ + /⋆ 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 ⋆/ + /⋆ 2 source letterboxed (1=yes, 0=no) ⋆/ + /⋆ 0 film/camera mode (0=camera, 1=film (625/50 only)) ⋆/ +</programlisting> + </section></section><section +role="section"><title><abbrev role="title-mark">4.2</abbrev>Video Function Calls</title> + +<section +role="subsection"><title><abbrev role="title-mark">4.2.1</abbrev>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) + for subsequent use. +<para>When an open() call has succeeded, the device will be ready for use. + The significance of blocking or non-blocking mode is described in the + documentation for functions where there is a difference. It does not affect the + semantics of the open() call itself. A device opened in blocking mode can later + be put into non-blocking mode (and vice versa) using the F_SETFL command + of the fcntl system call. This is a standard system call, documented in the Linux + manual page for fcntl. Only one user can open the Video Device in O_RDWR + mode. All other attempts to open the device in this mode will fail, and an + error-code will be returned. If the Video Device is opened in O_RDONLY + mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other + call will return an error code.</para> +</entry> + </row></tbody></tgroup></informaltable> +</para> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific video device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.2</abbrev>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened video device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.3</abbrev>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected + in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in + PES format, unless the capability allows other formats. If O_NONBLOCK is + not specified the function will block until buffer space is available. The amount + of data to be transferred is implied by count.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>size_t write(int fd, const void ⋆buf, size_t count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer containing the PES data.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>Attempted to write more data than the internal buffer can + hold.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.4</abbrev>VIDEO_STOP<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to stop playing the current stream. + Depending on the input parameter, the screen can be blanked out or displaying + the last decoded frame.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_STOP, boolean + mode);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_STOP for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>Boolean mode</para> +</entry><entry + align="char"> +<para>Indicates how the screen shall be handled.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE: Blank screen when stop.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE: Show last decoded frame.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.5</abbrev>VIDEO_PLAY<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to start playing a video stream from the + selected source.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_PLAY);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_PLAY for this command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.6</abbrev>VIDEO_FREEZE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call suspends the live video stream being played. Decoding + and playing are frozen. It is then possible to restart the decoding + and playing process of the video stream using the VIDEO_CONTINUE + command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call + VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more + data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_FREEZE);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_FREEZE for this command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.7</abbrev>VIDEO_CONTINUE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call restarts decoding and playing processes of the video stream + which was played before a call to VIDEO_FREEZE was made.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_CONTINUE for this command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.8</abbrev>VIDEO_SELECT_SOURCE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call informs the video device which source shall be used for the input + data. The possible sources are demux or memory. If memory is selected, the + data is fed to the video device through the write command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE, + video_stream_source_t source);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SELECT_SOURCE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_stream_source_t + source</para> +</entry><entry + align="char"> +<para>Indicates which source shall be used for the Video stream.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.9</abbrev>VIDEO_SET_BLANK<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to blank out the picture.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean + mode);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_BLANK for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean mode</para> +</entry><entry + align="char"> +<para>TRUE: Blank screen when stop.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE: Show last decoded frame.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.10</abbrev>VIDEO_GET_STATUS<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to return the current status of the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct + video_status ⋆status);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_STATUS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct video_status + *status</para> +</entry><entry + align="char"> +<para>Returns the current status of the Video Device.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.11</abbrev>VIDEO_GET_EVENT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns an event of type video_event if available. If an event is + not available, the behavior depends on whether the device is in blocking or + non-blocking mode. In the latter case, the call fails immediately with errno + set to EWOULDBLOCK. In the former case, the call blocks until an event + becomes available. The standard Linux poll() and/or select() system calls can + be used with the device file descriptor to watch for new events. For select(), + the file descriptor should be included in the exceptfds argument, and for + poll(), POLLPRI should be specified as the wake-up condition. Read-only + permissions are sufficient for this ioctl call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct + video_event ⋆ev);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_EVENT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct video_event + *ev</para> +</entry><entry + align="char"> +<para>Points to the location where the event, if any, is to be + stored.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ev points to invalid address</para> +</entry> + </row><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>There is no event pending, and the device is in + non-blocking mode.</para> +</entry> + </row><row><entry + align="char"> +<para>EOVERFLOW</para> +</entry><entry + align="char"> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>Overflow in event queue - one or more events were lost.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.12</abbrev>VIDEO_SET_DISPLAY_FORMAT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to select the video format to be applied + by the MPEG chip on the video.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = + VIDEO_SET_DISPLAY_FORMAT, video_display_format_t + format);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_DISPLAY_FORMAT for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_display_format_t + format</para> +</entry><entry + align="char"> +<para>Selects the video format to be used.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal parameter format.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.13</abbrev>VIDEO_STILLPICTURE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to display a still picture (I-frame). The + input data shall contain an I-frame. If the pointer is NULL, then the current + displayed still picture is blanked.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_STILLPICTURE, + struct video_still_picture ⋆sp);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_STILLPICTURE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + video_still_picture + *sp</para> +</entry><entry + align="char"> +<para>Pointer to a location where an I-frame and size is stored.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>sp points to an invalid iframe.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.14</abbrev>VIDEO_FAST_FORWARD<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to skip decoding of N number of I-frames. + This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int + nFrames);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_FAST_FORWARD for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int nFrames</para> +</entry><entry + align="char"> +<para>The number of frames to skip.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal parameter format.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.15</abbrev>VIDEO_SLOWMOTION<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the video device to repeat decoding frames N number of + times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int + nFrames);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SLOWMOTION for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int nFrames</para> +</entry><entry + align="char"> +<para>The number of times to repeat each frame.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal parameter format.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.16</abbrev>VIDEO_GET_CAPABILITIES<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the video device about its decoding capabilities. On success + it returns and integer which has bits set according to the defines in section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, + unsigned int ⋆cap);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_CAPABILITIES for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned int *cap</para> +</entry><entry + align="char"> +<para>Pointer to a location where to store the capability + information.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>cap points to an invalid iframe.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.17</abbrev>VIDEO_SET_ID<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl selects which sub-stream is to be decoded if a program or system + stream is sent to the video device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = VIDEO_SET_ID, int + id);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int id</para> +</entry><entry + align="char"> +<para>video sub-stream id</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid sub-stream id.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.18</abbrev>VIDEO_CLEAR_BUFFER<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_CLEAR_BUFFER for this command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.19</abbrev>VIDEO_SET_STREAMTYPE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl tells the driver which kind of stream to expect being written to it. If + this call is not used the default of video PES is used. Some drivers might not + support this call and always expect PES.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, + int type);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_STREAMTYPE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int type</para> +</entry><entry + align="char"> +<para>stream type</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>type is not a valid or supported stream type.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.20</abbrev>VIDEO_SET_FORMAT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the screen format (aspect ratio) of the connected output device + (TV) so that the output of the decoder can be adjusted accordingly.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_FORMAT, + video_format_t format);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_FORMAT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_format_t + format</para> +</entry><entry + align="char"> +<para>video format of TV as defined in section ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>format is not a valid video format.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.21</abbrev>VIDEO_SET_SYSTEM<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the television output format. The format (see section ??) may + vary from the color format of the displayed MPEG stream. If the hardware is + not able to display the requested format the call will return an error.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM , + video_system_t system);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_FORMAT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_system_t + system</para> +</entry><entry + align="char"> +<para>video system of TV output.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>system is not a valid or supported video system.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.22</abbrev>VIDEO_SET_HIGHLIGHT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT + ,video_highlight_t ⋆vhilite)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_highlight_t + *vhilite</para> +</entry><entry + align="char"> +<para>SPU Highlight information according to section ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid highlight setting.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.23</abbrev>VIDEO_SET_SPU<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can + only be used, if the driver is able to handle a DVD stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_SPU , + video_spu_t ⋆spu)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_SPU for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_spu_t *spu</para> +</entry><entry + align="char"> +<para>SPU decoding (de)activation and subid setting according + to section ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid spu setting or driver cannot handle + SPU.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.24</abbrev>VIDEO_SET_SPU_PALETTE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the SPU color palette.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE + ,video_spu_palette_t ⋆palette )</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_spu_palette_t + *palette</para> +</entry><entry + align="char"> +<para>SPU palette according to section ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid palette or driver doesn’t handle SPU.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.25</abbrev>VIDEO_GET_NAVI<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl returns navigational information from the DVD stream. This is + especially needed if an encoded stream has to be decoded by the hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_GET_NAVI , + video_navi_pack_t ⋆navipack)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_NAVI for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_navi_pack_t + *navipack</para> +</entry><entry + align="char"> +<para>PCI or DSI pack (private stream 2) according to section + ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>driver is not able to return navigational information</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">4.2.26</abbrev>VIDEO_SET_ATTRIBUTES<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is intended for DVD playback and allows you to set certain + information about the stream. Some hardware may not need this information, + but the call also tells the hardware to prepare for DVD playback.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE + ,video_attributes_t vattr)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_attributes_t + vattr</para> +</entry><entry + align="char"> +<para>video attributes according to section ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid attribute setting.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + </section></section></section><section +role="chapter"><title>DVB Audio Device</title> +<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It +can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and +ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your +application. +</para> +<para>Please note that some DVB cards don’t have their own MPEG decoder, which results in +the omission of the audio and video device. +</para> +<section +role="section"><title><abbrev role="title-mark">5.1</abbrev>Audio Data Types</title> +<para>This section describes the structures, data types and defines used when talking to the +audio device. +</para> + +<section +role="subsection"><title><abbrev role="title-mark">5.1.1</abbrev>audio_stream_source_t</title> +<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take +the following values, depending on whether we are replaying from an internal (demux) or +external (user write) source. +</para> +<programlisting> + typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY + } audio_stream_source_t; +</programlisting> +<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the +DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY +is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system +call. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.2</abbrev>audio_play_state_t</title> +<para>The following values can be returned by the AUDIO_GET_STATUS call representing the +state of audio playback. +</para> +<programlisting> + typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED + } audio_play_state_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.3</abbrev>audio_channel_select_t</title> +<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the +following values. +</para> +<programlisting> + typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, + } audio_channel_select_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.4</abbrev>struct audio_status</title> +<para>The AUDIO_GET_STATUS call returns the following structure informing about various +states of the playback operation. +</para> +<programlisting> + typedef struct audio_status { + boolean AV_sync_state; + boolean mute_state; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; + boolean bypass_mode; + } audio_status_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.5</abbrev>struct audio_mixer</title> +<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio +volume. +</para> +<programlisting> + typedef struct audio_mixer { + unsigned int volume_left; + unsigned int volume_right; + } audio_mixer_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.6</abbrev>audio encodings</title> +<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following +bits set according to the hardwares capabilities. +</para> +<programlisting> + #define AUDIO_CAP_DTS 1 + #define AUDIO_CAP_LPCM 2 + #define AUDIO_CAP_MP1 4 + #define AUDIO_CAP_MP2 8 + #define AUDIO_CAP_MP3 16 + #define AUDIO_CAP_AAC 32 + #define AUDIO_CAP_OGG 64 + #define AUDIO_CAP_SDDS 128 + #define AUDIO_CAP_AC3 256 +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.7</abbrev>struct audio_karaoke</title> +<para>The ioctl AUDIO_SET_KARAOKE uses the following format: +</para> +<programlisting> + typedef + struct audio_karaoke{ + int vocal1; + int vocal2; + int melody; + } audio_karaoke_t; +</programlisting> +<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both, +Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the +right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left +and right. +</para> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.1.8</abbrev>audio attributes</title> +<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: +</para> +<programlisting> + typedef uint16_t audio_attributes_t; + /⋆ bits: descr. ⋆/ + /⋆ 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, ⋆/ + /⋆ 12 multichannel extension ⋆/ + /⋆ 11-10 audio type (0=not spec, 1=language included) ⋆/ + /⋆ 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) ⋆/ + /⋆ 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, ⋆/ + /⋆ 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) ⋆/ + /⋆ 2- 0 number of audio channels (n+1 channels) ⋆/ +</programlisting> + </section></section><section +role="section"><title><abbrev role="title-mark">5.2</abbrev>Audio Function Calls</title> + +<section +role="subsection"><title><abbrev role="title-mark">5.2.1</abbrev>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) + for subsequent use. When an open() call has succeeded, the device will be ready + for use. The significance of blocking or non-blocking mode is described in the + documentation for functions where there is a difference. It does not affect the + semantics of the open() call itself. A device opened in blocking mode can later + be put into non-blocking mode (and vice versa) using the F_SETFL command + of the fcntl system call. This is a standard system call, documented in the Linux + manual page for fcntl. Only one user can open the Audio Device in O_RDWR + mode. All other attempts to open the device in this mode will fail, and an error + code will be returned. If the Audio Device is opened in O_RDONLY mode, the + only ioctl call that can be used is AUDIO_GET_STATUS. All other call will + return with an error code.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific audio device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.2</abbrev>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened audio device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.3</abbrev>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected + in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in + PES format. If O_NONBLOCK is not specified the function will block until + buffer space is available. The amount of data to be transferred is implied by + count.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>size_t write(int fd, const void ⋆buf, size_t count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer containing the PES data.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode AUDIO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>Attempted to write more data than the internal buffer can + hold.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.4</abbrev>AUDIO_STOP<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to stop playing the current stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_STOP);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_STOP for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.5</abbrev>AUDIO_PLAY<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to start playing an audio stream from the + selected source.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_PLAY);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_PLAY for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.6</abbrev>AUDIO_PAUSE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call suspends the audio stream being played. Decoding and playing + are paused. It is then possible to restart again decoding and playing process of + the audio stream using AUDIO_CONTINUE command.</para> +</entry> + </row><row><entry + align="char"> +<para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call + AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume) + any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is + performed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_PAUSE for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.7</abbrev>AUDIO_SELECT_SOURCE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call informs the audio device which source shall be used + for the input data. The possible sources are demux or memory. If + AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device + through the write command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, + audio_stream_source_t source);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SELECT_SOURCE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_stream_source_t + source</para> +</entry><entry + align="char"> +<para>Indicates the source that shall be used for the Audio + stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.8</abbrev>AUDIO_SET_MUTE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the audio device to mute the stream that is currently being + played.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_MUTE, + boolean state);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_MUTE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean state</para> +</entry><entry + align="char"> +<para>Indicates if audio device shall mute or not.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE Audio Mute</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE Audio Un-mute</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.9</abbrev>AUDIO_SET_AV_SYNC<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, + boolean state);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_AV_SYNC for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean state</para> +</entry><entry + align="char"> +<para>Tells the DVB subsystem if A/V synchronization shall be + ON or OFF.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE AV-sync ON</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE AV-sync OFF</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.10</abbrev>AUDIO_SET_BYPASS_MODE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward + the stream without decoding. This mode shall be used if streams that can’t be + handled by the DVB system shall be decoded. Dolby DigitalTM streams are + automatically forwarded by the DVB subsystem if the hardware can handle it.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_SET_BYPASS_MODE, boolean mode);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_BYPASS_MODE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean mode</para> +</entry><entry + align="char"> +<para>Enables or disables the decoding of the current Audio + stream in the DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE Bypass is disabled</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE Bypass is enabled</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.11</abbrev>AUDIO_CHANNEL_SELECT<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_CHANNEL_SELECT for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_channel_select_t + ch</para> +</entry><entry + align="char"> +<para>Select the output format of the audio (mono left/right, + stereo).</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter ch.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.12</abbrev>AUDIO_GET_STATUS<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to return the current state of the Audio + Device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_GET_STATUS, + struct audio_status ⋆status);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_GET_STATUS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct audio_status + *status</para> +</entry><entry + align="char"> +<para>Returns the current state of Audio Device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.13</abbrev>AUDIO_GET_CAPABILITIES<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities + of the audio hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_GET_CAPABILITIES, unsigned int ⋆cap);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_GET_CAPABILITIES for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned int *cap</para> +</entry><entry + align="char"> +<para>Returns a bit array of supported sound formats.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>cap points to an invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.14</abbrev>AUDIO_CLEAR_BUFFER<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to clear all software and hardware buffers + of the audio decoder device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_CLEAR_BUFFER for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.15</abbrev>AUDIO_SET_ID<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl selects which sub-stream is to be decoded if a program or system + stream is sent to the video device. If no audio stream type is set the id has to be + in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] + for LPCM. More specifications may follow for other stream types. If the stream + type is set the id just specifies the substream id of the audio stream and only + the first 5 bits are recognized.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_ID, int + id);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int id</para> +</entry><entry + align="char"> +<para>audio sub-stream id</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid sub-stream id.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.16</abbrev>AUDIO_SET_MIXER<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_MIXER, + audio_mixer_t ⋆mix);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_mixer_t *mix</para> +</entry><entry + align="char"> +<para>mixer settings.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>mix points to an invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.17</abbrev>AUDIO_SET_STREAMTYPE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl tells the driver which kind of audio stream to expect. This is useful + if the stream offers several audio sub-streams like LPCM and AC3.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, + int type);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_STREAMTYPE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>int type</para> +</entry><entry + align="char"> +<para>stream type</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>type is not a valid or supported stream type.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.18</abbrev>AUDIO_SET_EXT_ID<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl can be used to set the extension id for MPEG streams in DVD + playback. Only the first 3 bits are recognized.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int + id);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_EXT_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int id</para> +</entry><entry + align="char"> +<para>audio sub_stream_id</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>id is not a valid id.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.19</abbrev>AUDIO_SET_ATTRIBUTES<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is intended for DVD playback and allows you to set certain + information about the audio stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, + audio_attributes_t attr );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_attributes_t + attr</para> +</entry><entry + align="char"> +<para>audio attributes according to section ??</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>attr is not a valid or supported attribute setting.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">5.2.20</abbrev>AUDIO_SET_KARAOKE<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, + audio_karaoke_t ⋆karaoke);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_STREAMTYPE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_karaoke_t + *karaoke</para> +</entry><entry + align="char"> +<para>karaoke settings according to section ??.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>karaoke is not a valid or supported karaoke setting.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + </section></section></section><section +role="chapter"><title>DVB CA Device</title> +<para>The DVB CA device controls the conditional access hardware. It can be accessed through +<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by +including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application. +</para> +<section +role="section"><title><abbrev role="title-mark">6.1</abbrev>CA Data Types</title> + +<section +role="subsection"><title><abbrev role="title-mark">6.1.1</abbrev>ca_slot_info_t</title> + <programlisting> + /⋆ slot interface types and info ⋆/ + + typedef struct ca_slot_info_s { + int num; /⋆ slot number ⋆/ + + int type; /⋆ CA interface this slot supports ⋆/ + #define CA_CI 1 /⋆ CI high level interface ⋆/ + #define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/ + #define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/ + #define CA_SC 128 /⋆ simple smart card interface ⋆/ + + unsigned int flags; + #define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/ + #define CA_CI_MODULE_READY 2 + } ca_slot_info_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">6.1.2</abbrev>ca_descr_info_t</title> + <programlisting> + typedef struct ca_descr_info_s { + unsigned int num; /⋆ number of available descramblers (keys) ⋆/ + unsigned int type; /⋆ type of supported scrambling system ⋆/ + #define CA_ECD 1 + #define CA_NDS 2 + #define CA_DSS 4 + } ca_descr_info_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">6.1.3</abbrev>ca_cap_t</title> + <programlisting> + typedef struct ca_cap_s { + unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/ + unsigned int slot_type; /⋆ OR of all supported types ⋆/ + unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/ + unsigned int descr_type;/⋆ OR of all supported types ⋆/ + } ca_cap_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">6.1.4</abbrev>ca_msg_t</title> + <programlisting> + /⋆ a message to/from a CI-CAM ⋆/ + typedef struct ca_msg_s { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; + } ca_msg_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">6.1.5</abbrev>ca_descr_t</title> + <programlisting> + typedef struct ca_descr_s { + unsigned int index; + unsigned int parity; + unsigned char cw[8]; + } ca_descr_t; +</programlisting> + </section></section><section +role="section"><title><abbrev role="title-mark">6.2</abbrev>CA Function Calls</title> + +<section +role="subsection"><title><abbrev role="title-mark">6.2.1</abbrev>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use. +<para>When an open() call has succeeded, the device will be ready for use. + The significance of blocking or non-blocking mode is described in the + documentation for functions where there is a difference. It does not affect the + semantics of the open() call itself. A device opened in blocking mode can later + be put into non-blocking mode (and vice versa) using the F_SETFL command + of the fcntl system call. This is a standard system call, documented in the Linux + manual page for fcntl. Only one user can open the CA Device in O_RDWR + mode. All other attempts to open the device in this mode will fail, and an error + code will be returned.</para> +</entry> + </row></tbody></tgroup></informaltable> +</para> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific video device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">6.2.2</abbrev>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened audio device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + </section></section></section><section +role="chapter"><title>DVB Network API</title> +<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets +received via DVB into the Linux network protocol stack, e.g. for internet via satellite +applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and +and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your +application. +</para> +<section +role="section"><title><abbrev role="title-mark">7.1</abbrev>DVB Net Data Types</title> +<para>To be written… +</para> + +</section></section><section +role="chapter"><title>Kernel Demux API</title> +<para>The kernel demux API defines a driver-internal interface for registering low-level, +hardware specific driver to a hardware independent demux layer. It is only of interest for +DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in +<emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>. +</para> +<para>Maintainer note: This section must be reviewed. It is probably out of date. +</para> +<section +role="section"><title><abbrev role="title-mark">8.1</abbrev>Kernel Demux Data Types</title> + +<section +role="subsection"><title><abbrev role="title-mark">8.1.1</abbrev>dmx_success_t</title> + <programlisting> + typedef enum { + DMX_OK = 0, /⋆ Received Ok ⋆/ + DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ + DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ + DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ + DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ + DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ + DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ + } dmx_success_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.1.2</abbrev>TS filter types</title> + <programlisting> + /⋆--------------------------------------------------------------------------⋆/ + /⋆ TS packet reception ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + /⋆ TS filter type for set_type() ⋆/ + + #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ + #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS + payload (<=184 bytes per packet) to callback ⋆/ + #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.1.3</abbrev>dmx_ts_pes_t</title> +<para>The structure +</para> +<programlisting> + typedef enum + { + DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ + DMX_TS_PES_VIDEO, /⋆ ... ⋆/ + DMX_TS_PES_TELETEXT, + DMX_TS_PES_SUBTITLE, + DMX_TS_PES_PCR, + DMX_TS_PES_OTHER, + } dmx_ts_pes_t; +</programlisting> +<para>describes the PES type for filters which write to a built-in decoder. The correspond (and +should be kept identical) to the types in the demux device. +</para> +<programlisting> + struct dmx_ts_feed_s { + int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ + struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int (⋆set) (struct dmx_ts_feed_s⋆ feed, + __u16 pid, + size_t callback_length, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); + int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); + int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, + int type, + dmx_ts_pes_t pes_type); + }; + + typedef struct dmx_ts_feed_s dmx_ts_feed_t; +</programlisting> + <programlisting> + /⋆--------------------------------------------------------------------------⋆/ + /⋆ PES packet reception (not supported yet) ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + typedef struct dmx_pes_filter_s { + struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + } dmx_pes_filter_t; +</programlisting> + <programlisting> + typedef struct dmx_pes_feed_s { + int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ + struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int (⋆set) (struct dmx_pes_feed_s⋆ feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); + int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); + int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, + dmx_pes_filter_t⋆⋆ filter); + int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, + dmx_pes_filter_t⋆ filter); + } dmx_pes_feed_t; +</programlisting> + <programlisting> + typedef struct { + __u8 filter_value [DMX_MAX_FILTER_SIZE]; + __u8 filter_mask [DMX_MAX_FILTER_SIZE]; + struct dmx_section_feed_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + } dmx_section_filter_t; +</programlisting> + <programlisting> + struct dmx_section_feed_s { + int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ + struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int (⋆set) (struct dmx_section_feed_s⋆ feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + int check_crc); + int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, + dmx_section_filter_t⋆⋆ filter); + int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, + dmx_section_filter_t⋆ filter); + int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); + int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); + }; + typedef struct dmx_section_feed_s dmx_section_feed_t; + + /⋆--------------------------------------------------------------------------⋆/ + /⋆ Callback functions ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + typedef int (⋆dmx_ts_cb) ( __u8 ⋆ buffer1, + size_t buffer1_length, + __u8 ⋆ buffer2, + size_t buffer2_length, + dmx_ts_feed_t⋆ source, + dmx_success_t success); + + typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, + size_t buffer1_len, + __u8 ⋆ buffer2, + size_t buffer2_len, + dmx_section_filter_t ⋆ source, + dmx_success_t success); + + typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, + size_t buffer1_len, + __u8 ⋆ buffer2, + size_t buffer2_len, + dmx_pes_filter_t⋆ source, + dmx_success_t success); + + /⋆--------------------------------------------------------------------------⋆/ + /⋆ DVB Front-End ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + typedef enum { + DMX_OTHER_FE = 0, + DMX_SATELLITE_FE, + DMX_CABLE_FE, + DMX_TERRESTRIAL_FE, + DMX_LVDS_FE, + DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ + DMX_MEMORY_FE + } dmx_frontend_source_t; + + typedef struct { + /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ + char⋆ id; /⋆ Unique front-end identifier ⋆/ + char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ + char⋆ model; /⋆ Name of the front-end model ⋆/ + struct list_head connectivity_list; /⋆ List of front-ends that can + be connected to a particular + demux ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + dmx_frontend_source_t source; + } dmx_frontend_t; + + /⋆--------------------------------------------------------------------------⋆/ + /⋆ MPEG-2 TS Demux ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + /⋆ + ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. + ⋆/ + + #define DMX_TS_FILTERING 1 + #define DMX_PES_FILTERING 2 + #define DMX_SECTION_FILTERING 4 + #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ + #define DMX_CRC_CHECKING 16 + #define DMX_TS_DESCRAMBLING 32 + #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 + #define DMX_MAC_ADDRESS_DESCRAMBLING 128 +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.1.4</abbrev>demux_demux_t</title> + <programlisting> + /⋆ + ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered + ⋆ front-ends from the generic type struct list_head + ⋆ to the type ⋆ dmx_frontend_t + ⋆. + ⋆/ + + #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) + + struct dmx_demux_s { + /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ + char⋆ id; /⋆ Unique demux identifier ⋆/ + char⋆ vendor; /⋆ Name of the demux vendor ⋆/ + char⋆ model; /⋆ Name of the demux model ⋆/ + __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ + dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ + struct list_head reg_list; /⋆ List of registered demuxes ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int users; /⋆ Number of users ⋆/ + int (⋆open) (struct dmx_demux_s⋆ demux); + int (⋆close) (struct dmx_demux_s⋆ demux); + int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); + int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, + dmx_ts_feed_t⋆⋆ feed, + dmx_ts_cb callback); + int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, + dmx_ts_feed_t⋆ feed); + int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, + dmx_pes_feed_t⋆⋆ feed, + dmx_pes_cb callback); + int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, + dmx_pes_feed_t⋆ feed); + int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, + dmx_section_feed_t⋆⋆ feed, + dmx_section_cb callback); + int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, + dmx_section_feed_t⋆ feed); + int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, + __u8⋆ buffer1, + size_t buffer1_length, + __u8⋆ buffer2, + size_t buffer2_length, + __u16 pid); + int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, + __u8⋆ buffer1, + size_t buffer1_length, + __u8⋆ buffer2, size_t buffer2_length, + __u16 pid); + int (⋆add_frontend) (struct dmx_demux_s⋆ demux, + dmx_frontend_t⋆ frontend); + int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, + dmx_frontend_t⋆ frontend); + struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); + int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, + dmx_frontend_t⋆ frontend); + int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); + + + /⋆ added because js cannot keep track of these himself ⋆/ + int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); + }; + typedef struct dmx_demux_s dmx_demux_t; +</programlisting> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.1.5</abbrev>Demux directory</title> + <programlisting> + /⋆ + ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered + ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t + ⋆. + ⋆/ + + #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) + + int dmx_register_demux (dmx_demux_t⋆ demux); + int dmx_unregister_demux (dmx_demux_t⋆ demux); + struct list_head⋆ dmx_get_demuxes (void); +</programlisting> + </section></section><section +role="section"><title><abbrev role="title-mark">8.2</abbrev>Demux Directory API</title> +<para>The demux directory is a Linux kernel-wide facility for registering and accessing the +MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers +is possible using this API. +</para> +<para>All demux drivers in the directory implement the abstract interface dmx_demux_t. +</para> + +<section +role="subsection"><title><abbrev role="title-mark">8.2.1</abbrev>dmx_register_demux()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function makes a demux driver interface available to the Linux kernel. It is + usually called by the init_module() function of the kernel module that contains + the demux driver. The caller of this function is responsible for allocating + dynamic or static memory for the demux structure and for initializing its fields + before calling this function. The memory allocated for the demux structure + must not be freed before calling dmx_unregister_demux(),</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux structure.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EEXIST</para> +</entry><entry + align="char"> +<para>A demux with the same value of the id field already stored + in the directory.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSPC</para> +</entry><entry + align="char"> +<para>No space left in the directory.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.2.2</abbrev>dmx_unregister_demux()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function is called to indicate that the given demux interface is no + longer available. The caller of this function is responsible for freeing the + memory of the demux structure, if it was dynamically allocated before calling + dmx_register_demux(). The cleanup_module() function of the kernel module + that contains the demux driver should call this function. Note that this function + fails if the demux is currently in use, i.e., release_demux() has not been called + for the interface.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux structure which is to be + unregistered.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>The specified demux is not registered in the demux + directory.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>The specified demux is currently in use.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.2.3</abbrev>dmx_get_demuxes()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Provides the caller with the list of registered demux interfaces, using the + standard list structure defined in the include file linux/list.h. The include file + demux.h defines the macro DMX_DIR_ENTRY() for converting an element of + the generic type struct list_head* to the type dmx_demux_t*. The caller must + not free the memory of any of the elements obtained via this function call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>struct list_head ⋆dmx_get_demuxes ()</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>none</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>struct list_head *</para> +</entry><entry + align="char"> +<para>A list of demux interfaces, or NULL in the case of an + empty list.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section><section +role="section"><title><abbrev role="title-mark">8.3</abbrev>Demux API</title> +<para>The demux API should be implemented for each demux in the system. It is used to select +the TS source of a demux and to manage the demux resources. When the demux +client allocates a resource via the demux API, it receives a pointer to the API of that +resource. +</para> +<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the +demux API. In a system with more than one front-end, the API can be used to select one of +the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The +demux API only controls front-ends regarding their connections with demuxes; the APIs +used to set the other front-end parameters, such as tuning, are not defined in this +document. +</para> +<para>The functions that implement the abstract interface demux should be defined static or +module private and registered to the Demux Directory for external access. It is not necessary +to implement every function in the demux_t struct, however (for example, a demux interface +might support Section filtering, but not TS or PES filtering). The API client is expected to +check the value of any function pointer before calling the function: the value of NULL means +“function not available”. +</para> +<para>Whenever the functions of the demux API modify shared data, the possibilities of lost +update and race condition problems should be addressed, e.g. by protecting parts of code with +mutexes. This is especially important on multi-processor hosts. +</para> +<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x +kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if +swapping is needed. For example, the Linux kernel calls the functions of a network device +interface from a bottom half context. Thus, if a demux API function is called from network +device code, the function must not sleep. +</para> + +<section +role="subsection"><title><abbrev role="title-mark">8.3.1</abbrev>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function reserves the demux for use by the caller and, if necessary, + initializes the demux. When the demux is no longer needed, the function close() + should be called. It should be possible for multiple clients to access the demux + at the same time. Thus, the function implementation should increment the + demux usage count when open() is called and decrement it when close() is + called.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open ( demux_t⋆ demux );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EUSERS</para> +</entry><entry + align="char"> +<para>Maximum usage count reached.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.2</abbrev>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function reserves the demux for use by the caller and, if necessary, + initializes the demux. When the demux is no longer needed, the function close() + should be called. It should be possible for multiple clients to access the demux + at the same time. Thus, the function implementation should increment the + demux usage count when open() is called and decrement it when close() is + called.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(demux_t⋆ demux);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENODEV</para> +</entry><entry + align="char"> +<para>The demux was not in use.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.3</abbrev>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function provides the demux driver with a memory buffer containing TS + packets. Instead of receiving TS packets from the DVB front-end, the demux + driver software will read packets from memory. Any clients of this demux + with active TS, PES or Section filters will receive filtered data via the Demux + callback API (see 0). The function returns when all the data in the buffer has + been consumed by the demux. Demux hardware typically cannot read TS from + memory. If this is the case, memory-based filtering has to be implemented + entirely in software.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int write(demux_t⋆ demux, const char⋆ buf, size_t + count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>const char* buf</para> +</entry><entry + align="char"> +<para>Pointer to the TS data in kernel-space memory.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t length</para> +</entry><entry + align="char"> +<para>Length of the TS data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>The command is not implemented.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.4</abbrev>allocate_ts_feed()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Allocates a new TS feed, which is used to filter the TS packets carrying a + certain PID. The TS feed normally corresponds to a hardware PID filter on the + demux chip.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int allocate_ts_feed(dmx_demux_t⋆ demux, + dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_feed_t** + feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_cb callback</para> +</entry><entry + align="char"> +<para>Pointer to the callback function for passing received TS + packet</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>No more TS feeds available.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>The command is not implemented.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.5</abbrev>release_ts_feed()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in + progress on the TS feed should be stopped before calling this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int release_ts_feed(dmx_demux_t⋆ demux, + dmx_ts_feed_t⋆ feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.6</abbrev>allocate_section_feed()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving + sections. On platforms with hardware support for section filtering, a section + feed is directly mapped to the demux HW. On other platforms, TS packets are + first PID filtered in hardware and a hardware section filter then emulated in + software. The caller obtains an API pointer of type dmx_section_feed_t as an + out parameter. Using this API the caller can set filtering parameters and start + receiving sections.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int allocate_section_feed(dmx_demux_t⋆ demux, + dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_feed_t + **feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_cb + callback</para> +</entry><entry + align="char"> +<para>Pointer to the callback function for passing received + sections.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>No more section feeds available.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>The command is not implemented.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.7</abbrev>release_section_feed()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Releases the resources allocated with allocate_section_feed(), including + allocated filters. Any filtering in progress on the section feed should be stopped + before calling this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int release_section_feed(dmx_demux_t⋆ demux, + dmx_section_feed_t ⋆feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_feed_t + *feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.8</abbrev>descramble_mac_address()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function runs a descrambling algorithm on the destination MAC + address field of a DVB Datagram Section, replacing the original address + with its un-encrypted version. Otherwise, the description on the function + descramble_section_payload() applies also to this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int descramble_mac_address(dmx_demux_t⋆ demux, __u8 + ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, + size_t buffer2_length, __u16 pid);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t + *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8 *buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the first byte of the section.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer1.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8* buffer2</para> +</entry><entry + align="char"> +<para>Pointer to the tail of the section data, or NULL. The + pointer has a non-NULL value if the section wraps past + the end of a circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer2.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>The PID on which the section was received. Useful + for obtaining the descrambling key, e.g. from a DVB + Common Access facility.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.9</abbrev>descramble_section_payload()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function runs a descrambling algorithm on the payload of a DVB + Datagram Section, replacing the original payload with its un-encrypted + version. The function will be called from the demux API implementation; + the API client need not call this function directly. Section-level scrambling + algorithms are currently standardized only for DVB-RCC (return channel + over 2-directional cable TV network) systems. For all other DVB networks, + encryption schemes are likely to be proprietary to each data broadcaster. Thus, + it is expected that this function pointer will have the value of NULL (i.e., + function not available) in most demux API implementations. Nevertheless, it + should be possible to use the function pointer as a hook for dynamically adding + a “plug-in” descrambling facility to a demux driver.</para> +</entry> + </row><row><entry + align="char"> +<para>While this function is not needed with hardware-based section descrambling, + the descramble_section_payload function pointer can be used to override the + default hardware-based descrambling algorithm: if the function pointer has a + non-NULL value, the corresponding function should be used instead of any + descrambling hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int descramble_section_payload(dmx_demux_t⋆ demux, + __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, + size_t buffer2_length, __u16 pid);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t + *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8 *buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the first byte of the section.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer1.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8 *buffer2</para> +</entry><entry + align="char"> +<para>Pointer to the tail of the section data, or NULL. The + pointer has a non-NULL value if the section wraps past + the end of a circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer2.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>The PID on which the section was received. Useful + for obtaining the descrambling key, e.g. from a DVB + Common Access facility.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.10</abbrev>add_frontend()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Registers a connectivity between a demux and a front-end, i.e., indicates that + the demux can be connected via a call to connect_frontend() to use the given + front-end as a TS source. The client of this function has to allocate dynamic or + static memory for the frontend structure and initialize its fields before calling + this function. This function is normally called during the driver initialization. + The caller must not free the memory of the frontend struct before successfully + calling remove_frontend().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t + ⋆frontend);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_frontend_t* + frontend</para> +</entry><entry + align="char"> +<para>Pointer to the front-end instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EEXIST</para> +</entry><entry + align="char"> +<para>A front-end with the same value of the id field already + registered.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINUSE</para> +</entry><entry + align="char"> +<para>The demux is in use.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOMEM</para> +</entry><entry + align="char"> +<para>No more front-ends can be added.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.11</abbrev>remove_frontend()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Indicates that the given front-end, registered by a call to add_frontend(), can + no longer be connected as a TS source by this demux. The function should be + called when a front-end driver or a demux driver is removed from the system. + If the front-end is in use, the function fails with the return value of -EBUSY. + After successfully calling this function, the caller can free the memory of + the frontend struct if it was dynamically allocated before the add_frontend() + operation.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int remove_frontend(dmx_demux_t⋆ demux, + dmx_frontend_t⋆ frontend);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_frontend_t* + frontend</para> +</entry><entry + align="char"> +<para>Pointer to the front-end instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>The front-end is in use, i.e. a call to connect_frontend() + has not been followed by a call to disconnect_frontend().</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.12</abbrev>get_frontends()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Provides the APIs of the front-ends that have been registered for this demux. + Any of the front-ends obtained with this call can be used as a parameter for + connect_frontend().</para> +</entry> + </row><row><entry + align="char"> +<para>The include file demux.h contains the macro DMX_FE_ENTRY() for + converting an element of the generic type struct list_head* to the type + dmx_frontend_t*. The caller must not free the memory of any of the elements + obtained via this function call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t*</para> +</entry><entry + align="char"> +<para>A list of front-end interfaces, or NULL in the case of an + empty list.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.13</abbrev>connect_frontend()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Connects the TS output of the front-end to the input of the demux. A demux + can only be connected to a front-end registered to the demux with the function + add_frontend().</para> +</entry> + </row><row><entry + align="char"> +<para>It may or may not be possible to connect multiple demuxes to the same + front-end, depending on the capabilities of the HW platform. When not used, + the front-end should be released by calling disconnect_frontend().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int connect_frontend(dmx_demux_t⋆ demux, + dmx_frontend_t⋆ frontend);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_frontend_t* + frontend</para> +</entry><entry + align="char"> +<para>Pointer to the front-end instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>The front-end is in use.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.3.14</abbrev>disconnect_frontend()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Disconnects the demux and a front-end previously connected by a + connect_frontend() call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int disconnect_frontend(dmx_demux_t⋆ demux);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section><section +role="section"><title><abbrev role="title-mark">8.4</abbrev>Demux Callback API</title> +<para>This kernel-space API comprises the callback functions that deliver filtered data to the +demux client. Unlike the other APIs, these API functions are provided by the client and called +from the demux code. +</para> +<para>The function pointers of this abstract interface are not packed into a structure as in the +other demux APIs, because the callback functions are registered and used independent +of each other. As an example, it is possible for the API client to provide several +callback functions for receiving TS packets and no callbacks for PES packets or +sections. +</para> +<para>The functions that implement the callback API need not be re-entrant: when a demux +driver calls one of these functions, the driver is not allowed to call the function again before +the original call returns. If a callback is triggered by a hardware interrupt, it is recommended +to use the Linux “bottom half” mechanism or start a tasklet instead of making the callback +function call directly from a hardware interrupt. +</para> + +<section +role="subsection"><title><abbrev role="title-mark">8.4.1</abbrev>dmx_ts_cb()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function, provided by the client of the demux API, is called from the + demux code. The function is only called when filtering on this TS feed has + been enabled using the start_filtering() function.</para> +</entry> + </row><row><entry + align="char"> +<para>Any TS packets that match the filter settings are copied to a circular buffer. The + filtered TS packets are delivered to the client using this callback function. The + size of the circular buffer is controlled by the circular_buffer_size parameter + of the set() function in the TS Feed API. It is expected that the buffer1 and + buffer2 callback parameters point to addresses within the circular buffer, but + other implementations are also possible. Note that the called party should not + try to free the memory the buffer1 and buffer2 parameters point to.</para> +</entry> + </row><row><entry + align="char"> +<para>When this function is called, the buffer1 parameter typically points to the + start of the first undelivered TS packet within a circular buffer. The buffer2 + buffer parameter is normally NULL, except when the received TS packets have + crossed the last address of the circular buffer and ”wrapped” to the beginning + of the buffer. In the latter case the buffer1 parameter would contain an address + within the circular buffer, while the buffer2 parameter would contain the first + address of the circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>The number of bytes delivered with this function (i.e. buffer1_length + + buffer2_length) is usually equal to the value of callback_length parameter + given in the set() function, with one exception: if a timeout occurs before + receiving callback_length bytes of TS data, any undelivered packets are + immediately delivered to the client by calling this function. The timeout + duration is controlled by the set() function in the TS Feed API.</para> +</entry> + </row><row><entry + align="char"> +<para>If a TS packet is received with errors that could not be fixed by the TS-level + forward error correction (FEC), the Transport_error_indicator flag of the TS + packet header should be set. The TS packet should not be discarded, as + the error can possibly be corrected by a higher layer protocol. If the called + party is slow in processing the callback, it is possible that the circular buffer + eventually fills up. If this happens, the demux driver should discard any TS + packets received while the buffer is full. The error should be indicated to the + client on the next callback by setting the success parameter to the value of + DMX_OVERRUN_ERROR.</para> +</entry> + </row><row><entry + align="char"> +<para>The type of data returned to the callback can be selected by the new + function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t + pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the + include file ost/demux.h) The type parameter decides if the raw TS packet + (TS_PACKET) or just the payload (TS_PACKET—TS_PAYLOAD_ONLY) + should be returned. If additionally the TS_DECODER bit is set the stream + will also be sent to the hardware MPEG decoder. In this case, the second + flag decides as what kind of data the stream should be interpreted. The + possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, + DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, + DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int dmx_ts_cb(__u8⋆ buffer1, size_t buffer1_length, + __u8⋆ buffer2, size_t buffer2_length, dmx_ts_feed_t⋆ + source, dmx_success_t success);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>__u8* buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the start of the filtered TS packets.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the TS data in buffer1.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8* buffer2</para> +</entry><entry + align="char"> +<para>Pointer to the tail of the filtered TS packets, or NULL.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the TS data in buffer2.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_feed_t* + source</para> +</entry><entry + align="char"> +<para>Indicates which TS feed is the source of the callback.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_success_t + success</para> +</entry><entry + align="char"> +<para>Indicates if there was an error in TS reception.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>Continue filtering.</para> +</entry> + </row><row><entry + align="char"> +<para>-1</para> +</entry><entry + align="char"> +<para>Stop filtering - has the same effect as a call to + stop_filtering() on the TS Feed API.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.4.2</abbrev>dmx_section_cb()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function, provided by the client of the demux API, is called from the + demux code. The function is only called when filtering of sections has been + enabled using the function start_filtering() of the section feed API. When the + demux driver has received a complete section that matches at least one section + filter, the client is notified via this callback function. Normally this function is + called for each received section; however, it is also possible to deliver multiple + sections with one callback, for example when the system load is high. If an + error occurs while receiving a section, this function should be called with + the corresponding error type set in the success field, whether or not there is + data to deliver. The Section Feed implementation should maintain a circular + buffer for received sections. However, this is not necessary if the Section Feed + API is implemented as a client of the TS Feed API, because the TS Feed + implementation then buffers the received data. The size of the circular buffer + can be configured using the set() function in the Section Feed API. If there + is no room in the circular buffer when a new section is received, the section + must be discarded. If this happens, the value of the success parameter should + be DMX_OVERRUN_ERROR on the next callback.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int dmx_section_cb(__u8⋆ buffer1, size_t + buffer1_length, __u8⋆ buffer2, size_t + buffer2_length, dmx_section_filter_t⋆ source, + dmx_success_t success);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>__u8* buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the start of the filtered section, e.g. within the + circular buffer of the demux driver.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the filtered section data in buffer1, including + headers and CRC.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8* buffer2</para> +</entry><entry + align="char"> +<para>Pointer to the tail of the filtered section data, or NULL. + Useful to handle the wrapping of a circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the filtered section data in buffer2, including + headers and CRC.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_filter_t* + filter</para> +</entry><entry + align="char"> +<para>Indicates the filter that triggered the callback.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_success_t + success</para> +</entry><entry + align="char"> +<para>Indicates if there was an error in section reception.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>Continue filtering.</para> +</entry> + </row><row><entry + align="char"> +<para>-1</para> +</entry><entry + align="char"> +<para>Stop filtering - has the same effect as a call to + stop_filtering() on the Section Feed API.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section><section +role="section"><title><abbrev role="title-mark">8.5</abbrev>TS Feed API</title> +<para>A TS feed is typically mapped to a hardware PID filter on the demux chip. +Using this API, the client can set the filtering properties to start/stop filtering TS +packets on a particular TS feed. The API is defined as an abstract interface of the type +dmx_ts_feed_t. +</para> +<para>The functions that implement the interface should be defined static or module private. The +client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the +demux API. +</para> + +<section +role="subsection"><title><abbrev role="title-mark">8.5.1</abbrev>set()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function sets the parameters of a TS feed. Any filtering in progress on the + TS feed must be stopped before calling this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t + callback_length, size_t circular_buffer_size, int + descramble, struct timespec timeout);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>PID value to filter. Only the TS packets carrying the + specified PID will be passed to the API client.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t + callback_length</para> +</entry><entry + align="char"> +<para>Number of bytes to deliver with each call to the + dmx_ts_cb() callback function. The value of this + parameter should be a multiple of 188.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t + circular_buffer_size</para> +</entry><entry + align="char"> +<para>Size of the circular buffer for the filtered TS packets.</para> +</entry> + </row><row><entry + align="char"> +<para>int descramble</para> +</entry><entry + align="char"> +<para>If non-zero, descramble the filtered TS packets.</para> +</entry> + </row><row><entry + align="char"> +<para>struct timespec + timeout</para> +</entry><entry + align="char"> +<para>Maximum time to wait before delivering received TS + packets to the client.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOMEM</para> +</entry><entry + align="char"> +<para>Not enough memory for the requested buffer size.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available for TS.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.5.2</abbrev>start_filtering()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Starts filtering TS packets on this TS feed, according to its settings. The PID + value to filter can be set by the API client. All matching TS packets are + delivered asynchronously to the client, using the callback function registered + with allocate_ts_feed().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int start_filtering(dmx_ts_feed_t⋆ feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.5.3</abbrev>stop_filtering()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Stops filtering TS packets on this TS feed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section><section +role="section"><title><abbrev role="title-mark">8.6</abbrev>Section Feed API</title> +<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this +API, the client can set the properties of a section feed and to start/stop filtering. The API is +defined as an abstract interface of the type dmx_section_feed_t. The functions that implement +the interface should be defined static or module private. The client can get the handle of +a section feed API by calling the function allocate_section_feed() in the demux +API. +</para> +<para>On demux platforms that provide section filtering in hardware, the Section Feed API +implementation provides a software wrapper for the demux hardware. Other platforms may +support only PID filtering in hardware, requiring that TS packets are converted to sections in +software. In the latter case the Section Feed API implementation can be a client of the TS +Feed API. +</para> + +<section +role="subsection"><title><abbrev role="title-mark">8.6.1</abbrev>set()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function sets the parameters of a section feed. Any filtering in progress on + the section feed must be stopped before calling this function. If descrambling + is enabled, the payload_scrambling_control and address_scrambling_control + fields of received DVB datagram sections should be observed. If either one is + non-zero, the section should be descrambled either in hardware or using the + functions descramble_mac_address() and descramble_section_payload() of the + demux API. Note that according to the MPEG-2 Systems specification, only + the payloads of private sections can be scrambled while the rest of the section + data must be sent in the clear.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t + circular_buffer_size, int descramble, int + check_crc);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>PID value to filter; only the TS packets carrying the + specified PID will be accepted.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t + circular_buffer_size</para> +</entry><entry + align="char"> +<para>Size of the circular buffer for filtered sections.</para> +</entry> + </row><row><entry + align="char"> +<para>int descramble</para> +</entry><entry + align="char"> +<para>If non-zero, descramble any sections that are scrambled.</para> +</entry> + </row><row><entry + align="char"> +<para>int check_crc</para> +</entry><entry + align="char"> +<para>If non-zero, check the CRC values of filtered sections.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOMEM</para> +</entry><entry + align="char"> +<para>Not enough memory for the requested buffer size.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available for sections.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameters.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.6.2</abbrev>allocate_filter()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function is used to allocate a section filter on the demux. It should only be + called when no filtering is in progress on this section feed. If a filter cannot be + allocated, the function fails with -ENOSPC. See in section ?? for the format of + the section filter.</para> +</entry> + </row><row><entry + align="char"> +<para>The bitfields filter_mask and filter_value should only be modified when no + filtering is in progress on this section feed. filter_mask controls which bits of + filter_value are compared with the section headers/payload. On a binary value + of 1 in filter_mask, the corresponding bits are compared. The filter only accepts + sections that are equal to filter_value in all the tested bit positions. Any changes + to the values of filter_mask and filter_value are guaranteed to take effect only + when the start_filtering() function is called next time. The parent pointer in + the struct is initialized by the API implementation to the value of the feed + parameter. The priv pointer is not used by the API implementation, and can + thus be freely utilized by the caller of this function. Any data pointed to by the + priv pointer is available to the recipient of the dmx_section_cb() function call.</para> +</entry> + </row><row><entry + align="char"> +<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is + currently set at 16 bytes, hardware filters of that size are not available on all + platforms. Therefore, section filtering will often take place first in hardware, + followed by filtering in software for the header bytes that were not covered + by a hardware filter. The filter_mask field can be checked to determine how + many bytes of the section filter are actually used, and if the hardware filter will + suffice. Additionally, software-only section filters can optionally be allocated + to clients when all hardware section filters are in use. Note that on most demux + hardware it is not possible to filter on the section_length field of the section + header – thus this field is ignored, even though it is included in filter_value and + filter_mask fields.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int allocate_filter(dmx_section_feed_t⋆ feed, + dmx_section_filter_t⋆⋆ filter);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_filter_t** + filter</para> +</entry><entry + align="char"> +<para>Pointer to the allocated filter.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSPC</para> +</entry><entry + align="char"> +<para>No filters of given type and length available.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameters.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.6.3</abbrev>release_filter()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function releases all the resources of a previously allocated section filter. + The function should not be called while filtering is in progress on this section + feed. After calling this function, the caller should not try to dereference the + filter pointer.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int release_filter ( dmx_section_feed_t⋆ feed, + dmx_section_filter_t⋆ filter);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_filter_t* + filter</para> +</entry><entry + align="char"> +<para>I/O Pointer to the instance data of a section filter.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENODEV</para> +</entry><entry + align="char"> +<para>No such filter allocated.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.6.4</abbrev>start_filtering()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Starts filtering sections on this section feed, according to its settings. Sections + are first filtered based on their PID and then matched with the section + filters allocated for this feed. If the section matches the PID filter and + at least one section filter, it is delivered to the API client. The section + is delivered asynchronously using the callback function registered with + allocate_section_feed().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int start_filtering ( dmx_section_feed_t⋆ feed );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title><abbrev role="title-mark">8.6.5</abbrev>stop_filtering()<indexterm role="printindex" /></title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Stops filtering sections on this section feed. Note that any changes to the + filtering parameters (filter_value, filter_mask, etc.) should only be made when + filtering is stopped.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section></section></section><section +role="chapter"><title>Examples</title> +<para>In this section we would like to present some examples for using the DVB API. +</para> +<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged +with the driver distribution from <emphasis role="tt">http://linuxtv.org/</emphasis>. +</para> +<section +role="section"><title><abbrev role="title-mark">9.1</abbrev>Tuning</title> +<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as +the demux devices. The example is given for QPSK tuners, but can easily be adjusted for +QAM. +</para> +<programlisting> + #include <sys/ioctl.h> + #include <stdio.h> + #include <stdint.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <time.h> + #include <unistd.h> + + #include <linux/dvb/dmx.h> + #include <linux/dvb/frontend.h> + #include <linux/dvb/sec.h> + #include <sys/poll.h> + + #define DMX "/dev/dvb/adapter0/demux1" + #define FRONT "/dev/dvb/adapter0/frontend1" + #define SEC "/dev/dvb/adapter0/sec1" + + /⋆ routine for checking if we have a signal and other status information⋆/ + int FEReadStatus(int fd, fe_status_t ⋆stat) + { + int ans; + + if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ + perror("FE READ STATUS: "); + return -1; + } + + if (⋆stat & FE_HAS_POWER) + printf("FE HAS POWER\n"); + + if (⋆stat & FE_HAS_SIGNAL) + printf("FE HAS SIGNAL\n"); + + if (⋆stat & FE_SPECTRUM_INV) + printf("SPEKTRUM INV\n"); + + return 0; + } + + + /⋆ tune qpsk ⋆/ + /⋆ freq: frequency of transponder ⋆/ + /⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/ + /⋆ diseqc: DiSEqC address of the used LNB ⋆/ + /⋆ pol: Polarisation ⋆/ + /⋆ srate: Symbol Rate ⋆/ + /⋆ fec. FEC ⋆/ + /⋆ lnb_lof1: local frequency of lower LNB band ⋆/ + /⋆ lnb_lof2: local frequency of upper LNB band ⋆/ + /⋆ lnb_slof: switch frequency of LNB ⋆/ + + int set_qpsk_channel(int freq, int vpid, int apid, int tpid, + int diseqc, int pol, int srate, int fec, int lnb_lof1, + int lnb_lof2, int lnb_slof) + { + struct secCommand scmd; + struct secCmdSequence scmds; + struct dmx_pes_filter_params pesFilterParams; + FrontendParameters frp; + struct pollfd pfd[1]; + FrontendEvent event; + int demux1, demux2, demux3, front; + + frequency = (uint32_t) freq; + symbolrate = (uint32_t) srate; + + if((front = open(FRONT,O_RDWR)) < 0){ + perror("FRONTEND DEVICE: "); + return -1; + } + + if((sec = open(SEC,O_RDWR)) < 0){ + perror("SEC DEVICE: "); + return -1; + } + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux3 < 0){ + if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (freq < lnb_slof) { + frp.Frequency = (freq - lnb_lof1); + scmds.continuousTone = SEC_TONE_OFF; + } else { + frp.Frequency = (freq - lnb_lof2); + scmds.continuousTone = SEC_TONE_ON; + } + frp.Inversion = INVERSION_AUTO; + if (pol) scmds.voltage = SEC_VOLTAGE_18; + else scmds.voltage = SEC_VOLTAGE_13; + + scmd.type=0; + scmd.u.diseqc.addr=0x10; + scmd.u.diseqc.cmd=0x38; + scmd.u.diseqc.numParams=1; + scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) | + (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | + (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); + + scmds.miniCommand=SEC_MINI_NONE; + scmds.numCommands=1; + scmds.commands=&scmd; + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + frp.u.qpsk.SymbolRate = srate; + frp.u.qpsk.FEC_inner = fec; + + if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ + perror("QPSK TUNE: "); + return -1; + } + + pfd[0].fd = front; + pfd[0].events = POLLIN; + + if (poll(pfd,1,3000)){ + if (pfd[0].revents & POLLIN){ + printf("Getting QPSK event\n"); + if ( ioctl(front, FE_GET_EVENT, &event) + + == -EOVERFLOW){ + perror("qpsk get event"); + return -1; + } + printf("Received "); + switch(event.type){ + case FE_UNEXPECTED_EV: + printf("unexpected event\n"); + return -1; + case FE_FAILURE_EV: + printf("failure event\n"); + return -1; + + case FE_COMPLETION_EV: + printf("completion event\n"); + } + } + } + + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_vpid"); + return -1; + } + + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_apid"); + return -1; + } + + pesFilterParams.pid = tpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_TELETEXT; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_tpid"); + return -1; + } + + return has_signal(fds); + } + +</programlisting> +<para>The program assumes that you are using a universal LNB and a standard DiSEqC +switch with up to 4 addresses. Of course, you could build in some more checking if +tuning was successful and maybe try to repeat the tuning process. Depending on the +external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be +necessary. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">9.2</abbrev>The DVR device</title> +<para>The following program code shows how to use the DVR device for recording. +</para> +<programlisting> + #include <sys/ioctl.h> + #include <stdio.h> + #include <stdint.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <time.h> + #include <unistd.h> + + #include <linux/dvb/dmx.h> + #include <linux/dvb/video.h> + #include <sys/poll.h> + #define DVR "/dev/dvb/adapter0/dvr1" + #define AUDIO "/dev/dvb/adapter0/audio1" + #define VIDEO "/dev/dvb/adapter0/video1" + + #define BUFFY (188⋆20) + #define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/ + + + /⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/ + + /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ + /⋆ vpid, apid: PIDs of video and audio channels ⋆/ + + int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) + { + struct dmx_pes_filter_params pesFilterParams; + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pes_type = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pes_type = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + return 0; + } + + /⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/ + + /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ + /⋆ vpid, apid: PIDs of video and audio channels ⋆/ + int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) + { + int i; + int len; + int written; + uint8_t buf[BUFFY]; + uint64_t length; + struct pollfd pfd[1]; + int dvr, dvr_out; + + /⋆ open dvr device ⋆/ + if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ + perror("DVR DEVICE"); + return -1; + } + + /⋆ switch video and audio demuxes to dvr ⋆/ + printf ("Switching dvr on\n"); + i = switch_to_record(demux1, demux2, vpid, apid); + printf("finished: "); + + printf("Recording %2.0f MB of test file in TS format\n", + MAX_LENGTH/(1024.0⋆1024.0)); + length = 0; + + /⋆ open output file ⋆/ + if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT + |O_TRUNC, S_IRUSR|S_IWUSR + |S_IRGRP|S_IWGRP|S_IROTH| + S_IWOTH)) < 0){ + perror("Can't open file for dvr test"); + return -1; + } + + pfd[0].fd = dvr; + pfd[0].events = POLLIN; + + /⋆ poll for dvr data and write to file ⋆/ + while (length < MAX_LENGTH ) { + if (poll(pfd,1,1)){ + if (pfd[0].revents & POLLIN){ + len = read(dvr, buf, BUFFY); + if (len < 0){ + perror("recording"); + return -1; + } + if (len > 0){ + written = 0; + while (written < len) + written += + write (dvr_out, + buf, len); + length += len; + printf("written %2.0f MB\r", + length/1024./1024.); + } + } + } + } + return 0; + } + +</programlisting> + + + +</section>GNU Free Documentation License +<para>Version 1.1, March 2000 +</para> +<para>Copyright © 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Everyone is permitted to copy and distribute verbatim copies of this license document, but +changing it is not allowed. +</para> +<section +role="likesection"><title>Preamble</title> +<para>The purpose of this License is to make a manual, textbook, or other written document +“free” in the sense of freedom: to assure everyone the effective freedom to copy and +redistribute it, with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way to get credit +for their work, while not being considered responsible for modifications made by +others. +</para> +<para>This License is a kind of “copyleft”, which means that derivative works of the document +must themselves be free in the same sense. It complements the GNU General Public License, +which is a copyleft license designed for free software. +</para> +<para>We have designed this License in order to use it for manuals for free software, because +free software needs free documentation: a free program should come with manuals providing +the same freedoms that the software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or whether it is published as a +printed book. We recommend this License principally for works whose purpose is instruction +or reference. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.1</abbrev>Applicability and Definitions</title> +<para>This License applies to any manual or other work that contains a notice placed by the +copyright holder saying it can be distributed under the terms of this License. The +“Document”, below, refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. +</para> +<para>A “Modified Version” of the Document means any work containing the Document or a +portion of it, either copied verbatim, or with modifications and/or translated into another +language. +</para> +<para>A “Secondary Section” is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors of the Document to +the Document’s overall subject (or to related matters) and contains nothing that could +fall directly within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any mathematics.) The +relationship could be a matter of historical connection with the subject or with related +matters, or of legal, commercial, philosophical, ethical or political position regarding +them. +</para> +<para>The “Invariant Sections” are certain Secondary Sections whose titles are designated, as +being those of Invariant Sections, in the notice that says that the Document is released under +this License. +</para> +<para>The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts +or Back-Cover Texts, in the notice that says that the Document is released under this +License. +</para> +<para>A “Transparent” copy of the Document means a machine-readable copy, represented in a +format whose specification is available to the general public, whose contents can be viewed +and edited directly and straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available drawing editor, and +that is suitable for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise Transparent +file format whose markup has been designed to thwart or discourage subsequent +modification by readers is not Transparent. A copy that is not “Transparent” is called +“Opaque”. +</para> +<para>Examples of suitable formats for Transparent copies include plain ASCII without markup, +Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, +and standard-conforming simple HTML designed for human modification. Opaque formats +include PostScript, PDF, proprietary formats that can be read and edited only by proprietary +word processors, SGML or XML for which the DTD and/or processing tools are not +generally available, and the machine-generated HTML produced by some word processors +for output purposes only. +</para> +<para>The “Title Page” means, for a printed book, the title page itself, plus such following pages +as are needed to hold, legibly, the material this License requires to appear in the title page. +For works in formats which do not have any title page as such, “Title Page” means the text +near the most prominent appearance of the work’s title, preceding the beginning of the body +of the text. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.2</abbrev>Verbatim Copying</title> +<para>You may copy and distribute the Document in any medium, either commercially or +noncommercially, provided that this License, the copyright notices, and the license notice +saying this License applies to the Document are reproduced in all copies, and that you add no +other conditions whatsoever to those of this License. You may not use technical measures to +obstruct or control the reading or further copying of the copies you make or distribute. +However, you may accept compensation in exchange for copies. If you distribute +a large enough number of copies you must also follow the conditions in section +3. +</para> +<para>You may also lend copies, under the same conditions stated above, and you may publicly +display copies. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.3</abbrev>Copying in Quantity</title> +<para>If you publish printed copies of the Document numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the copies in covers that +carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and +Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you +as the publisher of these copies. The front cover must present the full title with all words of +the title equally prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title of the +Document and satisfy these conditions, can be treated as verbatim copying in other +respects. +</para> +<para>If the required texts for either cover are too voluminous to fit legibly, you should put the +first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto +adjacent pages. +</para> +<para>If you publish or distribute Opaque copies of the Document numbering more than 100, +you must either include a machine-readable Transparent copy along with each Opaque copy, +or state in or with each Opaque copy a publicly-accessible computer-network location +containing a complete Transparent copy of the Document, free of added material, +which the general network-using public has access to download anonymously at +no charge using public-standard network protocols. If you use the latter option, +you must take reasonably prudent steps, when you begin distribution of Opaque +copies in quantity, to ensure that this Transparent copy will remain thus accessible +at the stated location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that edition to the +public. +</para> +<para>It is requested, but not required, that you contact the authors of the Document well before +redistributing any large number of copies, to give them a chance to provide you with an +updated version of the Document. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.4</abbrev>Modifications</title> +<para>You may copy and distribute a Modified Version of the Document under the conditions of +sections 2 and 3 above, provided that you release the Modified Version under precisely this +License, with the Modified Version filling the role of the Document, thus licensing +distribution and modification of the Modified Version to whoever possesses a copy of it. In +addition, you must do these things in the Modified Version: +</para> + +<itemizedlist> + <listitem> +<para>Use in the Title Page (and on the covers, if any) a title distinct from that of the + Document, and from those of previous versions (which should, if there were any, + be listed in the History section of the Document). You may use the same title as + a previous version if the original publisher of that version gives permission. +</para> +</listitem> + <listitem> +<para>List on the Title Page, as authors, one or more persons or entities responsible for + authorship of the modifications in the Modified Version, together with at least + five of the principal authors of the Document (all of its principal authors, if it has + less than five). +</para> +</listitem> + <listitem> +<para>State on the Title page the name of the publisher of the Modified Version, as the + publisher. +</para> +</listitem> + <listitem> +<para>Preserve all the copyright notices of the Document. +</para> +</listitem> + <listitem> +<para>Add an appropriate copyright notice for your modifications adjacent to the other + copyright notices. +</para> +</listitem> + <listitem> +<para>Include, immediately after the copyright notices, a license notice giving the + public permission to use the Modified Version under the terms of this License, + in the form shown in the Addendum below. +</para> +</listitem> + <listitem> +<para>Preserve in that license notice the full lists of Invariant Sections and required + Cover Texts given in the Document’s license notice. +</para> +</listitem> + <listitem> +<para>Include an unaltered copy of this License. +</para> +</listitem> + <listitem> +<para>Preserve the section entitled “History”, and its title, and add to it an item stating + at least the title, year, new authors, and publisher of the Modified Version as + given on the Title Page. If there is no section entitled “History” in the Document, + create one stating the title, year, authors, and publisher of the Document as given + on its Title Page, then add an item describing the Modified Version as stated in + the previous sentence. +</para> +</listitem> + <listitem> +<para>Preserve the network location, if any, given in the Document for public access + to a Transparent copy of the Document, and likewise the network locations + given in the Document for previous versions it was based on. These may be + placed in the “History” section. You may omit a network location for a work that + was published at least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +</para> +</listitem> + <listitem> +<para>In any section entitled “Acknowledgements” or “Dedications”, preserve the + section’s title, and preserve in the section all the substance and tone of each of + the contributor acknowledgements and/or dedications given therein. +</para> +</listitem> + <listitem> +<para>Preserve all the Invariant Sections of the Document, unaltered in their text and + in their titles. Section numbers or the equivalent are not considered part of the + section titles. +</para> +</listitem> + <listitem> +<para>Delete any section entitled “Endorsements”. Such a section may not be included + in the Modified Version. +</para> +</listitem> + <listitem> +<para>Do not retitle any existing section as “Endorsements” or to conflict in title with + any Invariant Section. +</para> +</listitem></itemizedlist> +<para>If the Modified Version includes new front-matter sections or appendices that qualify as +Secondary Sections and contain no material copied from the Document, you may at your +option designate some or all of these sections as invariant. To do this, add their titles to the list +of Invariant Sections in the Modified Version’s license notice. These titles must be distinct +from any other section titles. +</para> +<para>You may add a section entitled “Endorsements”, provided it contains nothing but +endorsements of your Modified Version by various parties – for example, statements of peer +review or that the text has been approved by an organization as the authoritative definition of +a standard. +</para> +<para>You may add a passage of up to five words as a Front-Cover Text, and a passage of up to +25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. +Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already includes a cover text +for the same cover, previously added by you or by arrangement made by the same +entity you are acting on behalf of, you may not add another; but you may replace +the old one, on explicit permission from the previous publisher that added the old +one. +</para> +<para>The author(s) and publisher(s) of the Document do not by this License give permission to +use their names for publicity for or to assert or imply endorsement of any Modified +Version. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.5</abbrev>Combining Documents</title> +<para>You may combine the Document with other documents released under this License, under +the terms defined in section 4 above for modified versions, provided that you include +in the combination all of the Invariant Sections of all of the original documents, +unmodified, and list them all as Invariant Sections of your combined work in its license +notice. +</para> +<para>The combined work need only contain one copy of this License, and multiple identical +Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections +with the same name but different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original author or publisher of +that section if known, or else a unique number. Make the same adjustment to the +section titles in the list of Invariant Sections in the license notice of the combined +work. +</para> +<para>In the combination, you must combine any sections entitled “History” in the various +original documents, forming one section entitled “History”; likewise combine any sections +entitled “Acknowledgements”, and any sections entitled “Dedications”. You must delete all +sections entitled “Endorsements.” +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.6</abbrev>Collections of Documents</title> +<para>You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the various documents +with a single copy that is included in the collection, provided that you follow the +rules of this License for verbatim copying of each of the documents in all other +respects. +</para> +<para>You may extract a single document from such a collection, and distribute it individually +under this License, provided you insert a copy of this License into the extracted document, +and follow this License in all other respects regarding verbatim copying of that +document. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.7</abbrev>Aggregation With Independent Works</title> +<para>A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, does not as a +whole count as a Modified Version of the Document, provided no compilation copyright is +claimed for the compilation. Such a compilation is called an “aggregate”, and this License +does not apply to the other self-contained works thus compiled with the Document, on +account of their being thus compiled, if they are not themselves derivative works of the +Document. +</para> +<para>If the Cover Text requirement of section 3 is applicable to these copies of the Document, +then if the Document is less than one quarter of the entire aggregate, the Document’s Cover +Texts may be placed on covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.8</abbrev>Translation</title> +<para>Translation is considered a kind of modification, so you may distribute translations of the +Document under the terms of section 4. Replacing Invariant Sections with translations +requires special permission from their copyright holders, but you may include translations of +some or all Invariant Sections in addition to the original versions of these Invariant Sections. +You may include a translation of this License provided that you also include the original +English version of this License. In case of a disagreement between the translation +and the original English version of this License, the original English version will +prevail. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.9</abbrev>Termination</title> +<para>You may not copy, modify, sublicense, or distribute the Document except as expressly +provided for under this License. Any other attempt to copy, modify, sublicense or +distribute the Document is void, and will automatically terminate your rights under this +License. However, parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such parties remain in full +compliance. +</para> + +</section><section +role="section"><title><abbrev role="title-mark">A.10</abbrev>Future Revisions of This License</title> +<para>The Free Software Foundation may publish new, revised versions of the GNU Free +Documentation License from time to time. Such new versions will be similar in spirit to the +present version, but may differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. +</para> +<para>Each version of the License is given a distinguishing version number. If the Document +specifies that a particular numbered version of this License ”or any later version” applies to it, +you have the option of following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the Free Software +Foundation. If the Document does not specify a version number of this License, +you may choose any version ever published (not as a draft) by the Free Software +Foundation. +</para> + +</section><section +role="likesection"><title>ADDENDUM: How to use this License for your documents</title> +<para>To use this License in a document you have written, include a copy of the License in the +document and put the following copyright and license notices just after the title +page: +</para> + +<para>Copyright © YEAR YOUR NAME. Permission is granted to copy, + distribute and/or modify this document under the terms of the GNU Free + Documentation License, Version 1.1 or any later version published by the + Free Software Foundation; with the Invariant Sections being LIST THEIR + TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover + Texts being LIST. A copy of the license is included in the section entitled + “GNU Free Documentation License”. +</para> +<para>If you have no Invariant Sections, write “with no Invariant Sections” instead +of saying which ones are invariant. If you have no Front-Cover Texts, write “no +Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise for Back-Cover +Texts. +</para> +<para>If your document contains nontrivial examples of program code, we recommend releasing +these examples in parallel under your choice of free software license, such as the GNU +General Public License, to permit their use in free software. + +</para> + + +</section></section></section></article> diff --git a/dvb-spec/sgml/dvbapi.sgml b/dvb-spec/sgml/dvbapi.sgml new file mode 100644 index 000000000..e6f5674b8 --- /dev/null +++ b/dvb-spec/sgml/dvbapi.sgml @@ -0,0 +1,97 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "./entities.sgml"> %entities; +<!ENTITY i2c "I<superscript>2</superscript>C"> +]> + +<book id="dvbapi"> +<bookinfo> +<title>LINUX DVB API</title> +<subtitle>Version 3</subtitle> + +<authorgroup><author> +<firstname>Ralph</firstname> +<surname>Metzler</surname> +<othername role="mi">J. K.</othername> +<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> +</author> +<author> +<firstname>Marcus</firstname> +<surname>Metzler</surname> +<othername role="mi">O. C.</othername> +<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> +</author> +<author> +<firstname>Mauro</firstname> +<surname>Chehab</surname> +<othername role="mi">Carvalho</othername> +<affiliation><address><email>mchehab@infradead.org</email></address></affiliation> +</author> +</authorgroup> + +<copyright> +<year>2002</year> +<year>2003</year> +<year>2009</year> +<holder>Convergence GmbH</holder> +</copyright> + +<legalnotice> +<para>Permission is granted to copy, distribute and/or modify +this document under the terms of the GNU Free Documentation License, +Version 1.1 or any later version published by the Free Software +Foundation. A copy of the license is included in the chapter entitled +"GNU Free Documentation License"</para> +</legalnotice> + +<revhistory> +<!-- Put document revisions here, newest first. --> +<revision> +<revnumber>2.0.0</revnumber> +<date>2009-09-06</date> +<authorinitials>mcc</authorinitials> +<revremark>Conversion from LaTex to DocBook XML. The +contents is the same as the original LaTex version.</revremark> +</revision> +<revision> +<revnumber>1.0.0</revnumber> +<date>2003-07-24</date> +<authorinitials>rjkm</authorinitials> +<revremark>Initial revision on LaTEX.</revremark> +</revision> +</revhistory> + +</bookinfo> + +<toc></toc> <!-- autogenerated --> + +<!-- ADD THE CHAPTERS HERE --> + <chapter id="introdution"> + &sub-intro; + </chapter> + <chapter id="frontend"> + &sub-frontend; + </chapter> +<!-- + <chapter id="devices"> +Should be broken into: +\input{demux.tex} +\input{video.tex} +\input{audio.tex} +\input{ca.tex} +\input{net.tex} +\input{kdapi.tex} + + &sub-devices; + </chapter> + <chapter id="examples"> + &sub-examples; + </chapter> + <chapter id="fdl"> + &sub-fdl; + </chapter> +--> +<!-- END OF CHAPTERS --> + +</book> diff --git a/dvb-spec/sgml/dvbstb.pdf b/dvb-spec/sgml/dvbstb.pdf Binary files differnew file mode 100644 index 000000000..5a4eff6cb --- /dev/null +++ b/dvb-spec/sgml/dvbstb.pdf diff --git a/dvb-spec/sgml/dvbstb.png b/dvb-spec/sgml/dvbstb.png Binary files differnew file mode 100644 index 000000000..9b8f372e7 --- /dev/null +++ b/dvb-spec/sgml/dvbstb.png diff --git a/dvb-spec/sgml/examples.sgml b/dvb-spec/sgml/examples.sgml new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/dvb-spec/sgml/examples.sgml diff --git a/dvb-spec/sgml/fdl.sgml b/dvb-spec/sgml/fdl.sgml new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/dvb-spec/sgml/fdl.sgml diff --git a/dvb-spec/sgml/frontend.sgml b/dvb-spec/sgml/frontend.sgml new file mode 100644 index 000000000..d2a6ece04 --- /dev/null +++ b/dvb-spec/sgml/frontend.sgml @@ -0,0 +1,1816 @@ +<title>DVB Frontend API</title> + +<para>The DVB frontend device controls the tuner and DVB demodulator +hardware. It can be accessed through <emphasis +role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and +ioctl definitions can be accessed by including <emphasis +role="tt">linux/dvb/frontend.h</emphasis> in your application.</para> + +<para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C +(cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP) +is not yet handled by this API but a future extension is possible. For +DVB-S the frontend device also supports satellite equipment control +(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) +specification is available from Eutelsat <emphasis +role="tt">http://www.eutelsat.org/</emphasis>.</para> + +<para>Note that the DVB API may also be used for MPEG decoder-only PCI +cards, in which case there exists no frontend device.</para> + +<section id="frontend_types"> +<title>Frontend Data Types</title> + +<section id="frontend_type"> +<title>frontend type</title> + +<para>For historical reasons frontend types are named after the type of modulation used in +transmission.</para> +<programlisting> + typedef enum fe_type { + FE_QPSK, /⋆ DVB-S ⋆/ + FE_QAM, /⋆ DVB-C ⋆/ + FE_OFDM /⋆ DVB-T ⋆/ + } fe_type_t; +</programlisting> + +</section> + +<section id="frontend_caps"> +<title>frontend capabilities</title> + +<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for +a specific frontend type.</para> +<programlisting> + typedef enum fe_caps { + FE_IS_STUPID = 0, + FE_CAN_INVERSION_AUTO = 0x1, + FE_CAN_FEC_1_2 = 0x2, + FE_CAN_FEC_2_3 = 0x4, + FE_CAN_FEC_3_4 = 0x8, + FE_CAN_FEC_4_5 = 0x10, + FE_CAN_FEC_5_6 = 0x20, + FE_CAN_FEC_6_7 = 0x40, + FE_CAN_FEC_7_8 = 0x80, + FE_CAN_FEC_8_9 = 0x100, + FE_CAN_FEC_AUTO = 0x200, + FE_CAN_QPSK = 0x400, + FE_CAN_QAM_16 = 0x800, + FE_CAN_QAM_32 = 0x1000, + FE_CAN_QAM_64 = 0x2000, + FE_CAN_QAM_128 = 0x4000, + FE_CAN_QAM_256 = 0x8000, + FE_CAN_QAM_AUTO = 0x10000, + FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, + FE_CAN_BANDWIDTH_AUTO = 0x40000, + FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, + FE_CAN_HIERARCHY_AUTO = 0x100000, + FE_CAN_MUTE_TS = 0x80000000, + FE_CAN_CLEAN_SETUP = 0x40000000 + } fe_caps_t; +</programlisting> +</section> + +<section id="frontend_info"> +<title>frontend information</title> + +<para>Information about the frontend ca be queried with FE_GET_INFO.</para> + +<programlisting> + struct dvb_frontend_info { + char name[128]; + fe_type_t type; + uint32_t frequency_min; + uint32_t frequency_max; + uint32_t frequency_stepsize; + uint32_t frequency_tolerance; + uint32_t symbol_rate_min; + uint32_t symbol_rate_max; + uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ + uint32_t notifier_delay; /⋆ ms ⋆/ + fe_caps_t caps; + }; +</programlisting> +</section> + +<section id="frontend_diseqc"> +<title>diseqc master command</title> + +<para>A message sent from the frontend to DiSEqC capable equipment.</para> +<programlisting> + struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ + }; +</programlisting> +</section> +<section role="subsection"> +<title>diseqc slave reply</title> + +<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para> +<programlisting> + struct dvb_diseqc_slave_reply { + uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ + uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ + int timeout; /⋆ return from ioctl after timeout ms with ⋆/ + }; /⋆ errorcode when no message was received ⋆/ +</programlisting> +</section> + +<section id="frontend_diseqc_slave_reply"> +<title>diseqc slave reply</title> +<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation +(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched +consistently to the DiSEqC commands as described in the DiSEqC spec.</para> +<programlisting> + typedef enum fe_sec_voltage { + SEC_VOLTAGE_13, + SEC_VOLTAGE_18 + } fe_sec_voltage_t; +</programlisting> +</section> + +<section id="frontend_sec_tone"> +<title>SEC continuous tone</title> + +<para>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the +high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to +be switched consistently to the DiSEqC commands as described in the DiSEqC +spec.</para> +<programlisting> + typedef enum fe_sec_tone_mode { + SEC_TONE_ON, + SEC_TONE_OFF + } fe_sec_tone_mode_t; +</programlisting> +</section> + +<section id="frontend_sec_burst"> +<title>SEC tone burst</title> + +<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select +between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to +be switched consistently to the DiSEqC commands as described in the DiSEqC +spec.</para> +<programlisting> + typedef enum fe_sec_mini_cmd { + SEC_MINI_A, + SEC_MINI_B + } fe_sec_mini_cmd_t; +</programlisting> + +<para></para> +</section> + +<section id="frontend_status"> +<title>frontend status</title> +<para>Several functions of the frontend device use the fe_status data type defined +by</para> +<programlisting> + typedef enum fe_status { + FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ + FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ + FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ + FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ + FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ + FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ + FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ + } fe_status_t; /⋆ application is recommned to reset ⋆/ +</programlisting> +<para>to indicate the current state and/or state changes of the frontend hardware. +</para> + +</section> + +<section id="frontend_params"> +<title>frontend parameters</title> +<para>The kind of parameters passed to the frontend device for tuning depend on +the kind of hardware you are using. All kinds of parameters are combined as an +union in the FrontendParameters structure:</para> +<programlisting> + struct dvb_frontend_parameters { + uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ + /⋆ intermediate frequency in kHz for QPSK ⋆/ + fe_spectral_inversion_t inversion; + union { + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; + } u; + }; +</programlisting> +<para>For satellite QPSK frontends you have to use the <constant>QPSKParameters</constant> member defined by</para> +<programlisting> + struct dvb_qpsk_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + }; +</programlisting> +<para>for cable QAM frontend you use the <constant>QAMParameters</constant> structure</para> +<programlisting> + struct dvb_qam_parameters { + uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ + fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ + fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ + }; +</programlisting> +<para>DVB-T frontends are supported by the <constant>OFDMParamters</constant> structure +</para> +<programlisting> + struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ + fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ + fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; + }; +</programlisting> +<para>In the case of QPSK frontends the <constant>Frequency</constant> field specifies the intermediate +frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of +the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and +OFDM frontends the Frequency specifies the absolute frequency and is given in +Hz. +</para> +<para>The Inversion field can take one of these values: +</para> +<programlisting> + typedef enum fe_spectral_inversion { + INVERSION_OFF, + INVERSION_ON, + INVERSION_AUTO + } fe_spectral_inversion_t; +</programlisting> +<para>It indicates if spectral inversion should be presumed or not. In the automatic setting +(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by +itself. +</para> +<para>The possible values for the <constant>FEC_inner</constant> field are +</para> +<programlisting> + typedef enum fe_code_rate { + FEC_NONE = 0, + FEC_1_2, + FEC_2_3, + FEC_3_4, + FEC_4_5, + FEC_5_6, + FEC_6_7, + FEC_7_8, + FEC_8_9, + FEC_AUTO + } fe_code_rate_t; +</programlisting> +<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto +detection. +</para> +<para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature +modulation mode which can be one of the following: +</para> +<programlisting> + typedef enum fe_modulation { + QPSK, + QAM_16, + QAM_32, + QAM_64, + QAM_128, + QAM_256, + QAM_AUTO + } fe_modulation_t; +</programlisting> +<para>Finally, there are several more parameters for OFDM: +</para> +<programlisting> + typedef enum fe_transmit_mode { + TRANSMISSION_MODE_2K, + TRANSMISSION_MODE_8K, + TRANSMISSION_MODE_AUTO + } fe_transmit_mode_t; +</programlisting> + <programlisting> + typedef enum fe_bandwidth { + BANDWIDTH_8_MHZ, + BANDWIDTH_7_MHZ, + BANDWIDTH_6_MHZ, + BANDWIDTH_AUTO + } fe_bandwidth_t; +</programlisting> + <programlisting> + typedef enum fe_guard_interval { + GUARD_INTERVAL_1_32, + GUARD_INTERVAL_1_16, + GUARD_INTERVAL_1_8, + GUARD_INTERVAL_1_4, + GUARD_INTERVAL_AUTO + } fe_guard_interval_t; +</programlisting> + <programlisting> + typedef enum fe_hierarchy { + HIERARCHY_NONE, + HIERARCHY_1, + HIERARCHY_2, + HIERARCHY_4, + HIERARCHY_AUTO + } fe_hierarchy_t; +</programlisting> + +</section> + +<section id="frontend_events"> +<title>frontend events</title> + <programlisting> + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; +</programlisting> + </section> +</section> + + +<section id="frontend_fcalls"> +<title>Frontend Function Calls</title> + +<section id="frontend_f_open"> +<title>open()</title> +<para>DESCRIPTION</para> +<informaltable><tgroup cols="1"><tbody><row> +<entry align="char"> +<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) + for subsequent use. Usually the first thing to do after a successful open is to + find out the frontend type with FE_GET_INFO.</para> +<para>The device can be opened in read-only mode, which only allows monitoring of + device status and statistics, or read/write mode, which allows any kind of use + (e.g. performing tuning operations.) +</para> +<para>In a system with multiple front-ends, it is usually the case that multiple devices + cannot be open in read/write mode simultaneously. As long as a front-end + device is opened in read/write mode, other open() calls in read/write mode will + either fail or block, depending on whether non-blocking or blocking mode was + specified. A front-end device opened in blocking mode can later be put into + non-blocking mode (and vice versa) using the F_SETFL command of the fcntl + system call. This is a standard system call, documented in the Linux manual + page for fcntl. When an open() call has succeeded, the device will be ready + for use in the specified mode. This implies that the corresponding hardware is + powered up, and that other front-ends may have been powered down to make + that possible.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific video device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_f_close"> +<title>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened front-end device. After closing + a front-end device, its corresponding hardware might be powered down + automatically.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_read_status"> +<title>FE_READ_STATUS</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns status information about the front-end. This call only + requires read-only access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_READ_STATUS, + fe_status_t ⋆status);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> + +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_STATUS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct fe_status_t + *status</para> +</entry><entry + align="char"> +<para>Points to the location where the front-end status word is + to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_read_ber"> +<title>FE_READ_BER</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the bit error rate for the signal currently + received/demodulated by the front-end. For this command, read-only access to + the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_READ_BER, + uint32_t ⋆ber);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_BER for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>uint32_t *ber</para> +</entry><entry + align="char"> +<para>The bit error rate is stored into *ber.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ber points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSIGNAL</para> +</entry><entry + align="char"> +<para>There is no signal, thus no meaningful bit error rate. Also + returned if the front-end is not turned on.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_read_snr"> +<title>FE_READ_SNR</title> + +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the signal-to-noise ratio for the signal currently received + by the front-end. For this command, read-only access to the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_READ_SNR, int16_t + ⋆snr);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_SNR for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int16_t *snr</para> +</entry><entry + align="char"> +<para>The signal-to-noise ratio is stored into *snr.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>snr points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSIGNAL</para> +</entry><entry + align="char"> +<para>There is no signal, thus no meaningful signal strength + value. Also returned if front-end is not turned on.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_read_signal_strength"> +<title>FE_READ_SIGNAL_STRENGTH</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the signal strength value for the signal currently received + by the front-end. For this command, read-only access to the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = + FE_READ_SIGNAL_STRENGTH, int16_t ⋆strength);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_SIGNAL_STRENGTH for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>int16_t *strength</para> +</entry><entry + align="char"> +<para>The signal strength value is stored into *strength.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSIGNAL</para> +</entry><entry + align="char"> +<para>There is no signal, thus no meaningful signal strength + value. Also returned if front-end is not turned on.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_read_ub"> +<title>FE_READ_UNCORRECTED_BLOCKS</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the number of uncorrected blocks detected by the device + driver during its lifetime. For meaningful measurements, the increment in block + count during a specific time interval should be calculated. For this command, + read-only access to the device is sufficient.</para> +</entry> + </row><row><entry + align="char"> +<para>Note that the counter will wrap to zero after its maximum count has been + reached.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = + FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_READ_UNCORRECTED_BLOCKS for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>uint32_t *ublocks</para> +</entry><entry + align="char"> +<para>The total number of uncorrected blocks seen by the driver + so far.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ublocks points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOSYS</para> +</entry><entry + align="char"> +<para>Function not available for this device.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_set_fe"> +<title>FE_SET_FRONTEND</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call starts a tuning operation using specified parameters. The result + of this call will be successful if the parameters were valid and the tuning could + be initiated. The result of the tuning operation in itself, however, will arrive + asynchronously as an event (see documentation for FE_GET_EVENT and + FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before + the previous one was completed, the previous operation will be aborted in favor + of the new one. This command requires read/write access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_SET_FRONTEND, + struct dvb_frontend_parameters ⋆p);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_FRONTEND for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_parameters + *p</para> +</entry><entry + align="char"> +<para>Points to parameters for tuning operation.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>p points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Maximum supported symbol rate reached.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_get_fe"> +<title>FE_GET_FRONTEND</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call queries the currently effective frontend parameters. For this + command, read-only access to the device is sufficient.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_GET_FRONTEND, + struct dvb_frontend_parameters ⋆p);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_FRONTEND for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_parameters + *p</para> +</entry><entry + align="char"> +<para>Points to parameters for tuning operation.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> + +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>p points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Maximum supported symbol rate reached.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> + +<section id="frontend_get_event"> +<title>FE_GET_EVENT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns a frontend event if available. If an event is not + available, the behavior depends on whether the device is in blocking or + non-blocking mode. In the latter case, the call fails immediately with errno + set to EWOULDBLOCK. In the former case, the call blocks until an event + becomes available.</para> +</entry> + </row><row><entry + align="char"> +<para>The standard Linux poll() and/or select() system calls can be used with the + device file descriptor to watch for new events. For select(), the file descriptor + should be included in the exceptfds argument, and for poll(), POLLPRI should + be specified as the wake-up condition. Since the event queue allocated is + rather small (room for 8 events), the queue must be serviced regularly to avoid + overflow. If an overflow happens, the oldest event is discarded from the queue, + and an error (EOVERFLOW) occurs the next time the queue is read. After + reporting the error condition in this fashion, subsequent FE_GET_EVENT + calls will return events from the queue as usual.</para> +</entry> + </row><row><entry + align="char"> +<para>For the sake of implementation simplicity, this command requires read/write + access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = QPSK_GET_EVENT, + struct dvb_frontend_event ⋆ev);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_GET_EVENT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_event + *ev</para> +</entry><entry + align="char"> +<para>Points to the location where the event,</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>if any, is to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ev points to invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>There is no event pending, and the device is in + non-blocking mode.</para> +</entry> + </row><row><entry + align="char"> +<para>EOVERFLOW</para> +</entry><entry + align="char"> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>Overflow in event queue - one or more events were lost.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_get_info"> +<title>FE_GET_INFO</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns information about the front-end. This call only requires + read-only access to the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> + +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(int fd, int request = FE_GET_INFO, struct + dvb_frontend_info ⋆info);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> + +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_GET_INFO for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_frontend_info + *info</para> +</entry><entry + align="char"> +<para>Points to the location where the front-end information is + to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>info points to invalid address.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_diseqc_reset_overload"> +<title>FE_DISEQC_RESET_OVERLOAD</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>If the bus has been automatically powered off due to power overload, this ioctl + call restores the power to the bus. The call requires read/write access to the + device. This call has no effect if the device is manually powered off. Not all + DVB adapters support this ioctl.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_RESET_OVERLOAD);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_RESET_OVERLOAD for this + command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_diseqc_send_master_cmd"> +<title>FE_DISEQC_SEND_MASTER_CMD</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to send a a DiSEqC command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_SEND_MASTER_CMD, struct + dvb_diseqc_master_cmd ⋆cmd);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_SEND_MASTER_CMD for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_diseqc_master_cmd + *cmd</para> +</entry><entry + align="char"> +<para>Pointer to the command to be transmitted.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>Seq points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>The data structure referred to by seq is invalid in some + way.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_diseqc_recv_slave_reply"> +<title>FE_DISEQC_RECV_SLAVE_REPLY</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_RECV_SLAVE_REPLY, struct + dvb_diseqc_slave_reply ⋆reply);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_RECV_SLAVE_REPLY for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dvb_diseqc_slave_reply + *reply</para> +</entry><entry + align="char"> +<para>Pointer to the command to be received.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>Seq points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>The data structure referred to by seq is invalid in some + way.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_diseqc_send_burst"> +<title>FE_DISEQC_SEND_BURST</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to send a 22KHz tone burst.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_DISEQC_SEND_BURST, fe_sec_mini_cmd_t burst);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_DISEQC_SEND_BURST for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>fe_sec_mini_cmd_t + burst</para> +</entry><entry + align="char"> +<para>burst A or B.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>Seq points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>The data structure referred to by seq is invalid in some + way.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Permission denied (needs read/write access).</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_set_tone"> +<title>FE_SET_TONE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This call is used to set the generation of the continuous 22kHz tone. This call + requires read/write permissions.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_SET_TONE, + fe_sec_tone_mode_t tone);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_TONE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>fe_sec_tone_mode_t + tone</para> +</entry><entry + align="char"> +<para>The requested tone generation mode (on/off).</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>File not opened with read permissions.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="fe_set_voltage"> +<title>FE_SET_VOLTAGE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This call is used to set the bus voltage. This call requires read/write + permissions.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = FE_SET_VOLTAGE, + fe_sec_voltage_t voltage);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_VOLTAGE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>fe_sec_voltage_t + voltage</para> +</entry><entry + align="char"> +<para>The requested bus voltage.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>File not opened with read permissions.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="frontend_enable_high_lnb_volt"> +<title>FE_ENABLE_HIGH_LNB_VOLTAGE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate + for long cables). This call requires read/write permissions. Not all DVB + adapters support this ioctl.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + FE_ENABLE_HIGH_LNB_VOLTAGE, int high);</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals FE_SET_VOLTAGE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int high</para> +</entry><entry + align="char"> +<para>The requested bus voltage.</para> +</entry> + </row><row><entry + align="char"> +</entry> + </row></tbody></tgroup></informaltable> + +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>File not opened with read permissions.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error in the device driver.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> +</section> diff --git a/dvb-spec/sgml/intro.sgml b/dvb-spec/sgml/intro.sgml new file mode 100644 index 000000000..37d1c5055 --- /dev/null +++ b/dvb-spec/sgml/intro.sgml @@ -0,0 +1,191 @@ +<title>Introduction</title> + +<section id="requisites"> +<title>What you need to know</title> + +<para>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.</para> + +<para>Various DVB standards documents are available from +<emphasis role="tt">http://www.dvb.org/</emphasis> and/or +<emphasis role="tt">http://www.etsi.org/</emphasis>.</para> + +<para>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++. +</para> +</section> + +<section id="history"> +<title>History</title> + +<para>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. +</para> + +<para>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 <emphasis +role="tt">http://www.linuxtv.org/</emphasis> 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.</para> +</section> + +<section id="overview"> +<title>Overview</title> + + <figure id="stb_components"> + <title>Components of a DVB card/STB</title> + <mediaobject> + <imageobject> + <imagedata fileref="dvbstb.pdf" format="PS" /> + </imageobject> + <imageobject> + <imagedata fileref="dvbstb.png" format="PNG" /> + </imageobject> + </mediaobject> + </figure> + +<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the +following main hardware components: </para> + +<itemizedlist> + <listitem> + +<para>Frontend consisting of tuner and DVB demodulator</para> + +<para>Here the raw signal reaches the DVB hardware from a satellite dish +or antenna or directly from cable. The frontend down-converts and +demodulates this signal into an MPEG transport stream (TS). In case of a +satellite frontend, this includes a facility for satellite equipment +control (SEC), which allows control of LNB polarization, multi feed +switches or dish rotors.</para> + +</listitem> + <listitem> + +<para>Conditional Access (CA) hardware like CI adapters and smartcard slots +</para> + +<para>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.</para> + +</listitem> + <listitem> + <para>Demultiplexer which filters the incoming DVB stream</para> + +<para>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.</para> + +</listitem> +<listitem> + +<para>MPEG2 audio and video decoder</para> + +<para>The main targets of the demultiplexer are the MPEG2 audio and +video decoders. After decoding they pass on the uncompressed audio and +video to the computer screen or (through a PAL/NTSC encoder) to a TV +set.</para> + + +</listitem> +</itemizedlist> + +<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow +between those components.</para> + +<para>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.</para> + +</section> + +<section id="dvb_devices"> +<title>Linux DVB Devices</title> + +<para>The Linux DVB API lets you control these hardware components +through currently six Unix-style character devices for video, audio, +frontend, demux, CA and IP-over-DVB networking. The video and audio +devices control the MPEG2 decoder hardware, the frontend device the +tuner and the DVB demodulator. The demux device gives you control over +the PES and section filters of the hardware. If the hardware does not +support filtering these filters can be implemented in software. Finally, +the CA device controls all the conditional access capabilities of the +hardware. It can depend on the individual security requirements of the +platform, if and how many of the CA functions are made available to the +application through this device.</para> + +<para>All devices can be found in the <emphasis role="tt">/dev</emphasis> +tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices +are called:</para> + +<itemizedlist> +<listitem> + +<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para> +</listitem> +<listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para> +</listitem> +<listitem> +<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para> +</listitem> + <listitem> + +<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para> +</listitem> + <listitem> + +<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para> +</listitem> + <listitem> + +<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> + +<para>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 “<emphasis +role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion +of these devices. The naming scheme for the devices is the same wheter +devfs is used or not.</para> + +<para>More details about the data structures and function calls of all +the devices are described in the following chapters.</para> + +</section> + +<section id="include_files"> +<title>API include files</title> + +<para>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:</para> + + +<programlisting> + #include <linux/dvb/frontend.h> +</programlisting> + +<para>To enable applications to support different API version, an +additional include file <emphasis +role="tt">linux/dvb/version.h</emphasis> exists, which defines the +constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document +describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>. +</para> + +</section> + |