Documentation/DocBook/media/dvb/frontend.xml

   1 <title>DVB Frontend API</title>
   2
   3 <para>The DVB frontend API was designed to support three types of delivery systems:</para>
   4 <itemizedlist>
   5     <listitem>Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, DTMB, CMMB</listitem>
   6     <listitem>Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C</listitem>
   7     <listitem>Satellital systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS</listitem>
   8 </itemizedlist>
   9 <para>The DVB frontend controls several sub-devices including:</para>
  10 <itemizedlist>
  11     <listitem>Tuner</listitem>,
  12     <listitem>Digital TV demodulator</listitem>
  13     <listitem>Low noise amplifier (LNA)</listitem>
  14     <listitem>Satellite Equipment Control (SEC) hardware (only for Satellite).</listitem>
  15 </itemizedlist>
  16 <para>The frontend can be accessed through
  17     <emphasis role="bold">/dev/dvb/adapter?/frontend?</emphasis>. Data types and
  18     ioctl definitions can be accessed by including
  19     <emphasis role="bold">linux/dvb/frontend.h</emphasis> in your application.
  20 </para>
  21
  22 <para>NOTE: Transmission via the internet (DVB-IP)
  23     is not yet handled by this API but a future extension is possible.</para>
  24 <para>On Satellital systems, the API support for the Satellite Equipment Control
  25     (SEC) allows to power control and to send/receive signals to control the
  26     antenna subsystem, selecting the polarization and choosing the Intermediate
  27     Frequency IF) of the Low Noise Block Converter Feed Horn (LNBf). It
  28     supports the DiSEqC and V-SEC protocols. The DiSEqC (digital SEC)
  29 specification is available at
  30 <ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para>
  31
  32 <section id="query-dvb-frontend-info">
  33 <title>Querying frontend information</title>
  34
  35 <para>Usually, the first thing to do when the frontend is opened is to
  36     check the frontend capabilities. This is done using <link linkend="FE_GET_INFO">FE_GET_INFO</link>. This ioctl will enumerate
  37     the DVB API version and other characteristics about the frontend, and
  38     can be opened either in read only or read/write mode.</para>
  39 </section>
  40
  41 <section id="dvb-fe-read-status">
  42 <title>Querying frontend status and statistics</title>
  43
  44 <para>Once <link linkend="FE_GET_PROPERTY"><constant>FE_SET_PROPERTY</constant></link>
  45     is called, the frontend will run a kernel thread that will periodically
  46     check for the tuner lock status and provide statistics about the quality
  47     of the signal.</para>
  48 <para>The information about the frontend tuner locking status can be queried
  49     using <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>.</para>
  50 <para>Signal statistics are provided via <link linkend="FE_GET_PROPERTY"><constant>FE_GET_PROPERTY</constant></link>.
  51     Please notice that several statistics require the demodulator to be fully
  52     locked (e. g. with FE_HAS_LOCK bit set). See
  53     <xref linkend="frontend-stat-properties">Frontend statistics indicators</xref>
  54     for more details.</para>
  55 </section>
  56
  57 &sub-dvbproperty;
  58
  59 <section id="fe-spectral-inversion-t">
  60 <title>frontend spectral inversion</title>
  61 <para>The Inversion field can take one of these values:
  62 </para>
  63 <programlisting>
  64 typedef enum fe_spectral_inversion {
  65         INVERSION_OFF,
  66         INVERSION_ON,
  67         INVERSION_AUTO
  68 } fe_spectral_inversion_t;
  69 </programlisting>
  70 <para>It indicates if spectral inversion should be presumed or not. In the automatic setting
  71 (<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
  72 itself.
  73 </para>
  74 </section>
  75
  76 <section id="fe-code-rate-t">
  77 <title>frontend code rate</title>
  78 <para>The possible values for the <constant>fec_inner</constant> field used on
  79 <link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and
  80 <link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are:
  81 </para>
  82 <programlisting>
  83 typedef enum fe_code_rate {
  84         FEC_NONE = 0,
  85         FEC_1_2,
  86         FEC_2_3,
  87         FEC_3_4,
  88         FEC_4_5,
  89         FEC_5_6,
  90         FEC_6_7,
  91         FEC_7_8,
  92         FEC_8_9,
  93         FEC_AUTO,
  94         FEC_3_5,
  95         FEC_9_10,
  96 } fe_code_rate_t;
  97 </programlisting>
  98 <para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
  99 detection.
 100 </para>
 101 </section>
 102
 103 <section id="fe-modulation-t">
 104 <title>frontend modulation type for QAM, OFDM and VSB</title>
 105 <para>For cable and terrestrial frontends, e. g. for
 106 <link linkend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>,
 107 <link linkend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and
 108 <link linkend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>,
 109 it needs to specify the quadrature modulation mode which can be one of the following:
 110 </para>
 111 <programlisting>
 112  typedef enum fe_modulation {
 113         QPSK,
 114         QAM_16,
 115         QAM_32,
 116         QAM_64,
 117         QAM_128,
 118         QAM_256,
 119         QAM_AUTO,
 120         VSB_8,
 121         VSB_16,
 122         PSK_8,
 123         APSK_16,
 124         APSK_32,
 125         DQPSK,
 126  } fe_modulation_t;
 127 </programlisting>
 128 </section>
 129
 130 <section>
 131 <title>More OFDM parameters</title>
 132
 133 <section id="fe-transmit-mode-t">
 134 <title>Number of carriers per channel</title>
 135 <programlisting>
 136 typedef enum fe_transmit_mode {
 137         TRANSMISSION_MODE_2K,
 138         TRANSMISSION_MODE_8K,
 139         TRANSMISSION_MODE_AUTO,
 140         TRANSMISSION_MODE_4K,
 141         TRANSMISSION_MODE_1K,
 142         TRANSMISSION_MODE_16K,
 143         TRANSMISSION_MODE_32K,
 144  } fe_transmit_mode_t;
 145 </programlisting>
 146 </section>
 147
 148 <section id="fe-bandwidth-t">
 149 <title>frontend bandwidth</title>
 150 <programlisting>
 151 typedef enum fe_bandwidth {
 152         BANDWIDTH_8_MHZ,
 153         BANDWIDTH_7_MHZ,
 154         BANDWIDTH_6_MHZ,
 155         BANDWIDTH_AUTO,
 156         BANDWIDTH_5_MHZ,
 157         BANDWIDTH_10_MHZ,
 158         BANDWIDTH_1_712_MHZ,
 159 } fe_bandwidth_t;
 160 </programlisting>
 161 </section>
 162
 163 <section id="fe-guard-interval-t">
 164 <title>frontend guard inverval</title>
 165 <programlisting>
 166 typedef enum fe_guard_interval {
 167         GUARD_INTERVAL_1_32,
 168         GUARD_INTERVAL_1_16,
 169         GUARD_INTERVAL_1_8,
 170         GUARD_INTERVAL_1_4,
 171         GUARD_INTERVAL_AUTO,
 172         GUARD_INTERVAL_1_128,
 173         GUARD_INTERVAL_19_128,
 174         GUARD_INTERVAL_19_256,
 175 } fe_guard_interval_t;
 176 </programlisting>
 177 </section>
 178
 179 <section id="fe-hierarchy-t">
 180 <title>frontend hierarchy</title>
 181 <programlisting>
 182 typedef enum fe_hierarchy {
 183          HIERARCHY_NONE,
 184          HIERARCHY_1,
 185          HIERARCHY_2,
 186          HIERARCHY_4,
 187          HIERARCHY_AUTO
 188  } fe_hierarchy_t;
 189 </programlisting>
 190 </section>
 191
 192 </section>
 193
 194 <section id="frontend_fcalls">
 195 <title>Frontend Function Calls</title>
 196
 197 <section id="frontend_f_open">
 198 <title>open()</title>
 199 <para>DESCRIPTION</para>
 200 <informaltable><tgroup cols="1"><tbody><row>
 201 <entry align="char">
 202 <para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
 203  for subsequent use. Usually the first thing to do after a successful open is to
 204  find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
 205 <para>The device can be opened in read-only mode, which only allows monitoring of
 206  device status and statistics, or read/write mode, which allows any kind of use
 207  (e.g. performing tuning operations.)
 208 </para>
 209 <para>In a system with multiple front-ends, it is usually the case that multiple devices
 210  cannot be open in read/write mode simultaneously. As long as a front-end
 211  device is opened in read/write mode, other open() calls in read/write mode will
 212  either fail or block, depending on whether non-blocking or blocking mode was
 213  specified. A front-end device opened in blocking mode can later be put into
 214  non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
 215  system call. This is a standard system call, documented in the Linux manual
 216  page for fcntl. When an open() call has succeeded, the device will be ready
 217  for use in the specified mode. This implies that the corresponding hardware is
 218  powered up, and that other front-ends may have been powered down to make
 219  that possible.</para>
 220 </entry>
 221  </row></tbody></tgroup></informaltable>
 222
 223 <para>SYNOPSIS</para>
 224 <informaltable><tgroup cols="1"><tbody><row><entry
 225  align="char">
 226 <para>int open(const char &#x22C6;deviceName, int flags);</para>
 227 </entry>
 228  </row></tbody></tgroup></informaltable>
 229 <para>PARAMETERS
 230 </para>
 231 <informaltable><tgroup cols="2"><tbody><row><entry
 232  align="char">
 233 <para>const char
 234  *deviceName</para>
 235 </entry><entry
 236  align="char">
 237 <para>Name of specific video device.</para>
 238 </entry>
 239  </row><row><entry
 240  align="char">
 241 <para>int flags</para>
 242 </entry><entry
 243  align="char">
 244 <para>A bit-wise OR of the following flags:</para>
 245 </entry>
 246  </row><row><entry
 247  align="char">
 248 </entry><entry
 249  align="char">
 250 <para>O_RDONLY read-only access</para>
 251 </entry>
 252  </row><row><entry
 253  align="char">
 254 </entry><entry
 255  align="char">
 256 <para>O_RDWR read/write access</para>
 257 </entry>
 258  </row><row><entry
 259  align="char">
 260 </entry><entry
 261  align="char">
 262 <para>O_NONBLOCK open in non-blocking mode</para>
 263 </entry>
 264  </row><row><entry
 265  align="char">
 266 </entry><entry
 267  align="char">
 268 <para>(blocking mode is the default)</para>
 269 </entry>
 270  </row></tbody></tgroup></informaltable>
 271 <para>RETURN VALUE</para>
 272 <informaltable><tgroup cols="2"><tbody><row><entry
 273  align="char">
 274 <para>ENODEV</para>
 275 </entry><entry
 276  align="char">
 277 <para>Device driver not loaded/available.</para>
 278 </entry>
 279  </row><row><entry
 280  align="char">
 281 <para>EINTERNAL</para>
 282 </entry><entry
 283  align="char">
 284 <para>Internal error.</para>
 285 </entry>
 286  </row><row><entry
 287  align="char">
 288 <para>EBUSY</para>
 289 </entry><entry
 290  align="char">
 291 <para>Device or resource busy.</para>
 292 </entry>
 293  </row><row><entry
 294  align="char">
 295 <para>EINVAL</para>
 296 </entry><entry
 297  align="char">
 298 <para>Invalid argument.</para>
 299 </entry>
 300  </row></tbody></tgroup></informaltable>
 301 </section>
 302
 303 <section id="frontend_f_close">
 304 <title>close()</title>
 305 <para>DESCRIPTION
 306 </para>
 307 <informaltable><tgroup cols="1"><tbody><row><entry
 308  align="char">
 309 <para>This system call closes a previously opened front-end device. After closing
 310  a front-end device, its corresponding hardware might be powered down
 311  automatically.</para>
 312 </entry>
 313  </row></tbody></tgroup></informaltable>
 314 <para>SYNOPSIS
 315 </para>
 316 <informaltable><tgroup cols="1"><tbody><row><entry
 317  align="char">
 318 <para>int close(int fd);</para>
 319 </entry>
 320  </row></tbody></tgroup></informaltable>
 321 <para>PARAMETERS
 322 </para>
 323 <informaltable><tgroup cols="2"><tbody><row><entry
 324  align="char">
 325 <para>int fd</para>
 326 </entry><entry
 327  align="char">
 328 <para>File descriptor returned by a previous call to open().</para>
 329 </entry>
 330  </row></tbody></tgroup></informaltable>
 331 <para>RETURN VALUE</para>
 332 <informaltable><tgroup cols="2"><tbody><row><entry
 333  align="char">
 334 <para>EBADF</para>
 335 </entry><entry
 336  align="char">
 337 <para>fd is not a valid open file descriptor.</para>
 338 </entry>
 339  </row></tbody></tgroup></informaltable>
 340 </section>
 341
 342 &sub-fe-get-info;
 343 &sub-fe-read-status;
 344 &sub-fe-get-property;
 345 &sub-fe-diseqc-reset-overload;
 346 &sub-fe-diseqc-send-master-cmd;
 347 &sub-fe-diseqc-recv-slave-reply;
 348 &sub-fe-diseqc-send-burst;
 349 &sub-fe-set-tone;
 350 &sub-fe-set-voltage;
 351 &sub-fe-enable-high-lnb-voltage;
 352 &sub-fe-set-frontend-tune-mode;
 353
 354 </section>
 355
 356 <section id="frontend_legacy_dvbv3_api">
 357 <title>DVB Frontend legacy API (a. k. a. DVBv3)</title>
 358 <para>The usage of this API is deprecated, as it doesn't support all digital
 359     TV standards, doesn't provide good statistics measurements and provides
 360     incomplete information. This is kept only to support legacy applications.</para>
 361
 362 &sub-frontend_legacy_api;
 363 </section>