<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>Chapter 9. DVB Frontend API</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API" /><link rel="up" href="pt02.html" title="Part II. LINUX DVB API" /><link rel="prev" href="ch08s05.html" title="API include files" /><link rel="next" href="ch09s02.html" title="Frontend Function Calls" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. DVB Frontend API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch08s05.html">Prev</a> </td><th width="60%" align="center">Part II. LINUX DVB API</th><td width="20%" align="right"> <a accesskey="n" href="ch09s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 9. DVB Frontend API"><div class="titlepage"><div><div><h2 class="title"><a id="dvb_frontend"></a>Chapter 9. DVB Frontend API</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch09.html#frontend_types">Frontend Data Types</a></span></dt><dd><dl><dt><span class="section"><a href="ch09.html#frontend_type">frontend type</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_caps">frontend capabilities</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_info">frontend information</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_diseqc">diseqc master command</a></span></dt><dt><span class="section"><a href="ch09.html#id2837923">diseqc slave reply</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_diseqc_slave_reply">diseqc slave reply</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_sec_tone">SEC continuous tone</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_sec_burst">SEC tone burst</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_status">frontend status</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_params">frontend parameters</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_events">frontend events</a></span></dt></dl></dd><dt><span class="section"><a href="ch09s02.html">Frontend Function Calls</a></span></dt><dd><dl><dt><span class="section"><a href="ch09s02.html#frontend_f_open">open()</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_f_close">close()</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_read_status">FE_READ_STATUS</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_read_ber">FE_READ_BER</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_read_snr">FE_READ_SNR</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_read_signal_strength">FE_READ_SIGNAL_STRENGTH</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_read_ub">FE_READ_UNCORRECTED_BLOCKS</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_set_fe">FE_SET_FRONTEND</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_get_fe">FE_GET_FRONTEND</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_get_event">FE_GET_EVENT</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_get_info">FE_GET_INFO</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_diseqc_reset_overload">FE_DISEQC_RESET_OVERLOAD</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_diseqc_send_master_cmd">FE_DISEQC_SEND_MASTER_CMD</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_diseqc_recv_slave_reply">FE_DISEQC_RECV_SLAVE_REPLY</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_diseqc_send_burst">FE_DISEQC_SEND_BURST</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_set_tone">FE_SET_TONE</a></span></dt><dt><span class="section"><a href="ch09s02.html#fe_set_voltage">FE_SET_VOLTAGE</a></span></dt><dt><span class="section"><a href="ch09s02.html#frontend_enable_high_lnb_volt">FE_ENABLE_HIGH_LNB_VOLTAGE</a></span></dt></dl></dd><dt><span class="section"><a href="ch09s03.html">ISDB-T frontend</a></span></dt><dd><dl><dt><span class="section"><a href="ch09s03.html#isdbt-parms">Parameters that are common with DVB-T and ATSC</a></span></dt><dt><span class="section"><a href="ch09s03.html#isdbt-new-parms">ISDB-T only parameters</a></span></dt></dl></dd></dl></div><p>The DVB frontend device controls the tuner and DVB demodulator
hardware. It can be accessed through <span class="tt">/dev/dvb/adapter0/frontend0</span>. Data types and and
ioctl definitions can be accessed by including <span class="tt">linux/dvb/frontend.h</span> in your application.</p><p>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
<a class="ulink" href="http://www.eutelsat.com/satellites/4_5_5.html" target="_top">Eutelsat</a>.</p><p>Note that the DVB API may also be used for MPEG decoder-only PCI
cards, in which case there exists no frontend device.</p><div class="section" title="Frontend Data Types"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="frontend_types"></a>Frontend Data Types</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ch09.html#frontend_type">frontend type</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_caps">frontend capabilities</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_info">frontend information</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_diseqc">diseqc master command</a></span></dt><dt><span class="section"><a href="ch09.html#id2837923">diseqc slave reply</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_diseqc_slave_reply">diseqc slave reply</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_sec_tone">SEC continuous tone</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_sec_burst">SEC tone burst</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_status">frontend status</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_params">frontend parameters</a></span></dt><dt><span class="section"><a href="ch09.html#frontend_events">frontend events</a></span></dt></dl></div><div class="section" title="frontend type"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_type"></a>frontend type</h3></div></div></div><p>For historical reasons frontend types are named after the type of modulation used in
transmission.</p><pre class="programlisting">
typedef enum fe_type {
FE_QPSK, /⋆ DVB-S ⋆/
FE_QAM, /⋆ DVB-C ⋆/
FE_OFDM /⋆ DVB-T ⋆/
} fe_type_t;
</pre></div><div class="section" title="frontend capabilities"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_caps"></a>frontend capabilities</h3></div></div></div><p>Capabilities describe what a frontend can do. Some capabilities can only be supported for
a specific frontend type.</p><pre class="programlisting">
typedef enum fe_caps {
FE_IS_STUPID = 0,
FE_CAN_INVERSION_AUTO = 0x1,
FE_CAN_FEC_1_2 = 0x2,
FE_CAN_FEC_2_3 = 0x4,
FE_CAN_FEC_3_4 = 0x8,
FE_CAN_FEC_4_5 = 0x10,
FE_CAN_FEC_5_6 = 0x20,
FE_CAN_FEC_6_7 = 0x40,
FE_CAN_FEC_7_8 = 0x80,
FE_CAN_FEC_8_9 = 0x100,
FE_CAN_FEC_AUTO = 0x200,
FE_CAN_QPSK = 0x400,
FE_CAN_QAM_16 = 0x800,
FE_CAN_QAM_32 = 0x1000,
FE_CAN_QAM_64 = 0x2000,
FE_CAN_QAM_128 = 0x4000,
FE_CAN_QAM_256 = 0x8000,
FE_CAN_QAM_AUTO = 0x10000,
FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
FE_CAN_BANDWIDTH_AUTO = 0x40000,
FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
FE_CAN_HIERARCHY_AUTO = 0x100000,
FE_CAN_MUTE_TS = 0x80000000,
FE_CAN_CLEAN_SETUP = 0x40000000
} fe_caps_t;
</pre></div><div class="section" title="frontend information"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_info"></a>frontend information</h3></div></div></div><p>Information about the frontend ca be queried with FE_GET_INFO.</p><pre class="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;
};
</pre></div><div class="section" title="diseqc master command"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_diseqc"></a>diseqc master command</h3></div></div></div><p>A message sent from the frontend to DiSEqC capable equipment.</p><pre class="programlisting">
struct dvb_diseqc_master_cmd {
uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/
uint8_t msg_len; /⋆ valid values are 3...6 ⋆/
};
</pre></div><div class="section" title="diseqc slave reply"><div class="titlepage"><div><div><h3 class="title"><a id="id2837923"></a>diseqc slave reply</h3></div></div></div><p>A reply to the frontend from DiSEqC 2.0 capable equipment.</p><pre class="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 ⋆/
</pre></div><div class="section" title="diseqc slave reply"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_diseqc_slave_reply"></a>diseqc slave reply</h3></div></div></div><p>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.</p><pre class="programlisting">
typedef enum fe_sec_voltage {
SEC_VOLTAGE_13,
SEC_VOLTAGE_18
} fe_sec_voltage_t;
</pre></div><div class="section" title="SEC continuous tone"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_sec_tone"></a>SEC continuous tone</h3></div></div></div><p>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the
high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to
be switched consistently to the DiSEqC commands as described in the DiSEqC
spec.</p><pre class="programlisting">
typedef enum fe_sec_tone_mode {
SEC_TONE_ON,
SEC_TONE_OFF
} fe_sec_tone_mode_t;
</pre></div><div class="section" title="SEC tone burst"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_sec_burst"></a>SEC tone burst</h3></div></div></div><p>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.</p><pre class="programlisting">
typedef enum fe_sec_mini_cmd {
SEC_MINI_A,
SEC_MINI_B
} fe_sec_mini_cmd_t;
</pre><p></p></div><div class="section" title="frontend status"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_status"></a>frontend status</h3></div></div></div><p>Several functions of the frontend device use the fe_status data type defined
by</p><pre class="programlisting">
typedef enum fe_status {
FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/
FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/
FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/
FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/
FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/
FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/
FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/
} fe_status_t; /⋆ application is recommned to reset ⋆/
</pre><p>to indicate the current state and/or state changes of the frontend hardware.
</p></div><div class="section" title="frontend parameters"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_params"></a>frontend parameters</h3></div></div></div><p>The kind of parameters passed to the frontend device for tuning depend on
the kind of hardware you are using. All kinds of parameters are combined as an
union in the FrontendParameters structure:</p><pre class="programlisting">
struct dvb_frontend_parameters {
uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/
/⋆ intermediate frequency in kHz for QPSK ⋆/
fe_spectral_inversion_t inversion;
union {
struct dvb_qpsk_parameters qpsk;
struct dvb_qam_parameters qam;
struct dvb_ofdm_parameters ofdm;
} u;
};
</pre><p>For satellite QPSK frontends you have to use the <code class="constant">QPSKParameters</code> member defined by</p><pre class="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) ⋆/
};
</pre><p>for cable QAM frontend you use the <code class="constant">QAMParameters</code> structure</p><pre class="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) ⋆/
};
</pre><p>DVB-T frontends are supported by the <code class="constant">OFDMParamters</code> structure
</p><pre class="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;
};
</pre><p>In the case of QPSK frontends the <code class="constant">Frequency</code> field specifies the intermediate
frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
OFDM frontends the Frequency specifies the absolute frequency and is given in
Hz.
</p><p>The Inversion field can take one of these values:
</p><pre class="programlisting">
typedef enum fe_spectral_inversion {
INVERSION_OFF,
INVERSION_ON,
INVERSION_AUTO
} fe_spectral_inversion_t;
</pre><p>It indicates if spectral inversion should be presumed or not. In the automatic setting
(<code class="constant">INVERSION_AUTO</code>) the hardware will try to figure out the correct setting by
itself.
</p><p>The possible values for the <code class="constant">FEC_inner</code> field are
</p><pre class="programlisting">
typedef enum fe_code_rate {
FEC_NONE = 0,
FEC_1_2,
FEC_2_3,
FEC_3_4,
FEC_4_5,
FEC_5_6,
FEC_6_7,
FEC_7_8,
FEC_8_9,
FEC_AUTO
} fe_code_rate_t;
</pre><p>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
detection.
</p><p>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature
modulation mode which can be one of the following:
</p><pre class="programlisting">
typedef enum fe_modulation {
QPSK,
QAM_16,
QAM_32,
QAM_64,
QAM_128,
QAM_256,
QAM_AUTO
} fe_modulation_t;
</pre><p>Finally, there are several more parameters for OFDM:
</p><pre class="programlisting">
typedef enum fe_transmit_mode {
TRANSMISSION_MODE_2K,
TRANSMISSION_MODE_8K,
TRANSMISSION_MODE_AUTO
} fe_transmit_mode_t;
</pre><pre class="programlisting">
typedef enum fe_bandwidth {
BANDWIDTH_8_MHZ,
BANDWIDTH_7_MHZ,
BANDWIDTH_6_MHZ,
BANDWIDTH_AUTO
} fe_bandwidth_t;
</pre><pre class="programlisting">
typedef enum fe_guard_interval {
GUARD_INTERVAL_1_32,
GUARD_INTERVAL_1_16,
GUARD_INTERVAL_1_8,
GUARD_INTERVAL_1_4,
GUARD_INTERVAL_AUTO
} fe_guard_interval_t;
</pre><pre class="programlisting">
typedef enum fe_hierarchy {
HIERARCHY_NONE,
HIERARCHY_1,
HIERARCHY_2,
HIERARCHY_4,
HIERARCHY_AUTO
} fe_hierarchy_t;
</pre></div><div class="section" title="frontend events"><div class="titlepage"><div><div><h3 class="title"><a id="frontend_events"></a>frontend events</h3></div></div></div><pre class="programlisting">
struct dvb_frontend_event {
fe_status_t status;
struct dvb_frontend_parameters parameters;
};
</pre></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch08s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch09s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">API include files </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Frontend Function Calls</td></tr></table></div></body></html>
