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-code-rate-t">
  60 <title>frontend code rate</title>
  61 <para>The possible values for the <constant>fec_inner</constant> field used on
  62 <link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and
  63 <link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are:
  64 </para>
  65 <programlisting>
  66 typedef enum fe_code_rate {
  67         FEC_NONE = 0,
  68         FEC_1_2,
  69         FEC_2_3,
  70         FEC_3_4,
  71         FEC_4_5,
  72         FEC_5_6,
  73         FEC_6_7,
  74         FEC_7_8,
  75         FEC_8_9,
  76         FEC_AUTO,
  77         FEC_3_5,
  78         FEC_9_10,
  79 } fe_code_rate_t;
  80 </programlisting>
  81 <para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
  82 detection.
  83 </para>
  84 </section>
  85
  86
  87 <section>
  88 <title>More OFDM parameters</title>
  89
  90 <section id="fe-transmit-mode-t">
  91 <title>Number of carriers per channel</title>
  92 <programlisting>
  93 typedef enum fe_transmit_mode {
  94         TRANSMISSION_MODE_2K,
  95         TRANSMISSION_MODE_8K,
  96         TRANSMISSION_MODE_AUTO,
  97         TRANSMISSION_MODE_4K,
  98         TRANSMISSION_MODE_1K,
  99         TRANSMISSION_MODE_16K,
 100         TRANSMISSION_MODE_32K,
 101  } fe_transmit_mode_t;
 102 </programlisting>
 103 </section>
 104
 105 <section id="fe-bandwidth-t">
 106 <title>frontend bandwidth</title>
 107 <programlisting>
 108 typedef enum fe_bandwidth {
 109         BANDWIDTH_8_MHZ,
 110         BANDWIDTH_7_MHZ,
 111         BANDWIDTH_6_MHZ,
 112         BANDWIDTH_AUTO,
 113         BANDWIDTH_5_MHZ,
 114         BANDWIDTH_10_MHZ,
 115         BANDWIDTH_1_712_MHZ,
 116 } fe_bandwidth_t;
 117 </programlisting>
 118 </section>
 119
 120 <section id="fe-guard-interval-t">
 121 <title>frontend guard inverval</title>
 122 <programlisting>
 123 typedef enum fe_guard_interval {
 124         GUARD_INTERVAL_1_32,
 125         GUARD_INTERVAL_1_16,
 126         GUARD_INTERVAL_1_8,
 127         GUARD_INTERVAL_1_4,
 128         GUARD_INTERVAL_AUTO,
 129         GUARD_INTERVAL_1_128,
 130         GUARD_INTERVAL_19_128,
 131         GUARD_INTERVAL_19_256,
 132 } fe_guard_interval_t;
 133 </programlisting>
 134 </section>
 135
 136 <section id="fe-hierarchy-t">
 137 <title>frontend hierarchy</title>
 138 <programlisting>
 139 typedef enum fe_hierarchy {
 140          HIERARCHY_NONE,
 141          HIERARCHY_1,
 142          HIERARCHY_2,
 143          HIERARCHY_4,
 144          HIERARCHY_AUTO
 145  } fe_hierarchy_t;
 146 </programlisting>
 147 </section>
 148
 149 </section>
 150
 151 <section id="frontend_fcalls">
 152 <title>Frontend Function Calls</title>
 153
 154 <section id="frontend_f_open">
 155 <title>open()</title>
 156 <para>DESCRIPTION</para>
 157 <informaltable><tgroup cols="1"><tbody><row>
 158 <entry align="char">
 159 <para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
 160  for subsequent use. Usually the first thing to do after a successful open is to
 161  find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
 162 <para>The device can be opened in read-only mode, which only allows monitoring of
 163  device status and statistics, or read/write mode, which allows any kind of use
 164  (e.g. performing tuning operations.)
 165 </para>
 166 <para>In a system with multiple front-ends, it is usually the case that multiple devices
 167  cannot be open in read/write mode simultaneously. As long as a front-end
 168  device is opened in read/write mode, other open() calls in read/write mode will
 169  either fail or block, depending on whether non-blocking or blocking mode was
 170  specified. A front-end device opened in blocking mode can later be put into
 171  non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
 172  system call. This is a standard system call, documented in the Linux manual
 173  page for fcntl. When an open() call has succeeded, the device will be ready
 174  for use in the specified mode. This implies that the corresponding hardware is
 175  powered up, and that other front-ends may have been powered down to make
 176  that possible.</para>
 177 </entry>
 178  </row></tbody></tgroup></informaltable>
 179
 180 <para>SYNOPSIS</para>
 181 <informaltable><tgroup cols="1"><tbody><row><entry
 182  align="char">
 183 <para>int open(const char &#x22C6;deviceName, int flags);</para>
 184 </entry>
 185  </row></tbody></tgroup></informaltable>
 186 <para>PARAMETERS
 187 </para>
 188 <informaltable><tgroup cols="2"><tbody><row><entry
 189  align="char">
 190 <para>const char
 191  *deviceName</para>
 192 </entry><entry
 193  align="char">
 194 <para>Name of specific video device.</para>
 195 </entry>
 196  </row><row><entry
 197  align="char">
 198 <para>int flags</para>
 199 </entry><entry
 200  align="char">
 201 <para>A bit-wise OR of the following flags:</para>
 202 </entry>
 203  </row><row><entry
 204  align="char">
 205 </entry><entry
 206  align="char">
 207 <para>O_RDONLY read-only access</para>
 208 </entry>
 209  </row><row><entry
 210  align="char">
 211 </entry><entry
 212  align="char">
 213 <para>O_RDWR read/write access</para>
 214 </entry>
 215  </row><row><entry
 216  align="char">
 217 </entry><entry
 218  align="char">
 219 <para>O_NONBLOCK open in non-blocking mode</para>
 220 </entry>
 221  </row><row><entry
 222  align="char">
 223 </entry><entry
 224  align="char">
 225 <para>(blocking mode is the default)</para>
 226 </entry>
 227  </row></tbody></tgroup></informaltable>
 228 <para>RETURN VALUE</para>
 229 <informaltable><tgroup cols="2"><tbody><row><entry
 230  align="char">
 231 <para>ENODEV</para>
 232 </entry><entry
 233  align="char">
 234 <para>Device driver not loaded/available.</para>
 235 </entry>
 236  </row><row><entry
 237  align="char">
 238 <para>EINTERNAL</para>
 239 </entry><entry
 240  align="char">
 241 <para>Internal error.</para>
 242 </entry>
 243  </row><row><entry
 244  align="char">
 245 <para>EBUSY</para>
 246 </entry><entry
 247  align="char">
 248 <para>Device or resource busy.</para>
 249 </entry>
 250  </row><row><entry
 251  align="char">
 252 <para>EINVAL</para>
 253 </entry><entry
 254  align="char">
 255 <para>Invalid argument.</para>
 256 </entry>
 257  </row></tbody></tgroup></informaltable>
 258 </section>
 259
 260 <section id="frontend_f_close">
 261 <title>close()</title>
 262 <para>DESCRIPTION
 263 </para>
 264 <informaltable><tgroup cols="1"><tbody><row><entry
 265  align="char">
 266 <para>This system call closes a previously opened front-end device. After closing
 267  a front-end device, its corresponding hardware might be powered down
 268  automatically.</para>
 269 </entry>
 270  </row></tbody></tgroup></informaltable>
 271 <para>SYNOPSIS
 272 </para>
 273 <informaltable><tgroup cols="1"><tbody><row><entry
 274  align="char">
 275 <para>int close(int fd);</para>
 276 </entry>
 277  </row></tbody></tgroup></informaltable>
 278 <para>PARAMETERS
 279 </para>
 280 <informaltable><tgroup cols="2"><tbody><row><entry
 281  align="char">
 282 <para>int fd</para>
 283 </entry><entry
 284  align="char">
 285 <para>File descriptor returned by a previous call to open().</para>
 286 </entry>
 287  </row></tbody></tgroup></informaltable>
 288 <para>RETURN VALUE</para>
 289 <informaltable><tgroup cols="2"><tbody><row><entry
 290  align="char">
 291 <para>EBADF</para>
 292 </entry><entry
 293  align="char">
 294 <para>fd is not a valid open file descriptor.</para>
 295 </entry>
 296  </row></tbody></tgroup></informaltable>
 297 </section>
 298
 299 &sub-fe-get-info;
 300 &sub-fe-read-status;
 301 &sub-fe-get-property;
 302 &sub-fe-diseqc-reset-overload;
 303 &sub-fe-diseqc-send-master-cmd;
 304 &sub-fe-diseqc-recv-slave-reply;
 305 &sub-fe-diseqc-send-burst;
 306 &sub-fe-set-tone;
 307 &sub-fe-set-voltage;
 308 &sub-fe-enable-high-lnb-voltage;
 309 &sub-fe-set-frontend-tune-mode;
 310
 311 </section>
 312
 313 <section id="frontend_legacy_dvbv3_api">
 314 <title>DVB Frontend legacy API (a. k. a. DVBv3)</title>
 315 <para>The usage of this API is deprecated, as it doesn't support all digital
 316     TV standards, doesn't provide good statistics measurements and provides
 317     incomplete information. This is kept only to support legacy applications.</para>
 318
 319 &sub-frontend_legacy_api;
 320 </section>