path: root/Documentation/DocBook/media/dvb/frontend.xml

<title>DVB Frontend API</title>

<para>The DVB frontend API was designed to support three types of delivery systems:</para>
<itemizedlist>
    <listitem>Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, DTMB, CMMB</listitem>
    <listitem>Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C</listitem>
    <listitem>Satellital systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS</listitem>
</itemizedlist>
<para>The DVB frontend controls several sub-devices including:</para>
<itemizedlist>
    <listitem>Tuner</listitem>,
    <listitem>Digital TV demodulator</listitem>
    <listitem>Low noise amplifier (LNA)</listitem>
    <listitem>Satellite Equipment Control (SEC) hardware (only for Satellite).</listitem>
</itemizedlist>
<para>The frontend can be accessed through
    <emphasis role="bold">/dev/dvb/adapter?/frontend?</emphasis>. Data types and
    ioctl definitions can be accessed by including
    <emphasis role="bold">linux/dvb/frontend.h</emphasis> 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 Satellital 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>


<section id="query-dvb-frontend-info">
<title>Querying frontend information</title>

<para>Information about the frontend can be queried with
	<link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
</section>

&sub-fe-get-info;

<section id="dvb-fe-read-status">
<title>Querying frontend status</title>

<para>Information about the frontend tuner locking status can be queried with
	<link linkend="FE_READ_STATUS">FE_READ_STATUS</link>.</para>
</section>

&sub-fe-read-status;

&sub-dvbproperty;

<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]; /&#x22C6;  { framing, address, command, data[3] } &#x22C6;/
	uint8_t msg_len; /&#x22C6;  valid values are 3...6  &#x22C6;/
	};
</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]; /&#x22C6;  { framing, data [3] } &#x22C6;/
	uint8_t msg_len; /&#x22C6;  valid values are 0...4, 0 means no msg  &#x22C6;/
	int     timeout; /&#x22C6;  return from ioctl after timeout ms with &#x22C6;/
	};                       /&#x22C6;  errorcode when no message was received  &#x22C6;/
</programlisting>
</section>

<section id="fe-sec-tone-mode-t">
<title>SEC continuous tone</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>
</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-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 id="frontend_fcalls">
<title>Frontend Function Calls</title>

<section id="frontend_f_open">
<title>open()</title>
<para>DESCRIPTION</para>
<informaltable><tgroup cols="1"><tbody><row>
<entry align="char">
<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
 for subsequent use. Usually the first thing to do after a successful open is to
 find out the frontend type with <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
 device status and statistics, or read/write mode, which allows any kind of use
 (e.g. performing tuning operations.)
</para>
<para>In a system with multiple front-ends, it is usually the case that multiple devices
 cannot be open in read/write mode simultaneously. As long as a front-end
 device is opened in read/write mode, other open() calls in read/write mode will
 either fail or block, depending on whether non-blocking or blocking mode was
 specified. A front-end device opened in blocking mode can later be put into
 non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
 system call. This is a standard system call, documented in the Linux manual
 page for fcntl. When an open() call has succeeded, the device will be ready
 for use in the specified mode. This implies that the corresponding hardware is
 powered up, and that other front-ends may have been powered down to make
 that possible.</para>
</entry>
 </row></tbody></tgroup></informaltable>

<para>SYNOPSIS</para>
<informaltable><tgroup cols="1"><tbody><row><entry
 align="char">
<para>int open(const char &#x22C6;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">
<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_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 &#x22C6;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;
</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 &#x22C6;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>

&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>