Commit 5b233e1a authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

[media] DocBook: improve documentation for FE_READ_STATUS 



Move the ioctl and enum fe_status to a separate xml file and
put it into a better format.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@osg.samsung.com>
parent 002563e9

Documentation/DocBook/media/dvb/frontend.xml

+10 −109
Original line number Diff line number Diff line
@@ -33,12 +33,21 @@ specification is available at 
<section id="query-dvb-frontend-info">

<title>Querying frontend information</title>



<para>Information about the frontend ca be queried with

<para>Information about the frontend can be queried with

	<link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>

</section>



&sub-frontend_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-frontend_read_status;



<section id="dvb-diseqc-master-cmd">

<title>diseqc master command</title>
@@ -109,51 +118,6 @@ spec.</para> 
<para></para>

</section>



<section id="fe-status-t">

<title>frontend status</title>

<para>Several functions of the frontend device use the fe_status data type defined

by</para>

<programlisting>

typedef enum fe_status {

	FE_HAS_SIGNAL		= 0x01,

	FE_HAS_CARRIER		= 0x02,

	FE_HAS_VITERBI		= 0x04,

	FE_HAS_SYNC		= 0x08,

	FE_HAS_LOCK		= 0x10,

	FE_TIMEDOUT		= 0x20,

	FE_REINIT		= 0x40,

} fe_status_t;

</programlisting>

<para>to indicate the current state and/or state changes of the frontend hardware:

</para>



<informaltable><tgroup cols="2"><tbody>

<row>

<entry align="char">FE_HAS_SIGNAL</entry>

<entry align="char">The frontend has found something above the noise level</entry>

</row><row>

<entry align="char">FE_HAS_CARRIER</entry>

<entry align="char">The frontend has found a DVB signal</entry>

</row><row>

<entry align="char">FE_HAS_VITERBI</entry>

<entry align="char">The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable</entry>

</row><row>

<entry align="char">FE_HAS_SYNC</entry>

<entry align="char">Synchronization bytes was found</entry>

</row><row>

<entry align="char">FE_HAS_LOCK</entry>

<entry align="char">The DVB were locked and everything is working</entry>

</row><row>

<entry align="char">FE_TIMEDOUT</entry>

<entry align="char">no lock within the last about 2 seconds</entry>

</row><row>

<entry align="char">FE_REINIT</entry>

<entry align="char">The frontend was reinitialized, application is

recommended to reset DiSEqC, tone and parameters</entry>

</row>

</tbody></tgroup></informaltable>

</section>



<section id="fe-spectral-inversion-t">

<title>frontend spectral inversion</title>

<para>The Inversion field can take one of these values:
@@ -437,69 +401,6 @@ typedef enum fe_hierarchy { 
 </row></tbody></tgroup></informaltable>

</section>



<section id="FE_READ_STATUS">

<title>FE_READ_STATUS</title>

<para>DESCRIPTION

</para>

<informaltable><tgroup cols="1"><tbody><row><entry

 align="char">

<para>This ioctl call returns status information about the front-end. This call only

 requires read-only access to the device.</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_READ_STATUS">FE_READ_STATUS</link>,

 fe_status_t &#x22C6;status);</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_READ_STATUS">FE_READ_STATUS</link> for this command.</para>

</entry>

 </row><row><entry

 align="char">

<para>struct fe_status_t

 *status</para>

</entry><entry

 align="char">

<para>Points to the location where the front-end status word is

 to be stored.</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><row><entry

 align="char">

<para>EFAULT</para>

</entry><entry

 align="char">

<para>status points to invalid address.</para>

</entry>

 </row></tbody></tgroup></informaltable>

</section>





<section id="FE_DISEQC_RESET_OVERLOAD">

<title>FE_DISEQC_RESET_OVERLOAD</title>

Documentation/DocBook/media/dvb/frontend_read_status.xml

0 → 100644
+103 −0
Original line number Diff line number Diff line 
<refentry id="FE_READ_STATUS">

  <refmeta>

    <refentrytitle>ioctl FE_READ_STATUS</refentrytitle>

    &manvol;

  </refmeta>



  <refnamediv>

    <refname>FE_READ_STATUS</refname>

    <refpurpose>Returns status information about the front-end. This call only

 requires read-only access to the device</refpurpose>

  </refnamediv>



  <refsynopsisdiv>

    <funcsynopsis>

      <funcprototype>

	<funcdef>int <function>ioctl</function></funcdef>

	<paramdef>int <parameter>fd</parameter></paramdef>

	<paramdef>int <parameter>request</parameter></paramdef>

	<paramdef>&fe-status; *<parameter>argp</parameter></paramdef>

      </funcprototype>

    </funcsynopsis>

  </refsynopsisdiv>



  <refsect1>

    <title>Arguments</title>

        <variablelist>

      <varlistentry>

	<term><parameter>fd</parameter></term>

	<listitem>

	  <para>&fd;</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>request</parameter></term>

	<listitem>

	  <para>FE_READ_STATUS</para>

	</listitem>

      </varlistentry>

      <varlistentry>

	<term><parameter>argp</parameter></term>

	<listitem>

	    <para>pointer to &fe-status;</para>

	</listitem>

      </varlistentry>

    </variablelist>

  </refsect1>



  <refsect1>

    <title>Description</title>



    <para>All DVB frontend devices support the

<constant>FE_READ_STATUS</constant> ioctl. It is used to check about the

locking status of the frontend after being tuned. The ioctl takes a

pointer to a 16-bits number where the status will be written.

&return-value-dvb;.

</para>

</refsect1>



<section id="fe-status-t">

<title>enum fe_status</title>



<para>The enum fe_status is used to indicate the current state

    and/or state changes of the frontend hardware.</para>



<table pgwide="1" frame="none" id="fe-status">

    <title>enum fe_status</title>

    <tgroup cols="2">

	&cs-def;

	<thead>

	<row>

	    <entry>ID</entry>

	    <entry>Description</entry>

	</row>

	</thead>

	<tbody valign="top">

	<row>

	    <entry align="char">FE_HAS_SIGNAL</entry>

	    <entry align="char">The frontend has found something above the noise level</entry>

	</row><row>

	    <entry align="char">FE_HAS_CARRIER</entry>

	    <entry align="char">The frontend has found a DVB signal</entry>

	</row><row>

	    <entry align="char">FE_HAS_VITERBI</entry>

	    <entry align="char">The frontend FEC inner coding (Viterbi, LDPC or other inner code) is stable</entry>

	</row><row>

	    <entry align="char">FE_HAS_SYNC</entry>

	    <entry align="char">Synchronization bytes was found</entry>

	</row><row>

	    <entry align="char">FE_HAS_LOCK</entry>

	    <entry align="char">The DVB were locked and everything is working</entry>

	</row><row>

	    <entry align="char">FE_TIMEDOUT</entry>

	    <entry align="char">no lock within the last about 2 seconds</entry>

	</row><row>

	    <entry align="char">FE_REINIT</entry>

	    <entry align="char">The frontend was reinitialized, application is

	    recommended to reset DiSEqC, tone and parameters</entry>

	</row>

        </tbody>

    </tgroup>

</table>

</section>

</refentry>