diff options
| author |   José Pekkarinen <jose.pekkarinen@nokia.com> | 2016-04-11 10:41:07 +0300 |
|---|---|---|
| committer | José Pekkarinen <jose.pekkarinen@nokia.com> | 2016-04-13 08:17:18 +0300 |
| commit | e09b41010ba33a20a87472ee821fa407a5b8da36 (patch) | |
| tree | d10dc367189862e7ca5c592f033dc3726e1df4e3 /kernel/Documentation/DocBook/media/dvb | |
| parent | f93b97fd65072de626c074dbe099a1fff05ce060 (diff) | |
These changes are the raw update to linux-4.4.6-rt14. Kernel sources
are taken from kernel.org, and rt patch from the rt wiki download page.
During the rebasing, the following patch collided:
Force tick interrupt and get rid of softirq magic(I70131fb85).
Collisions have been removed because its logic was found on the
source already.
Change-Id: I7f57a4081d9deaa0d9ccfc41a6c8daccdee3b769
Signed-off-by: José Pekkarinen <jose.pekkarinen@nokia.com>
Diffstat (limited to 'kernel/Documentation/DocBook/media/dvb')
23 files changed, 2979 insertions, 4406 deletions
diff --git a/kernel/Documentation/DocBook/media/dvb/audio.xml b/kernel/Documentation/DocBook/media/dvb/audio.xml index a7ea56c71..ea56743dd 100644 --- a/kernel/Documentation/DocBook/media/dvb/audio.xml +++ b/kernel/Documentation/DocBook/media/dvb/audio.xml @@ -1,7 +1,7 @@ <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/audio.h</emphasis> in your +can be accessed through <constant>/dev/dvb/adapter?/audio?</constant>. Data types and and +ioctl definitions can be accessed by including <constant>linux/dvb/audio.h</constant> in your application. </para> <para>Please note that some DVB cards don’t have their own MPEG decoder, which results in @@ -32,7 +32,7 @@ typedef enum { </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 +is selected the stream comes from the application through the <constant>write()</constant> system call. </para> diff --git a/kernel/Documentation/DocBook/media/dvb/ca.xml b/kernel/Documentation/DocBook/media/dvb/ca.xml index 85eaf4fe2..d0b07e763 100644 --- a/kernel/Documentation/DocBook/media/dvb/ca.xml +++ b/kernel/Documentation/DocBook/media/dvb/ca.xml @@ -1,7 +1,7 @@ <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. +<constant>/dev/dvb/adapter?/ca?</constant>. Data types and and ioctl definitions can be accessed by +including <constant>linux/dvb/ca.h</constant> in your application. </para> <section id="ca_data_types"> diff --git a/kernel/Documentation/DocBook/media/dvb/demux.xml b/kernel/Documentation/DocBook/media/dvb/demux.xml index c8683d66f..34f2fb1cd 100644 --- a/kernel/Documentation/DocBook/media/dvb/demux.xml +++ b/kernel/Documentation/DocBook/media/dvb/demux.xml @@ -1,33 +1,50 @@ <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. +accessed through <constant>/dev/adapter?/demux?</constant>. Data types and and ioctl definitions can be +accessed by including <constant>linux/dvb/dmx.h</constant> in your application. </para> <section id="dmx_types"> <title>Demux Data Types</title> <section id="dmx-output-t"> -<title>dmx_output_t</title> -<programlisting> -typedef enum -{ - DMX_OUT_DECODER, /⋆ Streaming directly to decoder. ⋆/ - DMX_OUT_TAP, /⋆ Output going to a memory buffer ⋆/ - /⋆ (to be retrieved via the read command).⋆/ - DMX_OUT_TS_TAP, /⋆ Output multiplexed into a new TS ⋆/ - /⋆ (to be retrieved by reading from the ⋆/ - /⋆ logical DVR device). ⋆/ - DMX_OUT_TSDEMUX_TAP /⋆ Like TS_TAP but retrieved from the DMX device ⋆/ -} 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> +<title>Output for the demux</title> + +<table pgwide="1" frame="none" id="dmx-output"> + <title>enum dmx_output</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="DMX-OUT-DECODER">DMX_OUT_DECODER</entry> + <entry>Streaming directly to decoder.</entry> + </row><row> + <entry align="char" id="DMX-OUT-TAP">DMX_OUT_TAP</entry> + <entry>Output going to a memory buffer (to be retrieved via the + read command). Delivers the stream output to the demux + device on which the ioctl is called.</entry> + </row><row> + <entry align="char" id="DMX-OUT-TS-TAP">DMX_OUT_TS_TAP</entry> + <entry>Output multiplexed into a new TS (to be retrieved by + reading from the logical DVR device). Routes output to the + logical DVR device <constant>/dev/dvb/adapter?/dvr?</constant>, + which delivers a TS multiplexed from all filters for which + <constant>DMX_OUT_TS_TAP</constant> was specified.</entry> + </row><row> + <entry align="char" id="DMX-OUT-TSDEMUX-TAP">DMX_OUT_TSDEMUX_TAP</entry> + <entry>Like &DMX-OUT-TS-TAP; but retrieved from the DMX + device.</entry> + </row> + </tbody> + </tgroup> +</table> + </section> <section id="dmx-input-t"> diff --git a/kernel/Documentation/DocBook/media/dvb/dvbapi.xml b/kernel/Documentation/DocBook/media/dvb/dvbapi.xml index 4c15396c6..8576481e2 100644 --- a/kernel/Documentation/DocBook/media/dvb/dvbapi.xml +++ b/kernel/Documentation/DocBook/media/dvb/dvbapi.xml @@ -28,13 +28,23 @@ <holder>Convergence GmbH</holder> </copyright> <copyright> - <year>2009-2014</year> + <year>2009-2015</year> <holder>Mauro Carvalho Chehab</holder> </copyright> <revhistory> <!-- Put document revisions here, newest first. --> <revision> + <revnumber>2.1.0</revnumber> + <date>2015-05-29</date> + <authorinitials>mcc</authorinitials> + <revremark> + DocBook improvements and cleanups, in order to document the + system calls on a more standard way and provide more description + about the current DVB API. + </revremark> +</revision> +<revision> <revnumber>2.0.4</revnumber> <date>2011-05-06</date> <authorinitials>mcc</authorinitials> @@ -95,20 +105,25 @@ Added ISDB-T test originally written by Patrick Boettcher <chapter id="dvb_demux"> &sub-demux; </chapter> - <chapter id="dvb_video"> - &sub-video; - </chapter> - <chapter id="dvb_audio"> - &sub-audio; - </chapter> <chapter id="dvb_ca"> &sub-ca; </chapter> - <chapter id="dvb_net"> + <chapter id="net"> &sub-net; </chapter> - <chapter id="dvb_kdapi"> - &sub-kdapi; + <chapter id="legacy_dvb_apis"> + <title>DVB Deprecated APIs</title> + <para>The APIs described here are kept only for historical reasons. There's + just one driver for a very legacy hardware that uses this API. No + modern drivers should use it. Instead, audio and video should be using + the V4L2 and ALSA APIs, and the pipelines should be set using the + Media Controller API</para> + <section id="dvb_video"> + &sub-video; + </section> + <section id="dvb_audio"> + &sub-audio; + </section> </chapter> <chapter id="dvb_examples"> &sub-examples; diff --git a/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml b/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml index 3018564dd..08227d4e9 100644 --- a/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/kernel/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -1,14 +1,88 @@ -<section id="FE_GET_SET_PROPERTY"> -<title><constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></title> -<para>This section describes the DVB version 5 extension of the DVB-API, also -called "S2API", as this API were added to provide support for DVB-S2. It was -designed to be able to replace the old frontend API. Yet, the DISEQC and -the capability ioctls weren't implemented yet via the new way.</para> -<para>The typical usage for the <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant> -API is to replace the ioctl's were the <link linkend="dvb-frontend-parameters"> -struct <constant>dvb_frontend_parameters</constant></link> were used.</para> +<section id="frontend-properties"> +<title>DVB Frontend properties</title> +<para>Tuning into a Digital TV physical channel and starting decoding it + requires changing a set of parameters, in order to control the + tuner, the demodulator, the Linear Low-noise Amplifier (LNA) and to set the + antenna subsystem via Satellite Equipment Control (SEC), on satellite + systems. The actual parameters are specific to each particular digital + TV standards, and may change as the digital TV specs evolves.</para> +<para>In the past, the strategy used was to have a union with the parameters + needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped + there. The problem is that, as the second generation standards appeared, + those structs were not big enough to contain the additional parameters. + Also, the union didn't have any space left to be expanded without breaking + userspace. So, the decision was to deprecate the legacy union/struct based + approach, in favor of a properties set approach.</para> + +<para>NOTE: on Linux DVB API version 3, setting a frontend were done via + <link linkend="dvb-frontend-parameters">struct <constant>dvb_frontend_parameters</constant></link>. + This got replaced on version 5 (also called "S2API", as this API were + added originally_enabled to provide support for DVB-S2), because the old + API has a very limited support to new standards and new hardware. This + section describes the new and recommended way to set the frontend, with + suppports all digital TV delivery systems.</para> + +<para>Example: with the properties based approach, in order to set the tuner + to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol + rate of 5.217 Mbauds, those properties should be sent to + <link linkend="FE_GET_PROPERTY"><constant>FE_SET_PROPERTY</constant></link> ioctl:</para> + <itemizedlist> + <listitem><para>&DTV-DELIVERY-SYSTEM; = SYS_DVBC_ANNEX_A</para></listitem> + <listitem><para>&DTV-FREQUENCY; = 651000000</para></listitem> + <listitem><para>&DTV-MODULATION; = QAM_256</para></listitem> + <listitem><para>&DTV-INVERSION; = INVERSION_AUTO</para></listitem> + <listitem><para>&DTV-SYMBOL-RATE; = 5217000</para></listitem> + <listitem><para>&DTV-INNER-FEC; = FEC_3_4</para></listitem> + <listitem><para>&DTV-TUNE;</para></listitem> + </itemizedlist> + +<para>The code that would do the above is:</para> +<programlisting> +#include <stdio.h> +#include <fcntl.h> +#include <sys/ioctl.h> +#include <linux/dvb/frontend.h> + +static struct dtv_property props[] = { + { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, + { .cmd = DTV_FREQUENCY, .u.data = 651000000 }, + { .cmd = DTV_MODULATION, .u.data = QAM_256 }, + { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, + { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, + { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, + { .cmd = DTV_TUNE } +}; + +static struct dtv_properties dtv_prop = { + .num = 6, .props = props +}; + +int main(void) +{ + int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); + + if (!fd) { + perror ("open"); + return -1; + } + if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { + perror("ioctl"); + return -1; + } + printf("Frontend set\n"); + return 0; +} +</programlisting> + +<para>NOTE: While it is possible to directly call the Kernel code like the + above example, it is strongly recommended to use + <ulink url="http://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink>, + as it provides abstraction to work with the supported digital TV standards + and provides methods for usual operations like program scanning and to + read/write channel descriptor files.</para> + <section id="dtv-stats"> -<title>DTV stats type</title> +<title>struct <structname>dtv_stats</structname></title> <programlisting> struct dtv_stats { __u8 scale; /* enum fecap_scale_params type */ @@ -20,19 +94,19 @@ struct dtv_stats { </programlisting> </section> <section id="dtv-fe-stats"> -<title>DTV stats type</title> +<title>struct <structname>dtv_fe_stats</structname></title> <programlisting> #define MAX_DTV_STATS 4 struct dtv_fe_stats { __u8 len; - struct dtv_stats stat[MAX_DTV_STATS]; + &dtv-stats; stat[MAX_DTV_STATS]; } __packed; </programlisting> </section> <section id="dtv-property"> -<title>DTV property type</title> +<title>struct <structname>dtv_property</structname></title> <programlisting> /* Reserved fields should be set to 0 */ @@ -41,7 +115,7 @@ struct dtv_property { __u32 reserved[3]; union { __u32 data; - struct dtv_fe_stats st; + &dtv-fe-stats; st; struct { __u8 data[32]; __u32 len; @@ -57,115 +131,19 @@ struct dtv_property { </programlisting> </section> <section id="dtv-properties"> -<title>DTV properties type</title> +<title>struct <structname>dtv_properties</structname></title> <programlisting> struct dtv_properties { __u32 num; - struct dtv_property *props; + &dtv-property; *props; }; </programlisting> </section> -<section id="FE_GET_PROPERTY"> -<title>FE_GET_PROPERTY</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns one or more frontend properties. 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 = <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>, - dtv_properties ⋆props);</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 num</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dtv_property *props</para> -</entry><entry - align="char"> -<para>Points to the location where the front-end property commands are stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row> - <entry align="char"><para>EOPNOTSUPP</para></entry> - <entry align="char"><para>Property type not supported.</para></entry> - </row></tbody></tgroup></informaltable> -</section> - -<section id="FE_SET_PROPERTY"> -<title>FE_SET_PROPERTY</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call sets one or more frontend properties. This call - 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 = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>, - dtv_properties ⋆props);</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 num</para> -</entry><entry - align="char"> -<para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dtv_property *props</para> -</entry><entry - align="char"> -<para>Points to the location where the front-end property commands are stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row> - <entry align="char"><para>EOPNOTSUPP</para></entry> - <entry align="char"><para>Property type not supported.</para></entry> - </row></tbody></tgroup></informaltable> -</section> - <section> <title>Property types</title> <para> -On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>, +On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY and FE_SET_PROPERTY</link>, the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to get/set up to 64 properties. The actual meaning of each property is described on the next sections. </para> @@ -193,7 +171,7 @@ get/set up to 64 properties. The actual meaning of each property is described on <para>Central frequency of the channel.</para> <para>Notes:</para> - <para>1)For satellital delivery systems, it is measured in kHz. + <para>1)For satellite delivery systems, it is measured in kHz. For the other ones, it is measured in Hz.</para> <para>2)For ISDB-T, the channels are usually transmitted with an offset of 143kHz. E.g. a valid frequency could be 474143 kHz. The stepping is bound to the bandwidth of @@ -205,25 +183,78 @@ get/set up to 64 properties. The actual meaning of each property is described on </section> <section id="DTV-MODULATION"> <title><constant>DTV_MODULATION</constant></title> -<para>Specifies the frontend modulation type for cable and satellite types. The modulation can be one of the types bellow:</para> -<programlisting> - typedef enum fe_modulation { - QPSK, - QAM_16, - QAM_32, - QAM_64, - QAM_128, - QAM_256, - QAM_AUTO, - VSB_8, - VSB_16, - PSK_8, - APSK_16, - APSK_32, - DQPSK, - QAM_4_NR, - } fe_modulation_t; -</programlisting> +<para>Specifies the frontend modulation type for delivery systems that supports + more than one modulation type. The modulation can be one of the types + defined by &fe-modulation;.</para> + + +<section id="fe-modulation-t"> +<title>Modulation property</title> + +<para>Most of the digital TV standards currently offers more than one possible + modulation (sometimes called as "constellation" on some standards). This + enum contains the values used by the Kernel. Please note that not all + modulations are supported by a given standard.</para> + +<table pgwide="1" frame="none" id="fe-modulation"> + <title>enum fe_modulation</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="QPSK"><constant>QPSK</constant></entry> + <entry>QPSK modulation</entry> + </row><row> + <entry id="QAM-16"><constant>QAM_16</constant></entry> + <entry>16-QAM modulation</entry> + </row><row> + <entry id="QAM-32"><constant>QAM_32</constant></entry> + <entry>32-QAM modulation</entry> + </row><row> + <entry id="QAM-64"><constant>QAM_64</constant></entry> + <entry>64-QAM modulation</entry> + </row><row> + <entry id="QAM-128"><constant>QAM_128</constant></entry> + <entry>128-QAM modulation</entry> + </row><row> + <entry id="QAM-256"><constant>QAM_256</constant></entry> + <entry>256-QAM modulation</entry> + </row><row> + <entry id="QAM-AUTO"><constant>QAM_AUTO</constant></entry> + <entry>Autodetect QAM modulation</entry> + </row><row> + <entry id="VSB-8"><constant>VSB_8</constant></entry> + <entry>8-VSB modulation</entry> + </row><row> + <entry id="VSB-16"><constant>VSB_16</constant></entry> + <entry>16-VSB modulation</entry> + </row><row> + <entry id="PSK-8"><constant>PSK_8</constant></entry> + <entry>8-PSK modulation</entry> + </row><row> + <entry id="APSK-16"><constant>APSK_16</constant></entry> + <entry>16-APSK modulation</entry> + </row><row> + <entry id="APSK-32"><constant>APSK_32</constant></entry> + <entry>32-APSK modulation</entry> + </row><row> + <entry id="DQPSK"><constant>DQPSK</constant></entry> + <entry>DQPSK modulation</entry> + </row><row> + <entry id="QAM-4-NR"><constant>QAM_4_NR</constant></entry> + <entry>4-QAM-NR modulation</entry> + </row> + </tbody> + </tgroup> +</table> +</section> + </section> <section id="DTV-BANDWIDTH-HZ"> <title><constant>DTV_BANDWIDTH_HZ</constant></title> @@ -253,19 +284,45 @@ get/set up to 64 properties. The actual meaning of each property is described on </section> <section id="DTV-INVERSION"> <title><constant>DTV_INVERSION</constant></title> - <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>Specifies if the frontend should do spectral inversion or not.</para> + +<section id="fe-spectral-inversion-t"> +<title>enum fe_modulation: Frontend spectral inversion</title> + +<para>This parameter 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. If the hardware + doesn't support, the DVB core will try to lock at the carrier first with + inversion off. If it fails, it will try to enable inversion. +</para> + +<table pgwide="1" frame="none" id="fe-spectral-inversion"> + <title>enum fe_modulation</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="INVERSION-OFF"><constant>INVERSION_OFF</constant></entry> + <entry>Don't do spectral band inversion.</entry> + </row><row> + <entry id="INVERSION-ON"><constant>INVERSION_ON</constant></entry> + <entry>Do spectral band inversion.</entry> + </row><row> + <entry id="INVERSION-AUTO"><constant>INVERSION_AUTO</constant></entry> + <entry>Autodetect spectral band inversion.</entry> + </row> + </tbody> + </tgroup> +</table> +</section> + </section> <section id="DTV-DISEQC-MASTER"> <title><constant>DTV_DISEQC_MASTER</constant></title> @@ -279,25 +336,64 @@ get/set up to 64 properties. The actual meaning of each property is described on <title><constant>DTV_INNER_FEC</constant></title> <para>Used cable/satellite transmissions. The acceptable values 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, - FEC_3_5, - FEC_9_10, - FEC_2_5, -} 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> +<section id="fe-code-rate-t"> +<title>enum fe_code_rate: type of the Forward Error Correction.</title> + +<table pgwide="1" frame="none" id="fe-code-rate"> + <title>enum fe_code_rate</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="FEC-NONE"><constant>FEC_NONE</constant></entry> + <entry>No Forward Error Correction Code</entry> + </row><row> + <entry id="FEC-AUTO"><constant>FEC_AUTO</constant></entry> + <entry>Autodetect Error Correction Code</entry> + </row><row> + <entry id="FEC-1-2"><constant>FEC_1_2</constant></entry> + <entry>Forward Error Correction Code 1/2</entry> + </row><row> + <entry id="FEC-2-3"><constant>FEC_2_3</constant></entry> + <entry>Forward Error Correction Code 2/3</entry> + </row><row> + <entry id="FEC-3-4"><constant>FEC_3_4</constant></entry> + <entry>Forward Error Correction Code 3/4</entry> + </row><row> + <entry id="FEC-4-5"><constant>FEC_4_5</constant></entry> + <entry>Forward Error Correction Code 4/5</entry> + </row><row> + <entry id="FEC-5-6"><constant>FEC_5_6</constant></entry> + <entry>Forward Error Correction Code 5/6</entry> + </row><row> + <entry id="FEC-6-7"><constant>FEC_6_7</constant></entry> + <entry>Forward Error Correction Code 6/7</entry> + </row><row> + <entry id="FEC-7-8"><constant>FEC_7_8</constant></entry> + <entry>Forward Error Correction Code 7/8</entry> + </row><row> + <entry id="FEC-8-9"><constant>FEC_8_9</constant></entry> + <entry>Forward Error Correction Code 8/9</entry> + </row><row> + <entry id="FEC-9-10"><constant>FEC_9_10</constant></entry> + <entry>Forward Error Correction Code 9/10</entry> + </row><row> + <entry id="FEC-2-5"><constant>FEC_2_5</constant></entry> + <entry>Forward Error Correction Code 2/5</entry> + </row><row> + <entry id="FEC-3-5"><constant>FEC_3_5</constant></entry> + <entry>Forward Error Correction Code 3/5</entry> + </row> + </tbody> + </tgroup> +</table> +</section> </section> <section id="DTV-VOLTAGE"> <title><constant>DTV_VOLTAGE</constant></title> @@ -305,12 +401,31 @@ typedef enum fe_code_rate { 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> + +<table pgwide="1" frame="none" id="fe-sec-voltage"> + <title id="fe-sec-voltage-t">enum fe_sec_voltage</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="SEC-VOLTAGE-13"><constant>SEC_VOLTAGE_13</constant></entry> + <entry align="char">Set DC voltage level to 13V</entry> + </row><row> + <entry align="char" id="SEC-VOLTAGE-18"><constant>SEC_VOLTAGE_18</constant></entry> + <entry align="char">Set DC voltage level to 18V</entry> + </row><row> + <entry align="char" id="SEC-VOLTAGE-OFF"><constant>SEC_VOLTAGE_OFF</constant></entry> + <entry align="char">Don't send any voltage to the antenna</entry> + </row> + </tbody> + </tgroup> +</table> </section> <section id="DTV-TONE"> <title><constant>DTV_TONE</constant></title> @@ -321,13 +436,30 @@ typedef enum fe_code_rate { <para>Sets DVB-S2 pilot</para> <section id="fe-pilot-t"> <title>fe_pilot type</title> - <programlisting> -typedef enum fe_pilot { - PILOT_ON, - PILOT_OFF, - PILOT_AUTO, -} fe_pilot_t; - </programlisting> +<table pgwide="1" frame="none" id="fe-pilot"> + <title>enum fe_pilot</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="PILOT-ON"><constant>PILOT_ON</constant></entry> + <entry align="char">Pilot tones enabled</entry> + </row><row> + <entry align="char" id="PILOT-OFF"><constant>PILOT_OFF</constant></entry> + <entry align="char">Pilot tones disabled</entry> + </row><row> + <entry align="char" id="PILOT-AUTO"><constant>PILOT_AUTO</constant></entry> + <entry align="char">Autodetect pilot tones</entry> + </row> + </tbody> + </tgroup> +</table> </section> </section> <section id="DTV-ROLLOFF"> @@ -336,14 +468,33 @@ typedef enum fe_pilot { <section id="fe-rolloff-t"> <title>fe_rolloff type</title> - <programlisting> -typedef enum fe_rolloff { - ROLLOFF_35, /* Implied value in DVB-S, default for DVB-S2 */ - ROLLOFF_20, - ROLLOFF_25, - ROLLOFF_AUTO, -} fe_rolloff_t; - </programlisting> +<table pgwide="1" frame="none" id="fe-rolloff"> + <title>enum fe_rolloff</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="ROLLOFF-35"><constant>ROLLOFF_35</constant></entry> + <entry align="char">Roloff factor: α=35%</entry> + </row><row> + <entry align="char" id="ROLLOFF-20"><constant>ROLLOFF_20</constant></entry> + <entry align="char">Roloff factor: α=20%</entry> + </row><row> + <entry align="char" id="ROLLOFF-25"><constant>ROLLOFF_25</constant></entry> + <entry align="char">Roloff factor: α=25%</entry> + </row><row> + <entry align="char" id="ROLLOFF-AUTO"><constant>ROLLOFF_AUTO</constant></entry> + <entry align="char">Auto-detect the roloff factor.</entry> + </row> + </tbody> + </tgroup> +</table> </section> </section> <section id="DTV-DISEQC-SLAVE-REPLY"> @@ -364,31 +515,82 @@ typedef enum fe_rolloff { <section id="fe-delivery-system-t"> <title>fe_delivery_system type</title> <para>Possible values: </para> -<programlisting> -typedef enum fe_delivery_system { - SYS_UNDEFINED, - SYS_DVBC_ANNEX_A, - SYS_DVBC_ANNEX_B, - SYS_DVBT, - SYS_DSS, - SYS_DVBS, - SYS_DVBS2, - SYS_DVBH, - SYS_ISDBT, - SYS_ISDBS, - SYS_ISDBC, - SYS_ATSC, - SYS_ATSCMH, - SYS_DTMB, - SYS_CMMB, - SYS_DAB, - SYS_DVBT2, - SYS_TURBO, - SYS_DVBC_ANNEX_C, -} fe_delivery_system_t; -</programlisting> - </section> +<table pgwide="1" frame="none" id="fe-delivery-system"> + <title>enum fe_delivery_system</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="SYS-UNDEFINED"><constant>SYS_UNDEFINED</constant></entry> + <entry>Undefined standard. Generally, indicates an error</entry> + </row><row> + <entry id="SYS-DVBC-ANNEX-A"><constant>SYS_DVBC_ANNEX_A</constant></entry> + <entry>Cable TV: DVB-C following ITU-T J.83 Annex A spec</entry> + </row><row> + <entry id="SYS-DVBC-ANNEX-B"><constant>SYS_DVBC_ANNEX_B</constant></entry> + <entry>Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM)</entry> + </row><row> + <entry id="SYS-DVBC-ANNEX-C"><constant>SYS_DVBC_ANNEX_C</constant></entry> + <entry>Cable TV: DVB-C following ITU-T J.83 Annex C spec</entry> + </row><row> + <entry id="SYS-ISDBC"><constant>SYS_ISDBC</constant></entry> + <entry>Cable TV: ISDB-C (no drivers yet)</entry> + </row><row> + <entry id="SYS-DVBT"><constant>SYS_DVBT</constant></entry> + <entry>Terrestral TV: DVB-T</entry> + </row><row> + <entry id="SYS-DVBT2"><constant>SYS_DVBT2</constant></entry> + <entry>Terrestral TV: DVB-T2</entry> + </row><row> + <entry id="SYS-ISDBT"><constant>SYS_ISDBT</constant></entry> + <entry>Terrestral TV: ISDB-T</entry> + </row><row> + <entry id="SYS-ATSC"><constant>SYS_ATSC</constant></entry> + <entry>Terrestral TV: ATSC</entry> + </row><row> + <entry id="SYS-ATSCMH"><constant>SYS_ATSCMH</constant></entry> + <entry>Terrestral TV (mobile): ATSC-M/H</entry> + </row><row> + <entry id="SYS-DTMB"><constant>SYS_DTMB</constant></entry> + <entry>Terrestrial TV: DTMB</entry> + </row><row> + <entry id="SYS-DVBS"><constant>SYS_DVBS</constant></entry> + <entry>Satellite TV: DVB-S</entry> + </row><row> + <entry id="SYS-DVBS2"><constant>SYS_DVBS2</constant></entry> + <entry>Satellite TV: DVB-S2</entry> + </row><row> + <entry id="SYS-TURBO"><constant>SYS_TURBO</constant></entry> + <entry>Satellite TV: DVB-S Turbo</entry> + </row><row> + <entry id="SYS-ISDBS"><constant>SYS_ISDBS</constant></entry> + <entry>Satellite TV: ISDB-S</entry> + </row><row> + <entry id="SYS-DAB"><constant>SYS_DAB</constant></entry> + <entry>Digital audio: DAB (not fully supported)</entry> + </row><row> + <entry id="SYS-DSS"><constant>SYS_DSS</constant></entry> + <entry>Satellite TV:"DSS (not fully supported)</entry> + </row><row> + <entry id="SYS-CMMB"><constant>SYS_CMMB</constant></entry> + <entry>Terrestral TV (mobile):CMMB (not fully supported)</entry> + </row><row> + <entry id="SYS-DVBH"><constant>SYS_DVBH</constant></entry> + <entry>Terrestral TV (mobile): DVB-H (standard deprecated)</entry> + </row> + </tbody> + </tgroup> +</table> + + +</section> </section> <section id="DTV-ISDBT-PARTIAL-RECEPTION"> <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title> @@ -630,114 +832,177 @@ typedef enum fe_delivery_system { </section> <section id="DTV-ATSCMH-RS-FRAME-MODE"> <title><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></title> - <para>RS frame mode.</para> + <para>Reed Solomon (RS) frame mode.</para> <para>Possible values are:</para> - <para id="atscmh-rs-frame-mode"> -<programlisting> -typedef enum atscmh_rs_frame_mode { - ATSCMH_RSFRAME_PRI_ONLY = 0, - ATSCMH_RSFRAME_PRI_SEC = 1, -} atscmh_rs_frame_mode_t; -</programlisting> - </para> +<table pgwide="1" frame="none" id="atscmh-rs-frame-mode"> + <title>enum atscmh_rs_frame_mode</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="ATSCMH-RSFRAME-PRI-ONLY"><constant>ATSCMH_RSFRAME_PRI_ONLY</constant></entry> + <entry>Single Frame: There is only a primary RS Frame for all + Group Regions.</entry> + </row><row> + <entry id="ATSCMH-RSFRAME-PRI-SEC"><constant>ATSCMH_RSFRAME_PRI_SEC</constant></entry> + <entry>Dual Frame: There are two separate RS Frames: Primary RS + Frame for Group Region A and B and Secondary RS Frame for Group + Region C and D.</entry> + </row> + </tbody> + </tgroup> +</table> </section> <section id="DTV-ATSCMH-RS-FRAME-ENSEMBLE"> <title><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></title> - <para>RS frame ensemble.</para> + <para>Reed Solomon(RS) frame ensemble.</para> <para>Possible values are:</para> - <para id="atscmh-rs-frame-ensemble"> -<programlisting> -typedef enum atscmh_rs_frame_ensemble { - ATSCMH_RSFRAME_ENS_PRI = 0, - ATSCMH_RSFRAME_ENS_SEC = 1, -} atscmh_rs_frame_ensemble_t; -</programlisting> - </para> +<table pgwide="1" frame="none" id="atscmh-rs-frame-ensemble"> + <title>enum atscmh_rs_frame_ensemble</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="ATSCMH-RSFRAME-ENS-PRI"><constant>ATSCMH_RSFRAME_ENS_PRI</constant></entry> + <entry>Primary Ensemble.</entry> + </row><row> + <entry id="ATSCMH-RSFRAME-ENS-SEC"><constant>AATSCMH_RSFRAME_PRI_SEC</constant></entry> + <entry>Secondary Ensemble.</entry> + </row><row> + <entry id="ATSCMH-RSFRAME-RES"><constant>AATSCMH_RSFRAME_RES</constant></entry> + <entry>Reserved. Shouldn't be used.</entry> + </row> + </tbody> + </tgroup> +</table> </section> <section id="DTV-ATSCMH-RS-CODE-MODE-PRI"> <title><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></title> - <para>RS code mode (primary).</para> + <para>Reed Solomon (RS) code mode (primary).</para> <para>Possible values are:</para> - <para id="atscmh-rs-code-mode"> -<programlisting> -typedef enum atscmh_rs_code_mode { - ATSCMH_RSCODE_211_187 = 0, - ATSCMH_RSCODE_223_187 = 1, - ATSCMH_RSCODE_235_187 = 2, -} atscmh_rs_code_mode_t; -</programlisting> - </para> +<table pgwide="1" frame="none" id="atscmh-rs-code-mode"> + <title>enum atscmh_rs_code_mode</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="ATSCMH-RSCODE-211-187"><constant>ATSCMH_RSCODE_211_187</constant></entry> + <entry>Reed Solomon code (211,187).</entry> + </row><row> + <entry id="ATSCMH-RSCODE-223-187"><constant>ATSCMH_RSCODE_223_187</constant></entry> + <entry>Reed Solomon code (223,187).</entry> + </row><row> + <entry id="ATSCMH-RSCODE-235-187"><constant>ATSCMH_RSCODE_235_187</constant></entry> + <entry>Reed Solomon code (235,187).</entry> + </row><row> + <entry id="ATSCMH-RSCODE-RES"><constant>ATSCMH_RSCODE_RES</constant></entry> + <entry>Reserved. Shouldn't be used.</entry> + </row> + </tbody> + </tgroup> +</table> </section> <section id="DTV-ATSCMH-RS-CODE-MODE-SEC"> <title><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></title> - <para>RS code mode (secondary).</para> - <para>Possible values are:</para> -<programlisting> -typedef enum atscmh_rs_code_mode { - ATSCMH_RSCODE_211_187 = 0, - ATSCMH_RSCODE_223_187 = 1, - ATSCMH_RSCODE_235_187 = 2, -} atscmh_rs_code_mode_t; -</programlisting> + <para>Reed Solomon (RS) code mode (secondary).</para> + <para>Possible values are the same as documented on + &atscmh-rs-code-mode;:</para> </section> <section id="DTV-ATSCMH-SCCC-BLOCK-MODE"> <title><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></title> <para>Series Concatenated Convolutional Code Block Mode.</para> <para>Possible values are:</para> - <para id="atscmh-sccc-block-mode"> -<programlisting> -typedef enum atscmh_sccc_block_mode { - ATSCMH_SCCC_BLK_SEP = 0, - ATSCMH_SCCC_BLK_COMB = 1, -} atscmh_sccc_block_mode_t; -</programlisting> - </para> +<table pgwide="1" frame="none" id="atscmh-sccc-block-mode"> + <title>enum atscmh_scc_block_mode</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="ATSCMH-SCCC-BLK-SEP"><constant>ATSCMH_SCCC_BLK_SEP</constant></entry> + <entry>Separate SCCC: the SCCC outer code mode shall be set independently + for each Group Region (A, B, C, D)</entry> + </row><row> + <entry id="ATSCMH-SCCC-BLK-COMB"><constant>ATSCMH_SCCC_BLK_COMB</constant></entry> + <entry>Combined SCCC: all four Regions shall have the same SCCC outer + code mode.</entry> + </row><row> + <entry id="ATSCMH-SCCC-BLK-RES"><constant>ATSCMH_SCCC_BLK_RES</constant></entry> + <entry>Reserved. Shouldn't be used.</entry> + </row> + </tbody> + </tgroup> +</table> </section> <section id="DTV-ATSCMH-SCCC-CODE-MODE-A"> <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></title> <para>Series Concatenated Convolutional Code Rate.</para> <para>Possible values are:</para> - <para id="atscmh-sccc-code-mode"> -<programlisting> -typedef enum atscmh_sccc_code_mode { - ATSCMH_SCCC_CODE_HLF = 0, - ATSCMH_SCCC_CODE_QTR = 1, -} atscmh_sccc_code_mode_t; -</programlisting> - </para> +<table pgwide="1" frame="none" id="atscmh-sccc-code-mode"> + <title>enum atscmh_sccc_code_mode</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="ATSCMH-SCCC-CODE-HLF"><constant>ATSCMH_SCCC_CODE_HLF</constant></entry> + <entry>The outer code rate of a SCCC Block is 1/2 rate.</entry> + </row><row> + <entry id="ATSCMH-SCCC-CODE-QTR"><constant>ATSCMH_SCCC_CODE_QTR</constant></entry> + <entry>The outer code rate of a SCCC Block is 1/4 rate.</entry> + </row><row> + <entry id="ATSCMH-SCCC-CODE-RES"><constant>ATSCMH_SCCC_CODE_RES</constant></entry> + <entry>to be documented.</entry> + </row> + </tbody> + </tgroup> +</table> </section> <section id="DTV-ATSCMH-SCCC-CODE-MODE-B"> <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></title> <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are:</para> -<programlisting> -typedef enum atscmh_sccc_code_mode { - ATSCMH_SCCC_CODE_HLF = 0, - ATSCMH_SCCC_CODE_QTR = 1, -} atscmh_sccc_code_mode_t; -</programlisting> + <para>Possible values are the same as documented on + &atscmh-sccc-code-mode;.</para> </section> <section id="DTV-ATSCMH-SCCC-CODE-MODE-C"> <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></title> <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are:</para> -<programlisting> -typedef enum atscmh_sccc_code_mode { - ATSCMH_SCCC_CODE_HLF = 0, - ATSCMH_SCCC_CODE_QTR = 1, -} atscmh_sccc_code_mode_t; -</programlisting> + <para>Possible values are the same as documented on + &atscmh-sccc-code-mode;.</para> </section> <section id="DTV-ATSCMH-SCCC-CODE-MODE-D"> <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></title> <para>Series Concatenated Convolutional Code Rate.</para> - <para>Possible values are:</para> -<programlisting> -typedef enum atscmh_sccc_code_mode { - ATSCMH_SCCC_CODE_HLF = 0, - ATSCMH_SCCC_CODE_QTR = 1, -} atscmh_sccc_code_mode_t; -</programlisting> + <para>Possible values are the same as documented on + &atscmh-sccc-code-mode;.</para> </section> </section> <section id="DTV-API-VERSION"> @@ -746,65 +1011,74 @@ typedef enum atscmh_sccc_code_mode { </section> <section id="DTV-CODE-RATE-HP"> <title><constant>DTV_CODE_RATE_HP</constant></title> - <para>Used on terrestrial transmissions. The acceptable values are: + <para>Used on terrestrial transmissions. The acceptable values are + the ones described at &fe-transmit-mode-t;. </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, - FEC_3_5, - FEC_9_10, -} fe_code_rate_t; - </programlisting> </section> <section id="DTV-CODE-RATE-LP"> <title><constant>DTV_CODE_RATE_LP</constant></title> - <para>Used on terrestrial transmissions. The acceptable values are: + <para>Used on terrestrial transmissions. The acceptable values are + the ones described at &fe-transmit-mode-t;. </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, - FEC_3_5, - FEC_9_10, -} fe_code_rate_t; - </programlisting> + </section> + <section id="DTV-GUARD-INTERVAL"> <title><constant>DTV_GUARD_INTERVAL</constant></title> <para>Possible values are:</para> -<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, - GUARD_INTERVAL_1_128, - GUARD_INTERVAL_19_128, - GUARD_INTERVAL_19_256, - GUARD_INTERVAL_PN420, - GUARD_INTERVAL_PN595, - GUARD_INTERVAL_PN945, -} fe_guard_interval_t; -</programlisting> + +<section id="fe-guard-interval-t"> +<title>Modulation guard interval</title> + +<table pgwide="1" frame="none" id="fe-guard-interval"> + <title>enum fe_guard_interval</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="GUARD-INTERVAL-AUTO"><constant>GUARD_INTERVAL_AUTO</constant></entry> + <entry>Autodetect the guard interval</entry> + </row><row> + <entry id="GUARD-INTERVAL-1-128"><constant>GUARD_INTERVAL_1_128</constant></entry> + <entry>Guard interval 1/128</entry> + </row><row> + <entry id="GUARD-INTERVAL-1-32"><constant>GUARD_INTERVAL_1_32</constant></entry> + <entry>Guard interval 1/32</entry> + </row><row> + <entry id="GUARD-INTERVAL-1-16"><constant>GUARD_INTERVAL_1_16</constant></entry> + <entry>Guard interval 1/16</entry> + </row><row> + <entry id="GUARD-INTERVAL-1-8"><constant>GUARD_INTERVAL_1_8</constant></entry> + <entry>Guard interval 1/8</entry> + </row><row> + <entry id="GUARD-INTERVAL-1-4"><constant>GUARD_INTERVAL_1_4</constant></entry> + <entry>Guard interval 1/4</entry> + </row><row> + <entry id="GUARD-INTERVAL-19-128"><constant>GUARD_INTERVAL_19_128</constant></entry> + <entry>Guard interval 19/128</entry> + </row><row> + <entry id="GUARD-INTERVAL-19-256"><constant>GUARD_INTERVAL_19_256</constant></entry> + <entry>Guard interval 19/256</entry> + </row><row> + <entry id="GUARD-INTERVAL-PN420"><constant>GUARD_INTERVAL_PN420</constant></entry> + <entry>PN length 420 (1/4)</entry> + </row><row> + <entry id="GUARD-INTERVAL-PN595"><constant>GUARD_INTERVAL_PN595</constant></entry> + <entry>PN length 595 (1/6)</entry> + </row><row> + <entry id="GUARD-INTERVAL-PN945"><constant>GUARD_INTERVAL_PN945</constant></entry> + <entry>PN length 945 (1/9)</entry> + </row> + </tbody> + </tgroup> +</table> <para>Notes:</para> <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will @@ -812,26 +1086,64 @@ typedef enum fe_guard_interval { in the missing parameters.</para> <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para> <para>3) DTMB specifies PN420, PN595 and PN945.</para> +</section> </section> <section id="DTV-TRANSMISSION-MODE"> <title><constant>DTV_TRANSMISSION_MODE</constant></title> - <para>Specifies the number of carriers used by the standard</para> + <para>Specifies the number of carriers used by the standard. + This is used only on OFTM-based standards, e. g. + DVB-T/T2, ISDB-T, DTMB</para> + +<section id="fe-transmit-mode-t"> +<title>enum fe_transmit_mode: Number of carriers per channel</title> + +<table pgwide="1" frame="none" id="fe-transmit-mode"> + <title>enum fe_transmit_mode</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="TRANSMISSION-MODE-AUTO"><constant>TRANSMISSION_MODE_AUTO</constant></entry> + <entry>Autodetect transmission mode. The hardware will try to find + the correct FFT-size (if capable) to fill in the missing + parameters.</entry> + </row><row> + <entry id="TRANSMISSION-MODE-1K"><constant>TRANSMISSION_MODE_1K</constant></entry> + <entry>Transmission mode 1K</entry> + </row><row> + <entry id="TRANSMISSION-MODE-2K"><constant>TRANSMISSION_MODE_2K</constant></entry> + <entry>Transmission mode 2K</entry> + </row><row> + <entry id="TRANSMISSION-MODE-8K"><constant>TRANSMISSION_MODE_8K</constant></entry> + <entry>Transmission mode 8K</entry> + </row><row> + <entry id="TRANSMISSION-MODE-4K"><constant>TRANSMISSION_MODE_4K</constant></entry> + <entry>Transmission mode 4K</entry> + </row><row> + <entry id="TRANSMISSION-MODE-16K"><constant>TRANSMISSION_MODE_16K</constant></entry> + <entry>Transmission mode 16K</entry> + </row><row> + <entry id="TRANSMISSION-MODE-32K"><constant>TRANSMISSION_MODE_32K</constant></entry> + <entry>Transmission mode 32K</entry> + </row><row> + <entry id="TRANSMISSION-MODE-C1"><constant>TRANSMISSION_MODE_C1</constant></entry> + <entry>Single Carrier (C=1) transmission mode (DTMB)</entry> + </row><row> + <entry id="TRANSMISSION-MODE-C3780"><constant>TRANSMISSION_MODE_C3780</constant></entry> + <entry>Multi Carrier (C=3780) transmission mode (DTMB)</entry> + </row> + </tbody> + </tgroup> +</table> + - <para>Possible values are:</para> -<programlisting> -typedef enum fe_transmit_mode { - TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K, - TRANSMISSION_MODE_AUTO, - TRANSMISSION_MODE_4K, - TRANSMISSION_MODE_1K, - TRANSMISSION_MODE_16K, - TRANSMISSION_MODE_32K, - TRANSMISSION_MODE_C1, - TRANSMISSION_MODE_C3780, -} fe_transmit_mode_t; -</programlisting> <para>Notes:</para> <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para> @@ -842,19 +1154,48 @@ typedef enum fe_transmit_mode { <para>3) DVB-T specifies 2K and 8K as valid sizes.</para> <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para> <para>5) DTMB specifies C1 and C3780.</para> +</section> </section> <section id="DTV-HIERARCHY"> <title><constant>DTV_HIERARCHY</constant></title> <para>Frontend hierarchy</para> - <programlisting> -typedef enum fe_hierarchy { - HIERARCHY_NONE, - HIERARCHY_1, - HIERARCHY_2, - HIERARCHY_4, - HIERARCHY_AUTO - } fe_hierarchy_t; - </programlisting> + + +<section id="fe-hierarchy-t"> +<title>Frontend hierarchy</title> + +<table pgwide="1" frame="none" id="fe-hierarchy"> + <title>enum fe_hierarchy</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="HIERARCHY-NONE"><constant>HIERARCHY_NONE</constant></entry> + <entry>No hierarchy</entry> + </row><row> + <entry id="HIERARCHY-AUTO"><constant>HIERARCHY_AUTO</constant></entry> + <entry>Autodetect hierarchy (if supported)</entry> + </row><row> + <entry id="HIERARCHY-1"><constant>HIERARCHY_1</constant></entry> + <entry>Hierarchy 1</entry> + </row><row> + <entry id="HIERARCHY-2"><constant>HIERARCHY_2</constant></entry> + <entry>Hierarchy 2</entry> + </row><row> + <entry id="HIERARCHY-4"><constant>HIERARCHY_4</constant></entry> + <entry>Hierarchy 4</entry> + </row> + </tbody> + </tgroup> +</table> +</section> + </section> <section id="DTV-STREAM-ID"> <title><constant>DTV_STREAM_ID</constant></title> @@ -891,15 +1232,37 @@ typedef enum fe_hierarchy { </section> <section id="DTV-INTERLEAVING"> <title><constant>DTV_INTERLEAVING</constant></title> - <para id="fe-interleaving">Interleaving mode</para> - <programlisting> -enum fe_interleaving { - INTERLEAVING_NONE, - INTERLEAVING_AUTO, - INTERLEAVING_240, - INTERLEAVING_720, -}; - </programlisting> + +<para>Time interleaving to be used. Currently, used only on DTMB.</para> + +<table pgwide="1" frame="none" id="fe-interleaving"> + <title>enum fe_interleaving</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="INTERLEAVING-NONE"><constant>INTERLEAVING_NONE</constant></entry> + <entry>No interleaving.</entry> + </row><row> + <entry id="INTERLEAVING-AUTO"><constant>INTERLEAVING_AUTO</constant></entry> + <entry>Auto-detect interleaving.</entry> + </row><row> + <entry id="INTERLEAVING-240"><constant>INTERLEAVING_240</constant></entry> + <entry>Interleaving of 240 symbols.</entry> + </row><row> + <entry id="INTERLEAVING-720"><constant>INTERLEAVING_720</constant></entry> + <entry>Interleaving of 720 symbols.</entry> + </row> + </tbody> + </tgroup> +</table> + </section> <section id="DTV-LNA"> <title><constant>DTV_LNA</constant></title> @@ -921,7 +1284,7 @@ enum fe_interleaving { <para>For most delivery systems, <constant>dtv_property.stat.len</constant> will be 1 if the stats is supported, and the properties will return a single value for each parameter.</para> - <para>It should be noticed, however, that new OFDM delivery systems + <para>It should be noted, however, that new OFDM delivery systems like ISDB can use different modulation types for each group of carriers. On such standards, up to 3 groups of statistics can be provided, and <constant>dtv_property.stat.len</constant> is updated @@ -940,10 +1303,10 @@ enum fe_interleaving { and <constant>uvalue</constant> is for unsigned values (counters, relative scale)</para></listitem> <listitem><para><constant>scale</constant> - Scale for the value. It can be:</para> <itemizedlist mark='bullet' id="fecap-scale-params"> - <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)</para></listitem> - <listitem><para><constant>FE_SCALE_DECIBEL</constant> - parameter is a signed value, measured in 1/1000 dB</para></listitem> - <listitem><para><constant>FE_SCALE_RELATIVE</constant> - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.</para></listitem> - <listitem><para><constant>FE_SCALE_COUNTER</constant> - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.</para></listitem> + <listitem id="FE-SCALE-NOT-AVAILABLE"><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)</para></listitem> + <listitem id="FE-SCALE-DECIBEL"><para><constant>FE_SCALE_DECIBEL</constant> - parameter is a signed value, measured in 1/1000 dB</para></listitem> + <listitem id="FE-SCALE-RELATIVE"><para><constant>FE_SCALE_RELATIVE</constant> - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.</para></listitem> + <listitem id="FE-SCALE-COUNTER"><para><constant>FE_SCALE_COUNTER</constant> - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.</para></listitem> </itemizedlist> </listitem> </itemizedlist> @@ -953,7 +1316,7 @@ enum fe_interleaving { <para>Possible scales for this metric are:</para> <itemizedlist mark='bullet'> <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_DECIBEL</constant> - signal strength is in 0.0001 dBm units, power measured in miliwatts. This value is generally negative.</para></listitem> + <listitem><para><constant>FE_SCALE_DECIBEL</constant> - signal strength is in 0.001 dBm units, power measured in miliwatts. This value is generally negative.</para></listitem> <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for power (actually, 0 to 65535).</para></listitem> </itemizedlist> </section> @@ -963,7 +1326,7 @@ enum fe_interleaving { <para>Possible scales for this metric are:</para> <itemizedlist mark='bullet'> <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> - <listitem><para><constant>FE_SCALE_DECIBEL</constant> - Signal/Noise ratio is in 0.0001 dB units.</para></listitem> + <listitem><para><constant>FE_SCALE_DECIBEL</constant> - Signal/Noise ratio is in 0.001 dB units.</para></listitem> <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for Signal/Noise (actually, 0 to 65535).</para></listitem> </itemizedlist> </section> @@ -985,7 +1348,7 @@ enum fe_interleaving { <title><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></title> <para>Measures the amount of bits received before the inner code block, during the same period as <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link> measurement was taken.</para> - <para>It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream, + <para>It should be noted that this measurement can be smaller than the total amount of bits on the transport stream, as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para> <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. The frontend may reset it when a channel/transponder is tuned.</para> @@ -1014,7 +1377,7 @@ enum fe_interleaving { <title><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></title> <para>Measures the amount of bits received after the inner coding, during the same period as <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link> measurement was taken.</para> - <para>It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream, + <para>It should be noted that this measurement can be smaller than the total amount of bits on the transport stream, as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para> <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. The frontend may reset it when a channel/transponder is tuned.</para> @@ -1255,8 +1618,8 @@ enum fe_interleaving { <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> </section> - <section id="frontend-property-satellital-systems"> - <title>Properties used on satellital delivery systems</title> + <section id="frontend-property-satellite-systems"> + <title>Properties used on satellite delivery systems</title> <section id="dvbs-params"> <title>DVB-S delivery system</title> <para>The following parameters are valid for DVB-S:</para> diff --git a/kernel/Documentation/DocBook/media/dvb/examples.xml b/kernel/Documentation/DocBook/media/dvb/examples.xml index f037e568e..c9f68c718 100644 --- a/kernel/Documentation/DocBook/media/dvb/examples.xml +++ b/kernel/Documentation/DocBook/media/dvb/examples.xml @@ -1,8 +1,10 @@ <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 <ulink url="http://linuxtv.org/hg/dvb-apps" />. +<para>NOTE: This section is out of date, and the code below won't even + compile. Please refer to the + <ulink url="http://linuxtv.org/docs/libdvbv5/index.html">libdvbv5</ulink> + for updated/recommended examples. </para> <section id="tuning"> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-diseqc-recv-slave-reply.xml b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-recv-slave-reply.xml new file mode 100644 index 000000000..4595dbfff --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-recv-slave-reply.xml @@ -0,0 +1,78 @@ +<refentry id="FE_DISEQC_RECV_SLAVE_REPLY"> + <refmeta> + <refentrytitle>ioctl FE_DISEQC_RECV_SLAVE_REPLY</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_DISEQC_RECV_SLAVE_REPLY</refname> + <refpurpose>Receives reply from a DiSEqC 2.0 command</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct dvb_diseqc_slave_reply *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_DISEQC_RECV_SLAVE_REPLY</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>pointer to &dvb-diseqc-slave-reply;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Receives reply from a DiSEqC 2.0 command.</para> +&return-value-dvb; + +<table pgwide="1" frame="none" id="dvb-diseqc-slave-reply"> + <title>struct <structname>dvb_diseqc_slave_reply</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>uint8_t</entry> + <entry>msg[4]</entry> + <entry>DiSEqC message (framing, data[3])</entry> + </row><row> + <entry>uint8_t</entry> + <entry>msg_len</entry> + <entry>Length of the DiSEqC message. Valid values are 0 to 4, + where 0 means no msg</entry> + </row><row> + <entry>int</entry> + <entry>timeout</entry> + <entry>Return from ioctl after timeout ms with errorcode when no + message was received</entry> + </row> + </tbody> + </tgroup> +</table> + +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-diseqc-reset-overload.xml b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-reset-overload.xml new file mode 100644 index 000000000..c104df77e --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-reset-overload.xml @@ -0,0 +1,51 @@ +<refentry id="FE_DISEQC_RESET_OVERLOAD"> + <refmeta> + <refentrytitle>ioctl FE_DISEQC_RESET_OVERLOAD</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_DISEQC_RESET_OVERLOAD</refname> + <refpurpose>Restores the power to the antenna subsystem, if it was powered + off due to power overload.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>NULL</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_DISEQC_RESET_OVERLOAD</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <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> +&return-value-dvb; +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-diseqc-send-burst.xml b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-send-burst.xml new file mode 100644 index 000000000..9f6a68f32 --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-send-burst.xml @@ -0,0 +1,89 @@ +<refentry id="FE_DISEQC_SEND_BURST"> + <refmeta> + <refentrytitle>ioctl FE_DISEQC_SEND_BURST</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_DISEQC_SEND_BURST</refname> + <refpurpose>Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>enum fe_sec_mini_cmd *<parameter>tone</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_DISEQC_SEND_BURST</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>tone</parameter></term> + <listitem> + <para>pointer to &fe-sec-mini-cmd;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + +<para>This ioctl is used to set the generation of a 22kHz tone burst for mini + DiSEqC satellite + selection for 2x1 switches. + This call requires read/write permissions.</para> +<para>It provides support for what's specified at + <ulink url="http://www.eutelsat.com/files/contributed/satellites/pdf/Diseqc/associated%20docs/simple_tone_burst_detec.pdf">Digital Satellite Equipment Control + (DiSEqC) - Simple "ToneBurst" Detection Circuit specification.</ulink> + </para> +&return-value-dvb; +</refsect1> + +<refsect1 id="fe-sec-mini-cmd-t"> +<title>enum fe_sec_mini_cmd</title> + +<table pgwide="1" frame="none" id="fe-sec-mini-cmd"> + <title>enum fe_sec_mini_cmd</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="SEC-MINI-A"><constant>SEC_MINI_A</constant></entry> + <entry align="char">Sends a mini-DiSEqC 22kHz '0' Tone Burst to + select satellite-A</entry> + </row><row> + <entry align="char" id="SEC-MINI-B"><constant>SEC_MINI_B</constant></entry> + <entry align="char">Sends a mini-DiSEqC 22kHz '1' Data Burst to + select satellite-B</entry> + </row> + </tbody> + </tgroup> +</table> +</refsect1> + +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-diseqc-send-master-cmd.xml b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-send-master-cmd.xml new file mode 100644 index 000000000..38cf313e1 --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-diseqc-send-master-cmd.xml @@ -0,0 +1,72 @@ +<refentry id="FE_DISEQC_SEND_MASTER_CMD"> + <refmeta> + <refentrytitle>ioctl FE_DISEQC_SEND_MASTER_CMD</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_DISEQC_SEND_MASTER_CMD</refname> + <refpurpose>Sends a DiSEqC command</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct dvb_diseqc_master_cmd *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_DISEQC_SEND_MASTER_CMD</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>pointer to &dvb-diseqc-master-cmd;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Sends a DiSEqC command to the antenna subsystem.</para> +&return-value-dvb; + +<table pgwide="1" frame="none" id="dvb-diseqc-master-cmd"> + <title>struct <structname>dvb_diseqc_master_cmd</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>uint8_t</entry> + <entry>msg[6]</entry> + <entry>DiSEqC message (framing, address, command, data[3])</entry> + </row><row> + <entry>uint8_t</entry> + <entry>msg_len</entry> + <entry>Length of the DiSEqC message. Valid values are 3 to 6</entry> + </row> + </tbody> + </tgroup> +</table> + +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-enable-high-lnb-voltage.xml b/kernel/Documentation/DocBook/media/dvb/fe-enable-high-lnb-voltage.xml new file mode 100644 index 000000000..c11890b18 --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-enable-high-lnb-voltage.xml @@ -0,0 +1,61 @@ +<refentry id="FE_ENABLE_HIGH_LNB_VOLTAGE"> + <refmeta> + <refentrytitle>ioctl FE_ENABLE_HIGH_LNB_VOLTAGE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_ENABLE_HIGH_LNB_VOLTAGE</refname> + <refpurpose>Select output DC level between normal LNBf voltages or higher + LNBf voltages.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>unsigned int <parameter>high</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_ENABLE_HIGH_LNB_VOLTAGE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>high</parameter></term> + <listitem> + <para>Valid flags:</para> + <itemizedlist> + <listitem><para>0 - normal 13V and 18V.</para></listitem> + <listitem><para>>0 - enables slightly higher voltages instead of + 13/18V, in order to compensate for long antenna cables.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Select output DC level between normal LNBf voltages or higher + LNBf voltages between 0 (normal) or a value grater than 0 for higher + voltages.</para> +&return-value-dvb; +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-get-info.xml b/kernel/Documentation/DocBook/media/dvb/fe-get-info.xml new file mode 100644 index 000000000..ed0eeb29d --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-get-info.xml @@ -0,0 +1,266 @@ +<refentry id="FE_GET_INFO"> + <refmeta> + <refentrytitle>ioctl FE_GET_INFO</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_GET_INFO</refname> + <refpurpose>Query DVB frontend capabilities and returns information about + the front-end. This call only requires read-only access to the device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct dvb_frontend_info *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_GET_INFO</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>pointer to struct &dvb-frontend-info;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>All DVB frontend devices support the +<constant>FE_GET_INFO</constant> ioctl. It is used to identify +kernel devices compatible with this specification and to obtain +information about driver and hardware capabilities. The ioctl takes a +pointer to dvb_frontend_info which is filled by the driver. When the +driver is not compatible with this specification the ioctl returns an error. +</para> +&return-value-dvb; + + <table pgwide="1" frame="none" id="dvb-frontend-info"> + <title>struct <structname>dvb_frontend_info</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>char</entry> + <entry>name[128]</entry> + <entry>Name of the frontend</entry> + </row><row> + <entry>fe_type_t</entry> + <entry>type</entry> + <entry><emphasis role="bold">DEPRECATED</emphasis>. DVBv3 type. Should not be used on modern programs, as a + frontend may have more than one type. So, the DVBv5 API should + be used instead to enumerate and select the frontend type.</entry> + </row><row> + <entry>uint32_t</entry> + <entry>frequency_min</entry> + <entry>Minimal frequency supported by the frontend</entry> + </row><row> + <entry>uint32_t</entry> + <entry>frequency_max</entry> + <entry>Maximal frequency supported by the frontend</entry> + </row><row> + <entry>uint32_t</entry> + <entry>frequency_stepsize</entry> + <entry>Frequency step - all frequencies are multiple of this value</entry> + </row><row> + <entry>uint32_t</entry> + <entry>frequency_tolerance</entry> + <entry>Tolerance of the frequency</entry> + </row><row> + <entry>uint32_t</entry> + <entry>symbol_rate_min</entry> + <entry>Minimal symbol rate (for Cable/Satellite systems), in bauds</entry> + </row><row> + <entry>uint32_t</entry> + <entry>symbol_rate_max</entry> + <entry>Maximal symbol rate (for Cable/Satellite systems), in bauds</entry> + </row><row> + <entry>uint32_t</entry> + <entry>symbol_rate_tolerance</entry> + <entry>Maximal symbol rate tolerance, in ppm</entry> + </row><row> + <entry>uint32_t</entry> + <entry>notifier_delay</entry> + <entry><emphasis role="bold">DEPRECATED</emphasis>. Not used by any driver.</entry> + </row><row> + <entry>&fe-caps;</entry> + <entry>caps</entry> + <entry>Capabilities supported by the frontend</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>NOTE: The frequencies are specified in Hz for Terrestrial and Cable + systems. They're specified in kHz for Satellite systems</para> + </refsect1> + +<refsect1 id="fe-caps-t"> +<title>frontend capabilities</title> + +<para>Capabilities describe what a frontend can do. Some capabilities are + supported only on some specific frontend types.</para> + +<table pgwide="1" frame="none" id="fe-caps"> + <title>enum fe_caps</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="FE-IS-STUPID"><constant>FE_IS_STUPID</constant></entry> + <entry>There's something wrong at the frontend, and it can't + report its capabilities</entry> + </row> + <row> + <entry id="FE-CAN-INVERSION-AUTO"><constant>FE_CAN_INVERSION_AUTO</constant></entry> + <entry>The frontend is capable of auto-detecting inversion</entry> + </row> + <row> + <entry id="FE-CAN-FEC-1-2"><constant>FE_CAN_FEC_1_2</constant></entry> + <entry>The frontend supports FEC 1/2</entry> + </row> + <row> + <entry id="FE-CAN-FEC-2-3"><constant>FE_CAN_FEC_2_3</constant></entry> + <entry>The frontend supports FEC 2/3</entry> + </row> + <row> + <entry id="FE-CAN-FEC-3-4"><constant>FE_CAN_FEC_3_4</constant></entry> + <entry>The frontend supports FEC 3/4</entry> + </row> + <row> + <entry id="FE-CAN-FEC-4-5"><constant>FE_CAN_FEC_4_5</constant></entry> + <entry>The frontend supports FEC 4/5</entry> + </row> + <row> + <entry id="FE-CAN-FEC-5-6"><constant>FE_CAN_FEC_5_6</constant></entry> + <entry>The frontend supports FEC 5/6</entry> + </row> + <row> + <entry id="FE-CAN-FEC-6-7"><constant>FE_CAN_FEC_6_7</constant></entry> + <entry>The frontend supports FEC 6/7</entry> + </row> + <row> + <entry id="FE-CAN-FEC-7-8"><constant>FE_CAN_FEC_7_8</constant></entry> + <entry>The frontend supports FEC 7/8</entry> + </row> + <row> + <entry id="FE-CAN-FEC-8-9"><constant>FE_CAN_FEC_8_9</constant></entry> + <entry>The frontend supports FEC 8/9</entry> + </row> + <row> + <entry id="FE-CAN-FEC-AUTO"><constant>FE_CAN_FEC_AUTO</constant></entry> + <entry>The frontend can autodetect FEC.</entry> + </row> + <row> + <entry id="FE-CAN-QPSK"><constant>FE_CAN_QPSK</constant></entry> + <entry>The frontend supports QPSK modulation</entry> + </row> + <row> + <entry id="FE-CAN-QAM-16"><constant>FE_CAN_QAM_16</constant></entry> + <entry>The frontend supports 16-QAM modulation</entry> + </row> + <row> + <entry id="FE-CAN-QAM-32"><constant>FE_CAN_QAM_32</constant></entry> + <entry>The frontend supports 32-QAM modulation</entry> + </row> + <row> + <entry id="FE-CAN-QAM-64"><constant>FE_CAN_QAM_64</constant></entry> + <entry>The frontend supports 64-QAM modulation</entry> + </row> + <row> + <entry id="FE-CAN-QAM-128"><constant>FE_CAN_QAM_128</constant></entry> + <entry>The frontend supports 128-QAM modulation</entry> + </row> + <row> + <entry id="FE-CAN-QAM-256"><constant>FE_CAN_QAM_256</constant></entry> + <entry>The frontend supports 256-QAM modulation</entry> + </row> + <row> + <entry id="FE-CAN-QAM-AUTO"><constant>FE_CAN_QAM_AUTO</constant></entry> + <entry>The frontend can autodetect modulation</entry> + </row> + <row> + <entry id="FE-CAN-TRANSMISSION-MODE-AUTO"><constant>FE_CAN_TRANSMISSION_MODE_AUTO</constant></entry> + <entry>The frontend can autodetect the transmission mode</entry> + </row> + <row> + <entry id="FE-CAN-BANDWIDTH-AUTO"><constant>FE_CAN_BANDWIDTH_AUTO</constant></entry> + <entry>The frontend can autodetect the bandwidth</entry> + </row> + <row> + <entry id="FE-CAN-GUARD-INTERVAL-AUTO"><constant>FE_CAN_GUARD_INTERVAL_AUTO</constant></entry> + <entry>The frontend can autodetect the guard interval</entry> + </row> + <row> + <entry id="FE-CAN-HIERARCHY-AUTO"><constant>FE_CAN_HIERARCHY_AUTO</constant></entry> + <entry>The frontend can autodetect hierarch</entry> + </row> + <row> + <entry id="FE-CAN-8VSB"><constant>FE_CAN_8VSB</constant></entry> + <entry>The frontend supports 8-VSB modulation</entry> + </row> + <row> + <entry id="FE-CAN-16VSB"><constant>FE_CAN_16VSB</constant></entry> + <entry>The frontend supports 16-VSB modulation</entry> + </row> + <row> + <entry id="FE-HAS-EXTENDED-CAPS"><constant>FE_HAS_EXTENDED_CAPS</constant></entry> + <entry>Currently, unused</entry> + </row> + <row> + <entry id="FE-CAN-MULTISTREAM"><constant>FE_CAN_MULTISTREAM</constant></entry> + <entry>The frontend supports multistream filtering</entry> + </row> + <row> + <entry id="FE-CAN-TURBO-FEC"><constant>FE_CAN_TURBO_FEC</constant></entry> + <entry>The frontend supports turbo FEC modulation</entry> + </row> + <row> + <entry id="FE-CAN-2G-MODULATION"><constant>FE_CAN_2G_MODULATION</constant></entry> + <entry>The frontend supports "2nd generation modulation" (DVB-S2/T2)></entry> + </row> + <row> + <entry id="FE-NEEDS-BENDING"><constant>FE_NEEDS_BENDING</constant></entry> + <entry>Not supported anymore, don't use it</entry> + </row> + <row> + <entry id="FE-CAN-RECOVER"><constant>FE_CAN_RECOVER</constant></entry> + <entry>The frontend can recover from a cable unplug automatically</entry> + </row> + <row> + <entry id="FE-CAN-MUTE-TS"><constant>FE_CAN_MUTE_TS</constant></entry> + <entry>The frontend can stop spurious TS data output</entry> + </row> + </tbody> + </tgroup> +</table> +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-get-property.xml b/kernel/Documentation/DocBook/media/dvb/fe-get-property.xml new file mode 100644 index 000000000..53a170ed3 --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-get-property.xml @@ -0,0 +1,81 @@ +<refentry id="FE_GET_PROPERTY"> + <refmeta> + <refentrytitle>ioctl FE_SET_PROPERTY, FE_GET_PROPERTY</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_SET_PROPERTY</refname> + <refname>FE_GET_PROPERTY</refname> + <refpurpose>FE_SET_PROPERTY sets one or more frontend properties. + FE_GET_PROPERTY returns one or more frontend properties.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct dtv_properties *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_PROPERTY, FE_GET_PROPERTY</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>pointer to &dtv-properties;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>All DVB frontend devices support the +<constant>FE_SET_PROPERTY</constant> and <constant>FE_GET_PROPERTY</constant> +ioctls. The supported properties and statistics depends on the delivery system +and on the device:</para> +<itemizedlist> +<listitem> + <para><constant>FE_SET_PROPERTY:</constant></para> +<itemizedlist> +<listitem><para>This ioctl is used to set one or more + frontend properties.</para></listitem> +<listitem><para>This is the basic command to request the frontend to tune into some + frequency and to start decoding the digital TV signal.</para></listitem> +<listitem><para>This call requires read/write access to the device.</para></listitem> +<listitem><para>At return, the values are updated to reflect the + actual parameters used.</para></listitem> +</itemizedlist> +</listitem> +<listitem> + <para><constant>FE_GET_PROPERTY:</constant></para> +<itemizedlist> +<listitem><para>This ioctl is used to get properties and +statistics from the frontend.</para></listitem> +<listitem><para>No properties are changed, and statistics aren't reset.</para></listitem> +<listitem><para>This call only requires read-only access to the device.</para></listitem> +</itemizedlist> +</listitem> +</itemizedlist> +&return-value-dvb; +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-read-status.xml b/kernel/Documentation/DocBook/media/dvb/fe-read-status.xml new file mode 100644 index 000000000..bc0dc2a55 --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-read-status.xml @@ -0,0 +1,107 @@ +<refentry id="FE_READ_STATUS"> + <refmeta> + <refentrytitle>ioctl FE_READ_STATUS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_READ_STATUS</refname> + <refpurpose>Returns status information about the front-end. This call only + requires read-only access to the device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>unsigned int *<parameter>status</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_READ_STATUS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>status</parameter></term> + <listitem> + <para>pointer to a bitmask integer filled with the values defined by + &fe-status;.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>All DVB frontend devices support the +<constant>FE_READ_STATUS</constant> ioctl. It is used to check about the +locking status of the frontend after being tuned. The ioctl takes a +pointer to an integer where the status will be written. +</para> +<para>NOTE: the size of status is actually sizeof(enum fe_status), with varies + according with the architecture. This needs to be fixed in the future.</para> +&return-value-dvb; +</refsect1> + +<refsect1 id="fe-status-t"> +<title>int fe_status</title> + +<para>The fe_status parameter is used to indicate the current state + and/or state changes of the frontend hardware. It is produced using + the &fe-status; values on a bitmask</para> + +<table pgwide="1" frame="none" id="fe-status"> + <title>enum fe_status</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="FE-HAS-SIGNAL"><constant>FE_HAS_SIGNAL</constant></entry> + <entry align="char">The frontend has found something above the noise level</entry> + </row><row> + <entry align="char" id="FE-HAS-CARRIER"><constant>FE_HAS_CARRIER</constant></entry> + <entry align="char">The frontend has found a DVB signal</entry> + </row><row> + <entry align="char" id="FE-HAS-VITERBI"><constant>FE_HAS_VITERBI</constant></entry> + <entry align="char">The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable</entry> + </row><row> + <entry align="char" id="FE-HAS-SYNC"><constant>FE_HAS_SYNC</constant></entry> + <entry align="char">Synchronization bytes was found</entry> + </row><row> + <entry align="char" id="FE-HAS-LOCK"><constant>FE_HAS_LOCK</constant></entry> + <entry align="char">The DVB were locked and everything is working</entry> + </row><row> + <entry align="char" id="FE-TIMEDOUT"><constant>FE_TIMEDOUT</constant></entry> + <entry align="char">no lock within the last about 2 seconds</entry> + </row><row> + <entry align="char" id="FE-REINIT"><constant>FE_REINIT</constant></entry> + <entry align="char">The frontend was reinitialized, application is + recommended to reset DiSEqC, tone and parameters</entry> + </row> + </tbody> + </tgroup> +</table> +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-set-frontend-tune-mode.xml b/kernel/Documentation/DocBook/media/dvb/fe-set-frontend-tune-mode.xml new file mode 100644 index 000000000..99fa8a015 --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-set-frontend-tune-mode.xml @@ -0,0 +1,64 @@ +<refentry id="FE_SET_FRONTEND_TUNE_MODE"> + <refmeta> + <refentrytitle>ioctl FE_SET_FRONTEND_TUNE_MODE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_SET_FRONTEND_TUNE_MODE</refname> + <refpurpose>Allow setting tuner mode flags to the frontend.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>unsigned int <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_FRONTEND_TUNE_MODE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para>Valid flags:</para> + <itemizedlist> + <listitem><para>0 - normal tune mode</para></listitem> + <listitem><para>FE_TUNE_MODE_ONESHOT - When set, this flag will + disable any zigzagging or other "normal" tuning behaviour. + Additionally, there will be no automatic monitoring of the + lock status, and hence no frontend events will be + generated. If a frontend device is closed, this flag will + be automatically turned off when the device is reopened + read-write.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para>Allow setting tuner mode flags to the frontend, between 0 (normal) + or FE_TUNE_MODE_ONESHOT mode</para> +&return-value-dvb; +</refsect1> +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-set-tone.xml b/kernel/Documentation/DocBook/media/dvb/fe-set-tone.xml new file mode 100644 index 000000000..62d44e4cc --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-set-tone.xml @@ -0,0 +1,91 @@ +<refentry id="FE_SET_TONE"> + <refmeta> + <refentrytitle>ioctl FE_SET_TONE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_SET_TONE</refname> + <refpurpose>Sets/resets the generation of the continuous 22kHz tone.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>enum fe_sec_tone_mode *<parameter>tone</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_TONE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>tone</parameter></term> + <listitem> + <para>pointer to &fe-sec-tone-mode;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + +<para>This ioctl is used to set the generation of the continuous 22kHz tone. + This call requires read/write permissions.</para> +<para>Usually, satellite antenna subsystems require that the digital TV + device to send a 22kHz tone in order to select between high/low band on + some dual-band LNBf. It is also used to send signals to DiSEqC equipment, + but this is done using the DiSEqC ioctls.</para> +<para>NOTE: if more than one device is connected to the same antenna, + setting a tone may interfere on other devices, as they may lose + the capability of selecting the band. So, it is recommended that + applications would change to SEC_TONE_OFF when the device is not used.</para> + +&return-value-dvb; +</refsect1> + +<refsect1 id="fe-sec-tone-mode-t"> +<title>enum fe_sec_tone_mode</title> + +<table pgwide="1" frame="none" id="fe-sec-tone-mode"> + <title>enum fe_sec_tone_mode</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char" id="SEC-TONE-ON"><constant>SEC_TONE_ON</constant></entry> + <entry align="char">Sends a 22kHz tone burst to the antenna</entry> + </row><row> + <entry align="char" id="SEC-TONE-OFF"><constant>SEC_TONE_OFF</constant></entry> + <entry align="char">Don't send a 22kHz tone to the antenna + (except if the FE_DISEQC_* ioctls are called)</entry> + </row> + </tbody> + </tgroup> +</table> +</refsect1> + +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/fe-set-voltage.xml b/kernel/Documentation/DocBook/media/dvb/fe-set-voltage.xml new file mode 100644 index 000000000..c89a6f79b --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/fe-set-voltage.xml @@ -0,0 +1,69 @@ +<refentry id="FE_SET_VOLTAGE"> + <refmeta> + <refentrytitle>ioctl FE_SET_VOLTAGE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>FE_SET_VOLTAGE</refname> + <refpurpose>Allow setting the DC level sent to the antenna subsystem.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>enum fe_sec_voltage *<parameter>voltage</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_VOLTAGE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>voltage</parameter></term> + <listitem> + <para>pointer to &fe-sec-voltage;</para> + <para>Valid values are described at &fe-sec-voltage;.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + +<para>This ioctl allows to set the DC voltage level sent through the antenna + cable to 13V, 18V or off.</para> +<para>Usually, a satellite antenna subsystems require that the digital TV + device to send a DC voltage to feed power to the LNBf. Depending on the + LNBf type, the polarization or the intermediate frequency (IF) of the LNBf + can controlled by the voltage level. Other devices (for example, the ones + that implement DISEqC and multipoint LNBf's don't need to control the + voltage level, provided that either 13V or 18V is sent to power up the + LNBf.</para> +<para>NOTE: if more than one device is connected to the same antenna, + setting a voltage level may interfere on other devices, as they may lose + the capability of setting polarization or IF. So, on those + cases, setting the voltage to SEC_VOLTAGE_OFF while the device is not is + used is recommended.</para> + +&return-value-dvb; +</refsect1> + +</refentry> diff --git a/kernel/Documentation/DocBook/media/dvb/frontend.xml b/kernel/Documentation/DocBook/media/dvb/frontend.xml index 8a6a6ff27..01210b33c 100644 --- a/kernel/Documentation/DocBook/media/dvb/frontend.xml +++ b/kernel/Documentation/DocBook/media/dvb/frontend.xml @@ -1,485 +1,112 @@ <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 +<para>The DVB frontend API was designed to support three types of delivery systems:</para> +<itemizedlist> + <listitem><para>Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, DTMB, CMMB</para></listitem> + <listitem><para>Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C</para></listitem> + <listitem><para>Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS</para></listitem> +</itemizedlist> +<para>The DVB frontend controls several sub-devices including:</para> +<itemizedlist> + <listitem><para>Tuner</para></listitem> + <listitem><para>Digital TV demodulator</para></listitem> + <listitem><para>Low noise amplifier (LNA)</para></listitem> + <listitem><para>Satellite Equipment Control (SEC) hardware (only for Satellite).</para></listitem> +</itemizedlist> +<para>The frontend can be accessed through + <constant>/dev/dvb/adapter?/frontend?</constant>. Data types and + ioctl definitions can be accessed by including + <constant>linux/dvb/frontend.h</constant> in your application. +</para> + +<para>NOTE: Transmission via the internet (DVB-IP) + is not yet handled by this API but a future extension is possible.</para> +<para>On Satellite systems, the API support for the Satellite Equipment Control + (SEC) allows to power control and to send/receive signals to control the + antenna subsystem, selecting the polarization and choosing the Intermediate + Frequency IF) of the Low Noise Block Converter Feed Horn (LNBf). It + supports the DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) +specification is available at <ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</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="fe-type-t"> -<title>Frontend type</title> - -<para>For historical reasons, frontend types are named by the type of modulation used in -transmission. The fontend types are given by fe_type_t type, defined as:</para> - -<table pgwide="1" frame="none" id="fe-type"> -<title>Frontend types</title> -<tgroup cols="3"> - &cs-def; - <thead> - <row> - <entry>fe_type</entry> - <entry>Description</entry> - <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="FE_QPSK"><constant>FE_QPSK</constant></entry> - <entry>For DVB-S standard</entry> - <entry><constant>SYS_DVBS</constant></entry> - </row> - <row> - <entry id="FE_QAM"><constant>FE_QAM</constant></entry> - <entry>For DVB-C annex A standard</entry> - <entry><constant>SYS_DVBC_ANNEX_A</constant></entry> - </row> - <row> - <entry id="FE_OFDM"><constant>FE_OFDM</constant></entry> - <entry>For DVB-T standard</entry> - <entry><constant>SYS_DVBT</constant></entry> - </row> - <row> - <entry id="FE_ATSC"><constant>FE_ATSC</constant></entry> - <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry> - <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry> - </row> -</tbody></tgroup></table> - -<para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're -supported via the new <link linkend="FE_GET_SET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter. -</para> - -<para>The usage of this field is deprecated, as it doesn't report all supported standards, and -will provide an incomplete information for frontends that support multiple delivery systems. -Please use <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead.</para> -</section> - -<section id="fe-caps-t"> -<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_8VSB = 0x200000, - FE_CAN_16VSB = 0x400000, - FE_HAS_EXTENDED_CAPS = 0x800000, - FE_CAN_MULTISTREAM = 0x4000000, - FE_CAN_TURBO_FEC = 0x8000000, - FE_CAN_2G_MODULATION = 0x10000000, - FE_NEEDS_BENDING = 0x20000000, - FE_CAN_RECOVER = 0x40000000, - FE_CAN_MUTE_TS = 0x80000000 - } fe_caps_t; -</programlisting> -</section> - -<section id="dvb-frontend-info"> -<title>frontend information</title> - -<para>Information about the frontend ca be queried with - <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</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="dvb-diseqc-master-cmd"> -<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" id="dvb-diseqc-slave-reply"> -<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="fe-sec-voltage-t"> -<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="fe-sec-tone-mode-t"> -<title>SEC continuous tone</title> +<section id="query-dvb-frontend-info"> +<title>Querying frontend information</title> -<para>The continuous 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> +<para>Usually, the first thing to do when the frontend is opened is to + check the frontend capabilities. This is done using <link linkend="FE_GET_INFO">FE_GET_INFO</link>. This ioctl will enumerate + the DVB API version and other characteristics about the frontend, and + can be opened either in read only or read/write mode.</para> </section> -<section id="fe-sec-mini-cmd-t"> -<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="fe-status-t"> -<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, - FE_HAS_CARRIER = 0x02, - FE_HAS_VITERBI = 0x04, - FE_HAS_SYNC = 0x08, - FE_HAS_LOCK = 0x10, - FE_TIMEDOUT = 0x20, - FE_REINIT = 0x40, -} fe_status_t; -</programlisting> -<para>to indicate the current state and/or state changes of the frontend hardware: -</para> - -<informaltable><tgroup cols="2"><tbody> -<row> -<entry align="char">FE_HAS_SIGNAL</entry> -<entry align="char">The frontend has found something above the noise level</entry> -</row><row> -<entry align="char">FE_HAS_CARRIER</entry> -<entry align="char">The frontend has found a DVB signal</entry> -</row><row> -<entry align="char">FE_HAS_VITERBI</entry> -<entry align="char">The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable</entry> -</row><row> -<entry align="char">FE_HAS_SYNC</entry> -<entry align="char">Synchronization bytes was found</entry> -</row><row> -<entry align="char">FE_HAS_LOCK</entry> -<entry align="char">The DVB were locked and everything is working</entry> -</row><row> -<entry align="char">FE_TIMEDOUT</entry> -<entry align="char">no lock within the last about 2 seconds</entry> -</row><row> -<entry align="char">FE_REINIT</entry> -<entry align="char">The frontend was reinitialized, application is -recommended to reset DiSEqC, tone and parameters</entry> -</row> -</tbody></tgroup></informaltable> +<section id="dvb-fe-read-status"> +<title>Querying frontend status and statistics</title> +<para>Once <link linkend="FE_GET_PROPERTY"><constant>FE_SET_PROPERTY</constant></link> + is called, the frontend will run a kernel thread that will periodically + check for the tuner lock status and provide statistics about the quality + of the signal.</para> +<para>The information about the frontend tuner locking status can be queried + using <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>.</para> +<para>Signal statistics are provided via <link linkend="FE_GET_PROPERTY"><constant>FE_GET_PROPERTY</constant></link>. + Please note that several statistics require the demodulator to be fully + locked (e. g. with FE_HAS_LOCK bit set). See + <link linkend="frontend-stat-properties">Frontend statistics indicators</link> + for more details.</para> </section> -<section id="dvb-frontend-parameters"> -<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.</para> -<para>The struct <constant>dvb_frontend_parameters</constant> uses an -union with specific per-system parameters. However, as newer delivery systems -required more data, the structure size weren't enough to fit, and just -extending its size would break the existing applications. So, those parameters -were replaced by the usage of <link linkend="FE_GET_SET_PROPERTY"> -<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The -new API is flexible enough to add new parameters to existing delivery systems, -and to add newer delivery systems.</para> -<para>So, newer applications should use <link linkend="FE_GET_SET_PROPERTY"> -<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in -order to be able to support the newer System Delivery like DVB-S2, DVB-T2, -DVB-C2, ISDB, etc.</para> -<para>All kinds of parameters are combined as an union in the FrontendParameters structure: -<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; - struct dvb_vsb_parameters vsb; - } u; -}; -</programlisting></para> -<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 <constant>frequency</constant> specifies the absolute frequency and is given in Hz. -</para> - -<section id="dvb-qpsk-parameters"> -<title>QPSK parameters</title> -<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</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> -</section> -<section id="dvb-qam-parameters"> -<title>QAM parameters</title> -<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</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> -</section> -<section id="dvb-vsb-parameters"> -<title>VSB parameters</title> -<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para> -<programlisting> -struct dvb_vsb_parameters { - fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ -}; -</programlisting> -</section> -<section id="dvb-ofdm-parameters"> -<title>OFDM parameters</title> -<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</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> -</section> -<section id="fe-spectral-inversion-t"> -<title>frontend spectral inversion</title> -<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> -</section> -<section id="fe-code-rate-t"> -<title>frontend code rate</title> -<para>The possible values for the <constant>fec_inner</constant> field used on -<link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and -<link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> 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, - FEC_3_5, - FEC_9_10, -} 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> -</section> -<section id="fe-modulation-t"> -<title>frontend modulation type for QAM, OFDM and VSB</title> -<para>For cable and terrestrial frontends, e. g. for -<link linkend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>, -<link linkend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and -<link linkend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>, -it needs 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, - VSB_8, - VSB_16, - PSK_8, - APSK_16, - APSK_32, - DQPSK, - } fe_modulation_t; -</programlisting> -</section> -<section> -<title>More OFDM parameters</title> -<section id="fe-transmit-mode-t"> -<title>Number of carriers per channel</title> -<programlisting> -typedef enum fe_transmit_mode { - TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K, - TRANSMISSION_MODE_AUTO, - TRANSMISSION_MODE_4K, - TRANSMISSION_MODE_1K, - TRANSMISSION_MODE_16K, - TRANSMISSION_MODE_32K, - } fe_transmit_mode_t; -</programlisting> -</section> -<section id="fe-bandwidth-t"> -<title>frontend bandwidth</title> -<programlisting> -typedef enum fe_bandwidth { - BANDWIDTH_8_MHZ, - BANDWIDTH_7_MHZ, - BANDWIDTH_6_MHZ, - BANDWIDTH_AUTO, - BANDWIDTH_5_MHZ, - BANDWIDTH_10_MHZ, - BANDWIDTH_1_712_MHZ, -} fe_bandwidth_t; -</programlisting> -</section> -<section id="fe-guard-interval-t"> -<title>frontend guard inverval</title> -<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, - GUARD_INTERVAL_1_128, - GUARD_INTERVAL_19_128, - GUARD_INTERVAL_19_256, -} fe_guard_interval_t; -</programlisting> -</section> -<section id="fe-hierarchy-t"> -<title>frontend hierarchy</title> -<programlisting> -typedef enum fe_hierarchy { - HIERARCHY_NONE, - HIERARCHY_1, - HIERARCHY_2, - HIERARCHY_4, - HIERARCHY_AUTO - } fe_hierarchy_t; -</programlisting> -</section> -</section> - -</section> - -<section id="dvb-frontend-event"> -<title>frontend events</title> - <programlisting> - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; -</programlisting> - </section> -</section> - +&sub-dvbproperty; <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) +<refentry id="frontend_f_open"> + <refmeta> + <refentrytitle>DVB frontend open()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>fe-open</refname> + <refpurpose>Open a frontend device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>open</function></funcdef> + <paramdef>const char *<parameter>device_name</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>device_name</parameter></term> + <listitem> + <para>Device to be opened.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para>Open flags. Access can either be + <constant>O_RDWR</constant> or <constant>O_RDONLY</constant>.</para> + <para>Multiple opens are allowed with <constant>O_RDONLY</constant>. In this mode, only query and read ioctls are allowed.</para> + <para>Only one open is allowed in <constant>O_RDWR</constant>. In this mode, all ioctls are allowed.</para> + <para>When the <constant>O_NONBLOCK</constant> flag is given, the system calls may return &EAGAIN; when no data is available or when the device driver is temporarily busy.</para> + <para>Other flags have no effect.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Description</title> + <para>This system call opens a named frontend device (<constant>/dev/dvb/adapter?/frontend?</constant>) for subsequent use. Usually the first thing to do after a successful open is to find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para> <para>The device can be opened in read-only mode, which only allows monitoring of @@ -497,1052 +124,146 @@ typedef enum fe_hierarchy { 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></tbody></tgroup></informaltable> -<para>RETURN VALUE</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"> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success <function>open</function> returns the new file +descriptor. On error -1 is returned, and the <varname>errno</varname> +variable is set appropriately. Possible error codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EACCES</errorcode></term> + <listitem> + <para>The caller has no permission to access the +device.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EBUSY</errorcode></term> + <listitem> + <para>The the device driver is already in use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENXIO</errorcode></term> + <listitem> + <para>No device corresponding to this device special file +exists.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>Not enough kernel memory was available to complete the +request.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EMFILE</errorcode></term> + <listitem> + <para>The process already has the maximum number of +files open.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENFILE</errorcode></term> + <listitem> + <para>The limit on the total number of files open on the +system has been reached.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENODEV</errorcode></term> + <listitem> + <para>The device got removed.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> + +<refentry id="frontend_f_close"> + <refmeta> + <refentrytitle>DVB frontend close()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>fe-close</refname> + <refpurpose>Close a frontend device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>close</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> <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></tbody></tgroup></informaltable> -<para>RETURN VALUE</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="FE_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 = <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>, - 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 <link linkend="FE_READ_STATUS">FE_READ_STATUS</link> 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>RETURN VALUE</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="FE_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 = <link linkend="FE_READ_BER">FE_READ_BER</link>, - 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 <link linkend="FE_READ_BER">FE_READ_BER</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_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 = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_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 <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint16_t *snr</para> -</entry><entry - align="char"> -<para>The signal-to-noise ratio is stored into *snr.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_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 = - <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_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 <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint16_t *strength</para> -</entry><entry - align="char"> -<para>The signal strength value is stored into *strength.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_UNCORRECTED_BLOCKS"> -<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 = - <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, 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 <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> 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> - -&return-value-dvb; -</section> - -<section id="FE_SET_FRONTEND"> -<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 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and - FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> 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 = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>, - 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 <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><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="FE_GET_FRONTEND"> -<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 = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>, - 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 <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><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="FE_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 - <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> - 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 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> 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> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><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"> -<para>Overflow in event queue - one or more events were lost.</para> -</entry> -</row></tbody></tgroup></informaltable> -</section> - -<section id="FE_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 = <link linkend="FE_GET_INFO">FE_GET_INFO</link>, 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 <link linkend="FE_GET_INFO">FE_GET_INFO</link> 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> -&return-value-dvb; -</section> - -<section id="FE_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 = - <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link>);</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 <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link> for this - command.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_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></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link>, 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 <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; +</refsect1> + <refsect1> + <title>Return Value</title> + + <para>The function returns <returnvalue>0</returnvalue> on +success, <returnvalue>-1</returnvalue> on failure and the +<varname>errno</varname> is set appropriately. Possible error +codes:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid open file +descriptor.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> + +&sub-fe-get-info; +&sub-fe-read-status; +&sub-fe-get-property; +&sub-fe-diseqc-reset-overload; +&sub-fe-diseqc-send-master-cmd; +&sub-fe-diseqc-recv-slave-reply; +&sub-fe-diseqc-send-burst; +&sub-fe-set-tone; +&sub-fe-set-voltage; +&sub-fe-enable-high-lnb-voltage; +&sub-fe-set-frontend-tune-mode; + +</section> + +<section id="frontend_legacy_dvbv3_api"> +<title>DVB Frontend legacy API (a. k. a. DVBv3)</title> +<para>The usage of this API is deprecated, as it doesn't support all digital + TV standards, doesn't provide good statistics measurements and provides + incomplete information. This is kept only to support legacy applications.</para> + +&sub-frontend_legacy_api; </section> - -<section id="FE_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></tbody></tgroup></informaltable> - -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link>, 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 <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link> 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></tbody></tgroup></informaltable> -&return-value-dvb; -</section> - -<section id="FE_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></tbody></tgroup></informaltable> - -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link>, 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 <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_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 = <link linkend="FE_SET_TONE">FE_SET_TONE</link>, - 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 <link linkend="FE_SET_TONE">FE_SET_TONE</link> 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></tbody></tgroup></informaltable> -&return-value-dvb; -</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 = <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link>, - 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 <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_ENABLE_HIGH_LNB_VOLTAGE"> -<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 = - <link linkend="FE_ENABLE_HIGH_LNB_VOLTAGE">FE_ENABLE_HIGH_LNB_VOLTAGE</link>, 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 <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> 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></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_SET_FRONTEND_TUNE_MODE"> -<title>FE_SET_FRONTEND_TUNE_MODE</title> -<para>DESCRIPTION</para> -<informaltable><tgroup cols="1"><tbody><row> -<entry align="char"> -<para>Allow setting tuner mode flags to the frontend.</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 = -<link linkend="FE_SET_FRONTEND_TUNE_MODE">FE_SET_FRONTEND_TUNE_MODE</link>, unsigned int flags);</para> -</entry> -</row></tbody></tgroup></informaltable> - -<para>PARAMETERS</para> -<informaltable><tgroup cols="2"><tbody><row> -<entry align="char"> - <para>unsigned int flags</para> -</entry> -<entry align="char"> -<para> -FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "normal" tuning behaviour. Additionally, there will be no automatic monitoring of the lock status, and hence no frontend events will be generated. If a frontend device is closed, this flag will be automatically turned off when the device is reopened read-write. -</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_DISHNETWORK_SEND_LEGACY_CMD"> - <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title> -<para>DESCRIPTION</para> -<informaltable><tgroup cols="1"><tbody><row> -<entry align="char"> -<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para> -<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para> -<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</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 = - <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para> -</entry> -</row></tbody></tgroup></informaltable> - -<para>PARAMETERS</para> -<informaltable><tgroup cols="2"><tbody><row> -<entry align="char"> - <para>unsigned long cmd</para> -</entry> -<entry align="char"> -<para> -sends the specified raw cmd to the dish via DISEqC. -</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -</section> - -&sub-dvbproperty; diff --git a/kernel/Documentation/DocBook/media/dvb/frontend_legacy_api.xml b/kernel/Documentation/DocBook/media/dvb/frontend_legacy_api.xml new file mode 100644 index 000000000..8fadf3a4b --- /dev/null +++ b/kernel/Documentation/DocBook/media/dvb/frontend_legacy_api.xml @@ -0,0 +1,654 @@ +<section id="frontend_legacy_types"> +<title>Frontend Legacy Data Types</title> + +<section id="fe-type-t"> +<title>Frontend type</title> + +<para>For historical reasons, frontend types are named by the type of modulation + used in transmission. The fontend types are given by fe_type_t type, defined as:</para> + +<table pgwide="1" frame="none" id="fe-type"> +<title>Frontend types</title> +<tgroup cols="3"> + &cs-def; + <thead> + <row> + <entry>fe_type</entry> + <entry>Description</entry> + <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="FE-QPSK"><constant>FE_QPSK</constant></entry> + <entry>For DVB-S standard</entry> + <entry><constant>SYS_DVBS</constant></entry> + </row> + <row> + <entry id="FE-QAM"><constant>FE_QAM</constant></entry> + <entry>For DVB-C annex A standard</entry> + <entry><constant>SYS_DVBC_ANNEX_A</constant></entry> + </row> + <row> + <entry id="FE-OFDM"><constant>FE_OFDM</constant></entry> + <entry>For DVB-T standard</entry> + <entry><constant>SYS_DVBT</constant></entry> + </row> + <row> + <entry id="FE-ATSC"><constant>FE_ATSC</constant></entry> + <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry> + <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry> + </row> +</tbody></tgroup></table> + +<para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're +supported via the new <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter. +</para> + +<para>In the old days, &dvb-frontend-info; used to contain + <constant>fe_type_t</constant> field to indicate the delivery systems, + filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this is + still filled to keep backward compatibility, the usage of this + field is deprecated, as it can report just one delivery system, but some + devices support multiple delivery systems. Please use + <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead. +</para> +<para>On devices that support multiple delivery systems, + &dvb-frontend-info;::<constant>fe_type_t</constant> is filled with the + currently standard, as selected by the last call to + <link linkend="FE_GET_PROPERTY">FE_SET_PROPERTY</link> + using the &DTV-DELIVERY-SYSTEM; property.</para> +</section> + +<section id="fe-bandwidth-t"> +<title>Frontend bandwidth</title> + +<table pgwide="1" frame="none" id="fe-bandwidth"> + <title>enum fe_bandwidth</title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry id="BANDWIDTH-AUTO"><constant>BANDWIDTH_AUTO</constant></entry> + <entry>Autodetect bandwidth (if supported)</entry> + </row><row> + <entry id="BANDWIDTH-1-712-MHZ"><constant>BANDWIDTH_1_712_MHZ</constant></entry> + <entry>1.712 MHz</entry> + </row><row> + <entry id="BANDWIDTH-5-MHZ"><constant>BANDWIDTH_5_MHZ</constant></entry> + <entry>5 MHz</entry> + </row><row> + <entry id="BANDWIDTH-6-MHZ"><constant>BANDWIDTH_6_MHZ</constant></entry> + <entry>6 MHz</entry> + </row><row> + <entry id="BANDWIDTH-7-MHZ"><constant>BANDWIDTH_7_MHZ</constant></entry> + <entry>7 MHz</entry> + </row><row> + <entry id="BANDWIDTH-8-MHZ"><constant>BANDWIDTH_8_MHZ</constant></entry> + <entry>8 MHz</entry> + </row><row> + <entry id="BANDWIDTH-10-MHZ"><constant>BANDWIDTH_10_MHZ</constant></entry> + <entry>10 MHz</entry> + </row> + </tbody> + </tgroup> +</table> + +</section> + +<section id="dvb-frontend-parameters"> +<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.</para> +<para>The struct <constant>dvb_frontend_parameters</constant> uses an +union with specific per-system parameters. However, as newer delivery systems +required more data, the structure size weren't enough to fit, and just +extending its size would break the existing applications. So, those parameters +were replaced by the usage of <link linkend="FE_GET_PROPERTY"> +<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The +new API is flexible enough to add new parameters to existing delivery systems, +and to add newer delivery systems.</para> +<para>So, newer applications should use <link linkend="FE_GET_PROPERTY"> +<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in +order to be able to support the newer System Delivery like DVB-S2, DVB-T2, +DVB-C2, ISDB, etc.</para> +<para>All kinds of parameters are combined as an union in the FrontendParameters structure: +<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; + struct dvb_vsb_parameters vsb; + } u; +}; +</programlisting></para> +<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 <constant>frequency</constant> specifies the absolute frequency and is given in Hz. +</para> + +<section id="dvb-qpsk-parameters"> +<title>QPSK parameters</title> +<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</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> +</section> + +<section id="dvb-qam-parameters"> +<title>QAM parameters</title> +<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</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> +</section> + +<section id="dvb-vsb-parameters"> +<title>VSB parameters</title> +<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para> +<programlisting> +struct dvb_vsb_parameters { + &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/ +}; +</programlisting> +</section> + +<section id="dvb-ofdm-parameters"> +<title>OFDM parameters</title> +<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</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> +</section> +</section> + +<section id="dvb-frontend-event"> +<title>frontend events</title> + <programlisting> + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; +</programlisting> + </section> +</section> + +<section id="frontend_legacy_fcalls"> +<title>Frontend Legacy Function Calls</title> + +<para>Those functions are defined at DVB version 3. The support is kept in + the kernel due to compatibility issues only. Their usage is strongly + not recommended</para> + +<section id="FE_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 = <link linkend="FE_READ_BER">FE_READ_BER</link>, + 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 <link linkend="FE_READ_BER">FE_READ_BER</link> 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></tbody></tgroup></informaltable> + +&return-value-dvb; +</section> + +<section id="FE_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 = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_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 <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>uint16_t *snr</para> +</entry><entry + align="char"> +<para>The signal-to-noise ratio is stored into *snr.</para> +</entry> + </row></tbody></tgroup></informaltable> + +&return-value-dvb; +</section> + +<section id="FE_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 = + <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_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 <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>uint16_t *strength</para> +</entry><entry + align="char"> +<para>The signal strength value is stored into *strength.</para> +</entry> + </row></tbody></tgroup></informaltable> + +&return-value-dvb; +</section> + +<section id="FE_READ_UNCORRECTED_BLOCKS"> +<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 = + <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, 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 <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> 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> + +&return-value-dvb; +</section> + +<section id="FE_SET_FRONTEND"> +<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 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and + FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> 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 = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>, + 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 <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> 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></tbody></tgroup></informaltable> + +&return-value-dvb; +<informaltable><tgroup cols="2"><tbody><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="FE_GET_FRONTEND"> +<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 = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>, + 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 <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> 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></tbody></tgroup></informaltable> + +&return-value-dvb; +<informaltable><tgroup cols="2"><tbody><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="FE_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 + <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> + 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 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> 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> + +&return-value-dvb; +<informaltable><tgroup cols="2"><tbody><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"> +<para>Overflow in event queue - one or more events were lost.</para> +</entry> +</row></tbody></tgroup></informaltable> +</section> + +<section id="FE_DISHNETWORK_SEND_LEGACY_CMD"> + <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title> +<para>DESCRIPTION</para> +<informaltable><tgroup cols="1"><tbody><row> +<entry align="char"> +<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para> +<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para> +<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</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 = + <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para> +</entry> +</row></tbody></tgroup></informaltable> + +<para>PARAMETERS</para> +<informaltable><tgroup cols="2"><tbody><row> +<entry align="char"> + <para>unsigned long cmd</para> +</entry> +<entry align="char"> +<para> +sends the specified raw cmd to the dish via DISEqC. +</para> +</entry> + </row></tbody></tgroup></informaltable> + +&return-value-dvb; +</section> + +</section> diff --git a/kernel/Documentation/DocBook/media/dvb/intro.xml b/kernel/Documentation/DocBook/media/dvb/intro.xml index 2048b53d1..51db15648 100644 --- a/kernel/Documentation/DocBook/media/dvb/intro.xml +++ b/kernel/Documentation/DocBook/media/dvb/intro.xml @@ -129,43 +129,42 @@ 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 +<para>All devices can be found in the <constant>/dev</constant> +tree under <constant>/dev/dvb</constant>. The individual devices are called:</para> <itemizedlist> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para> +<para><constant>/dev/dvb/adapterN/audioM</constant>,</para> </listitem> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para> +<para><constant>/dev/dvb/adapterN/videoM</constant>,</para> </listitem> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para> +<para><constant>/dev/dvb/adapterN/frontendM</constant>,</para> </listitem> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para> +<para><constant>/dev/dvb/adapterN/netM</constant>,</para> </listitem> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para> +<para><constant>/dev/dvb/adapterN/demuxM</constant>,</para> </listitem> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/dvrM</emphasis>,</para> +<para><constant>/dev/dvb/adapterN/dvrM</constant>,</para> </listitem> <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> +<para><constant>/dev/dvb/adapterN/caM</constant>,</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> +adapter, starting from 0, too. We will omit the “ +<constant>/dev/dvb/adapterN/</constant>” in the further discussion +of these devices.</para> <para>More details about the data structures and function calls of all the devices are described in the following chapters.</para> @@ -202,10 +201,10 @@ a partial path like:</para> </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 5.8</emphasis>. +additional include file +<constant>linux/dvb/version.h</constant> exists, which defines the +constant <constant>DVB_API_VERSION</constant>. This document +describes <constant>DVB_API_VERSION 5.10</constant>. </para> </section> diff --git a/kernel/Documentation/DocBook/media/dvb/kdapi.xml b/kernel/Documentation/DocBook/media/dvb/kdapi.xml deleted file mode 100644 index 6c11ec52c..000000000 --- a/kernel/Documentation/DocBook/media/dvb/kdapi.xml +++ /dev/null @@ -1,2309 +0,0 @@ -<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-core</emphasis>. -</para> -<para>Maintainer note: This section must be reviewed. It is probably out of date. -</para> - -<section id="kernel_demux_data_types"> -<title>Kernel Demux Data Types</title> - - -<section id="dmx_success_t"> -<title>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 id="ts_filter_types"> -<title>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 id="dmx_ts_pes_t"> -<title>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 id="demux_demux_t"> -<title>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 id="demux_directory"> -<title>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 id="demux_directory_api"> -<title>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>dmx_register_demux()</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>dmx_unregister_demux()</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>dmx_get_demuxes()</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 id="demux_api"> -<title>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 id="kdapi_fopen"> -<title>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 id="kdapi_fclose"> -<title>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 id="kdapi_fwrite"> -<title>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>allocate_ts_feed()</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>release_ts_feed()</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>allocate_section_feed()</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>release_section_feed()</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>descramble_mac_address()</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>descramble_section_payload()</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>add_frontend()</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>remove_frontend()</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>get_frontends()</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>connect_frontend()</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>disconnect_frontend()</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 id="demux_callback_api"> -<title>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>dmx_ts_cb()</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>dmx_section_cb()</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 id="ts_feed_api"> -<title>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>set()</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>start_filtering()</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>stop_filtering()</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 id="section_feed_api"> -<title>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> -<section id="kdapi_set"> -<title>set()</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>allocate_filter()</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>release_filter()</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>start_filtering()</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></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>stop_filtering()</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> diff --git a/kernel/Documentation/DocBook/media/dvb/net.xml b/kernel/Documentation/DocBook/media/dvb/net.xml index a193e8694..d2e44b7e0 100644 --- a/kernel/Documentation/DocBook/media/dvb/net.xml +++ b/kernel/Documentation/DocBook/media/dvb/net.xml @@ -1,156 +1,238 @@ <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 id="dvb_net_types"> -<title>DVB Net Data Types</title> - -<section id="dvb-net-if"> -<title>struct dvb_net_if</title> -<programlisting> -struct dvb_net_if { - __u16 pid; - __u16 if_num; - __u8 feedtype; -#define DVB_NET_FEEDTYPE_MPE 0 /⋆ multi protocol encapsulation ⋆/ -#define DVB_NET_FEEDTYPE_ULE 1 /⋆ ultra lightweight encapsulation ⋆/ -}; -</programlisting> -</section> +<para>The DVB net device controls the mapping of data packages that are + part of a transport stream to be mapped into a virtual network interface, + visible through the standard Linux network protocol stack.</para> +<para>Currently, two encapsulations are supported:</para> +<itemizedlist> + <listitem><para><ulink url="http://en.wikipedia.org/wiki/Multiprotocol_Encapsulation"> + Multi Protocol Encapsulation (MPE)</ulink></para></listitem> + <listitem><para><ulink url="http://en.wikipedia.org/wiki/Unidirectional_Lightweight_Encapsulation"> + Ultra Lightweight Encapsulation (ULE)</ulink></para></listitem> +</itemizedlist> + +<para>In order to create the Linux virtual network interfaces, an application + needs to tell to the Kernel what are the PIDs and the encapsulation types + that are present on the transport stream. This is done through + <constant>/dev/dvb/adapter?/net?</constant> device node. + The data will be available via virtual <constant>dvb?_?</constant> + network interfaces, and will be controled/routed via the standard + ip tools (like ip, route, netstat, ifconfig, etc).</para> +<para> Data types and and ioctl definitions are defined via + <constant>linux/dvb/net.h</constant> header.</para> -</section> <section id="net_fcalls"> <title>DVB net Function Calls</title> -<para>To be written… -</para> - -<section id="NET_ADD_IF" -role="subsection"><title>NET_ADD_IF</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = NET_ADD_IF, - struct dvb_net_if *if);</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 NET_ADD_IF for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dvb_net_if *if -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> + + +<refentry id="NET_ADD_IF"> + <refmeta> + <refentrytitle>ioctl NET_ADD_IF</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>NET_ADD_IF</refname> + <refpurpose>Creates a new network interface for a given Packet ID.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_TONE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>net_if</parameter></term> + <listitem> + <para>pointer to &dvb-net-if;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + +<para>The NET_ADD_IF ioctl system call selects the Packet ID (PID) that + contains a TCP/IP traffic, the type of encapsulation to be used (MPE or ULE) + and the interface number for the new interface to be created. When the + system call successfully returns, a new virtual network interface is created.</para> +<para>The &dvb-net-if;::ifnum field will be filled with the number of the + created interface.</para> + &return-value-dvb; -</section> +</refsect1> + +<refsect1 id="dvb-net-if-t"> +<title>struct <structname>dvb_net_if</structname> description</title> + +<table pgwide="1" frame="none" id="dvb-net-if"> + <title>struct <structname>dvb_net_if</structname></title> + <tgroup cols="2"> + &cs-def; + <thead> + <row> + <entry>ID</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry align="char">pid</entry> + <entry align="char">Packet ID (PID) of the MPEG-TS that contains + data</entry> + </row><row> + <entry align="char">ifnum</entry> + <entry align="char">number of the DVB interface.</entry> + </row><row> + <entry align="char">feedtype</entry> + <entry align="char">Encapsulation type of the feed. It can be: + <constant>DVB_NET_FEEDTYPE_MPE</constant> for MPE encoding + or + <constant>DVB_NET_FEEDTYPE_ULE</constant> for ULE encoding. + </entry> + </row> + </tbody> + </tgroup> +</table> +</refsect1> +</refentry> + +<refentry id="NET_REMOVE_IF"> + <refmeta> + <refentrytitle>ioctl NET_REMOVE_IF</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>NET_REMOVE_IF</refname> + <refpurpose>Removes a network interface.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>int <parameter>ifnum</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_TONE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>net_if</parameter></term> + <listitem> + <para>number of the interface to be removed</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + +<para>The NET_REMOVE_IF ioctl deletes an interface previously created + via &NET-ADD-IF;.</para> -<section id="NET_REMOVE_IF" -role="subsection"><title>NET_REMOVE_IF</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = NET_REMOVE_IF); -</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 NET_REMOVE_IF for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> &return-value-dvb; -</section> +</refsect1> +</refentry> + + +<refentry id="NET_GET_IF"> + <refmeta> + <refentrytitle>ioctl NET_GET_IF</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>NET_GET_IF</refname> + <refpurpose>Read the configuration data of an interface created via + &NET-ADD-IF;.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct dvb_net_if *<parameter>net_if</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fe_fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>FE_SET_TONE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>net_if</parameter></term> + <listitem> + <para>pointer to &dvb-net-if;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + +<para>The NET_GET_IF ioctl uses the interface number given by the + &dvb-net-if;::ifnum field and fills the content of &dvb-net-if; with + the packet ID and encapsulation type used on such interface. If the + interface was not created yet with &NET-ADD-IF;, it will return -1 and + fill the <constant>errno</constant> with <constant>EINVAL</constant> + error code.</para> -<section id="NET_GET_IF" -role="subsection"><title>NET_GET_IF</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is undocumented. Documentation is welcome.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = NET_GET_IF, - struct dvb_net_if *if);</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 NET_GET_IF for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dvb_net_if *if -</para> -</entry><entry - align="char"> -<para>Undocumented.</para> -</entry> - </row></tbody></tgroup></informaltable> &return-value-dvb; -</section> +</refsect1> +</refentry> </section> diff --git a/kernel/Documentation/DocBook/media/dvb/video.xml b/kernel/Documentation/DocBook/media/dvb/video.xml index 3ea1ca7e7..71547fcd7 100644 --- a/kernel/Documentation/DocBook/media/dvb/video.xml +++ b/kernel/Documentation/DocBook/media/dvb/video.xml @@ -1,12 +1,12 @@ <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 +can be accessed through <emphasis role="bold">/dev/dvb/adapter0/video0</emphasis>. Data types and and +ioctl definitions can be accessed by including <emphasis role="bold">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 +associated video4linux device, e.g. <emphasis role="bold">/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 @@ -24,7 +24,7 @@ have been created to replace that functionality.</para> <section id="video-format-t"> <title>video_format_t</title> -<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by +<para>The <constant>video_format_t</constant> data type defined by </para> <programlisting> typedef enum { @@ -74,7 +74,7 @@ typedef enum { </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 +is selected the stream comes from the application through the <emphasis role="bold">write()</emphasis> system call. </para> </section> |