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><para>Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, DTMB, CMMB</para></listitem>
   6     <listitem><para>Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C</para></listitem>
   7     <listitem><para>Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS</para></listitem>
   8 </itemizedlist>
   9 <para>The DVB frontend controls several sub-devices including:</para>
  10 <itemizedlist>
  11     <listitem><para>Tuner</para></listitem>
  12     <listitem><para>Digital TV demodulator</para></listitem>
  13     <listitem><para>Low noise amplifier (LNA)</para></listitem>
  14     <listitem><para>Satellite Equipment Control (SEC) hardware (only for Satellite).</para></listitem>
  15 </itemizedlist>
  16 <para>The frontend can be accessed through
  17     <constant>/dev/dvb/adapter?/frontend?</constant>. Data types and
  18     ioctl definitions can be accessed by including
  19     <constant>linux/dvb/frontend.h</constant> 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 Satellite 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 note that several statistics require the demodulator to be fully
  52     locked (e. g. with FE_HAS_LOCK bit set). See
  53     <link linkend="frontend-stat-properties">Frontend statistics indicators</link>
  54     for more details.</para>
  55 </section>
  56
  57 &sub-dvbproperty;
  58
  59 <section id="frontend_fcalls">
  60 <title>Frontend Function Calls</title>
  61
  62 <refentry id="frontend_f_open">
  63   <refmeta>
  64     <refentrytitle>DVB frontend open()</refentrytitle>
  65     &manvol;
  66   </refmeta>
  67
  68   <refnamediv>
  69     <refname>fe-open</refname>
  70     <refpurpose>Open a frontend device</refpurpose>
  71   </refnamediv>
  72
  73   <refsynopsisdiv>
  74     <funcsynopsis>
  75       <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
  76       <funcprototype>
  77         <funcdef>int <function>open</function></funcdef>
  78         <paramdef>const char *<parameter>device_name</parameter></paramdef>
  79         <paramdef>int <parameter>flags</parameter></paramdef>
  80       </funcprototype>
  81     </funcsynopsis>
  82   </refsynopsisdiv>
  83
  84   <refsect1>
  85     <title>Arguments</title>
  86
  87     <variablelist>
  88       <varlistentry>
  89         <term><parameter>device_name</parameter></term>
  90         <listitem>
  91           <para>Device to be opened.</para>
  92         </listitem>
  93       </varlistentry>
  94       <varlistentry>
  95         <term><parameter>flags</parameter></term>
  96         <listitem>
  97           <para>Open flags. Access can either be
  98               <constant>O_RDWR</constant> or <constant>O_RDONLY</constant>.</para>
  99           <para>Multiple opens are allowed with <constant>O_RDONLY</constant>. In this mode, only query and read ioctls are allowed.</para>
 100           <para>Only one open is allowed in <constant>O_RDWR</constant>. In this mode, all ioctls are allowed.</para>
 101           <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>
 102          <para>Other flags have no effect.</para>
 103         </listitem>
 104       </varlistentry>
 105     </variablelist>
 106   </refsect1>
 107   <refsect1>
 108     <title>Description</title>
 109     <para>This system call opens a named frontend device (<constant>/dev/dvb/adapter?/frontend?</constant>)
 110  for subsequent use. Usually the first thing to do after a successful open is to
 111  find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
 112 <para>The device can be opened in read-only mode, which only allows monitoring of
 113  device status and statistics, or read/write mode, which allows any kind of use
 114  (e.g. performing tuning operations.)
 115 </para>
 116 <para>In a system with multiple front-ends, it is usually the case that multiple devices
 117  cannot be open in read/write mode simultaneously. As long as a front-end
 118  device is opened in read/write mode, other open() calls in read/write mode will
 119  either fail or block, depending on whether non-blocking or blocking mode was
 120  specified. A front-end device opened in blocking mode can later be put into
 121  non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
 122  system call. This is a standard system call, documented in the Linux manual
 123  page for fcntl. When an open() call has succeeded, the device will be ready
 124  for use in the specified mode. This implies that the corresponding hardware is
 125  powered up, and that other front-ends may have been powered down to make
 126  that possible.</para>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Return Value</title>
 131
 132     <para>On success <function>open</function> returns the new file
 133 descriptor. On error -1 is returned, and the <varname>errno</varname>
 134 variable is set appropriately. Possible error codes are:</para>
 135
 136     <variablelist>
 137       <varlistentry>
 138         <term><errorcode>EACCES</errorcode></term>
 139         <listitem>
 140           <para>The caller has no permission to access the
 141 device.</para>
 142         </listitem>
 143       </varlistentry>
 144       <varlistentry>
 145         <term><errorcode>EBUSY</errorcode></term>
 146         <listitem>
 147           <para>The the device driver is already in use.</para>
 148         </listitem>
 149       </varlistentry>
 150       <varlistentry>
 151         <term><errorcode>ENXIO</errorcode></term>
 152         <listitem>
 153           <para>No device corresponding to this device special file
 154 exists.</para>
 155         </listitem>
 156       </varlistentry>
 157       <varlistentry>
 158         <term><errorcode>ENOMEM</errorcode></term>
 159         <listitem>
 160           <para>Not enough kernel memory was available to complete the
 161 request.</para>
 162         </listitem>
 163       </varlistentry>
 164       <varlistentry>
 165         <term><errorcode>EMFILE</errorcode></term>
 166         <listitem>
 167           <para>The  process  already  has  the  maximum number of
 168 files open.</para>
 169         </listitem>
 170       </varlistentry>
 171       <varlistentry>
 172         <term><errorcode>ENFILE</errorcode></term>
 173         <listitem>
 174           <para>The limit on the total number of files open on the
 175 system has been reached.</para>
 176         </listitem>
 177       </varlistentry>
 178       <varlistentry>
 179         <term><errorcode>ENODEV</errorcode></term>
 180         <listitem>
 181           <para>The device got removed.</para>
 182         </listitem>
 183       </varlistentry>
 184     </variablelist>
 185   </refsect1>
 186 </refentry>
 187
 188 <refentry id="frontend_f_close">
 189   <refmeta>
 190     <refentrytitle>DVB frontend close()</refentrytitle>
 191     &manvol;
 192   </refmeta>
 193
 194   <refnamediv>
 195     <refname>fe-close</refname>
 196     <refpurpose>Close a frontend device</refpurpose>
 197   </refnamediv>
 198
 199   <refsynopsisdiv>
 200     <funcsynopsis>
 201       <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
 202       <funcprototype>
 203         <funcdef>int <function>close</function></funcdef>
 204         <paramdef>int <parameter>fd</parameter></paramdef>
 205       </funcprototype>
 206     </funcsynopsis>
 207   </refsynopsisdiv>
 208
 209   <refsect1>
 210     <title>Arguments</title>
 211
 212     <variablelist>
 213       <varlistentry>
 214         <term><parameter>fd</parameter></term>
 215         <listitem>
 216           <para>&fd;</para>
 217         </listitem>
 218       </varlistentry>
 219     </variablelist>
 220   </refsect1>
 221
 222   <refsect1>
 223     <title>Description</title>
 224 <para>This system call closes a previously opened front-end device. After closing
 225  a front-end device, its corresponding hardware might be powered down
 226  automatically.</para>
 227 </refsect1>
 228   <refsect1>
 229     <title>Return Value</title>
 230
 231     <para>The function returns <returnvalue>0</returnvalue> on
 232 success, <returnvalue>-1</returnvalue> on failure and the
 233 <varname>errno</varname> is set appropriately. Possible error
 234 codes:</para>
 235
 236     <variablelist>
 237       <varlistentry>
 238         <term><errorcode>EBADF</errorcode></term>
 239         <listitem>
 240           <para><parameter>fd</parameter> is not a valid open file
 241 descriptor.</para>
 242         </listitem>
 243       </varlistentry>
 244     </variablelist>
 245   </refsect1>
 246 </refentry>
 247
 248 &sub-fe-get-info;
 249 &sub-fe-read-status;
 250 &sub-fe-get-property;
 251 &sub-fe-diseqc-reset-overload;
 252 &sub-fe-diseqc-send-master-cmd;
 253 &sub-fe-diseqc-recv-slave-reply;
 254 &sub-fe-diseqc-send-burst;
 255 &sub-fe-set-tone;
 256 &sub-fe-set-voltage;
 257 &sub-fe-enable-high-lnb-voltage;
 258 &sub-fe-set-frontend-tune-mode;
 259
 260 </section>
 261
 262 <section id="frontend_legacy_dvbv3_api">
 263 <title>DVB Frontend legacy API (a. k. a. DVBv3)</title>
 264 <para>The usage of this API is deprecated, as it doesn't support all digital
 265     TV standards, doesn't provide good statistics measurements and provides
 266     incomplete information. This is kept only to support legacy applications.</para>
 267
 268 &sub-frontend_legacy_api;
 269 </section>