mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-21 19:53:59 +08:00
81959d996a
Use the proper format for FE_DISEQC_SEND_BURST documentation and improve the documentation. Keep the enum fe_sec_mini_cmd description together with the ioctl, as both are used together. Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
521 lines
15 KiB
XML
521 lines
15 KiB
XML
<title>DVB Frontend API</title>
|
|
|
|
<para>The DVB frontend API was designed to support three types of delivery systems:</para>
|
|
<itemizedlist>
|
|
<listitem>Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, DTMB, CMMB</listitem>
|
|
<listitem>Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B), ISDB-C</listitem>
|
|
<listitem>Satellital systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS</listitem>
|
|
</itemizedlist>
|
|
<para>The DVB frontend controls several sub-devices including:</para>
|
|
<itemizedlist>
|
|
<listitem>Tuner</listitem>,
|
|
<listitem>Digital TV demodulator</listitem>
|
|
<listitem>Low noise amplifier (LNA)</listitem>
|
|
<listitem>Satellite Equipment Control (SEC) hardware (only for Satellite).</listitem>
|
|
</itemizedlist>
|
|
<para>The frontend can be accessed through
|
|
<emphasis role="bold">/dev/dvb/adapter?/frontend?</emphasis>. Data types and
|
|
ioctl definitions can be accessed by including
|
|
<emphasis role="bold">linux/dvb/frontend.h</emphasis> in your application.
|
|
</para>
|
|
|
|
<para>NOTE: Transmission via the internet (DVB-IP)
|
|
is not yet handled by this API but a future extension is possible.</para>
|
|
<para>On Satellital systems, the API support for the Satellite Equipment Control
|
|
(SEC) allows to power control and to send/receive signals to control the
|
|
antenna subsystem, selecting the polarization and choosing the Intermediate
|
|
Frequency IF) of the Low Noise Block Converter Feed Horn (LNBf). It
|
|
supports the DiSEqC and V-SEC protocols. The DiSEqC (digital SEC)
|
|
specification is available at
|
|
<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para>
|
|
|
|
|
|
<section id="query-dvb-frontend-info">
|
|
<title>Querying frontend information</title>
|
|
|
|
<para>Information about the frontend can be queried with
|
|
<link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
|
|
</section>
|
|
|
|
&sub-fe-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-fe-read-status;
|
|
|
|
&sub-dvbproperty;
|
|
|
|
<section id="dvb-diseqc-master-cmd">
|
|
<title>diseqc master command</title>
|
|
|
|
<para>A message sent from the frontend to DiSEqC capable equipment.</para>
|
|
<programlisting>
|
|
struct dvb_diseqc_master_cmd {
|
|
uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/
|
|
uint8_t msg_len; /⋆ valid values are 3...6 ⋆/
|
|
};
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section role="subsection" id="dvb-diseqc-slave-reply">
|
|
<title>diseqc slave reply</title>
|
|
|
|
<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para>
|
|
<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 ⋆/
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="fe-spectral-inversion-t">
|
|
<title>frontend spectral inversion</title>
|
|
<para>The Inversion field can take one of these values:
|
|
</para>
|
|
<programlisting>
|
|
typedef enum fe_spectral_inversion {
|
|
INVERSION_OFF,
|
|
INVERSION_ON,
|
|
INVERSION_AUTO
|
|
} fe_spectral_inversion_t;
|
|
</programlisting>
|
|
<para>It indicates if spectral inversion should be presumed or not. In the automatic setting
|
|
(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
|
|
itself.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="fe-code-rate-t">
|
|
<title>frontend code rate</title>
|
|
<para>The possible values for the <constant>fec_inner</constant> field used on
|
|
<link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and
|
|
<link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are:
|
|
</para>
|
|
<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,
|
|
FEC_3_5,
|
|
FEC_9_10,
|
|
} fe_code_rate_t;
|
|
</programlisting>
|
|
<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
|
|
detection.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="fe-modulation-t">
|
|
<title>frontend modulation type for QAM, OFDM and VSB</title>
|
|
<para>For cable and terrestrial frontends, e. g. for
|
|
<link linkend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>,
|
|
<link linkend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and
|
|
<link linkend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>,
|
|
it needs to specify the quadrature modulation mode which can be one of the following:
|
|
</para>
|
|
<programlisting>
|
|
typedef enum fe_modulation {
|
|
QPSK,
|
|
QAM_16,
|
|
QAM_32,
|
|
QAM_64,
|
|
QAM_128,
|
|
QAM_256,
|
|
QAM_AUTO,
|
|
VSB_8,
|
|
VSB_16,
|
|
PSK_8,
|
|
APSK_16,
|
|
APSK_32,
|
|
DQPSK,
|
|
} fe_modulation_t;
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>More OFDM parameters</title>
|
|
|
|
<section id="fe-transmit-mode-t">
|
|
<title>Number of carriers per channel</title>
|
|
<programlisting>
|
|
typedef enum fe_transmit_mode {
|
|
TRANSMISSION_MODE_2K,
|
|
TRANSMISSION_MODE_8K,
|
|
TRANSMISSION_MODE_AUTO,
|
|
TRANSMISSION_MODE_4K,
|
|
TRANSMISSION_MODE_1K,
|
|
TRANSMISSION_MODE_16K,
|
|
TRANSMISSION_MODE_32K,
|
|
} fe_transmit_mode_t;
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="fe-bandwidth-t">
|
|
<title>frontend bandwidth</title>
|
|
<programlisting>
|
|
typedef enum fe_bandwidth {
|
|
BANDWIDTH_8_MHZ,
|
|
BANDWIDTH_7_MHZ,
|
|
BANDWIDTH_6_MHZ,
|
|
BANDWIDTH_AUTO,
|
|
BANDWIDTH_5_MHZ,
|
|
BANDWIDTH_10_MHZ,
|
|
BANDWIDTH_1_712_MHZ,
|
|
} fe_bandwidth_t;
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="fe-guard-interval-t">
|
|
<title>frontend guard inverval</title>
|
|
<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,
|
|
GUARD_INTERVAL_1_128,
|
|
GUARD_INTERVAL_19_128,
|
|
GUARD_INTERVAL_19_256,
|
|
} fe_guard_interval_t;
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section id="fe-hierarchy-t">
|
|
<title>frontend hierarchy</title>
|
|
<programlisting>
|
|
typedef enum fe_hierarchy {
|
|
HIERARCHY_NONE,
|
|
HIERARCHY_1,
|
|
HIERARCHY_2,
|
|
HIERARCHY_4,
|
|
HIERARCHY_AUTO
|
|
} fe_hierarchy_t;
|
|
</programlisting>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="frontend_fcalls">
|
|
<title>Frontend Function Calls</title>
|
|
|
|
<section id="frontend_f_open">
|
|
<title>open()</title>
|
|
<para>DESCRIPTION</para>
|
|
<informaltable><tgroup cols="1"><tbody><row>
|
|
<entry align="char">
|
|
<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
|
|
for subsequent use. Usually the first thing to do after a successful open is to
|
|
find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
|
|
<para>The device can be opened in read-only mode, which only allows monitoring of
|
|
device status and statistics, or read/write mode, which allows any kind of use
|
|
(e.g. performing tuning operations.)
|
|
</para>
|
|
<para>In a system with multiple front-ends, it is usually the case that multiple devices
|
|
cannot be open in read/write mode simultaneously. As long as a front-end
|
|
device is opened in read/write mode, other open() calls in read/write mode will
|
|
either fail or block, depending on whether non-blocking or blocking mode was
|
|
specified. A front-end device opened in blocking mode can later be put into
|
|
non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
|
|
system call. This is a standard system call, documented in the Linux manual
|
|
page for fcntl. When an open() call has succeeded, the device will be ready
|
|
for use in the specified mode. This implies that the corresponding hardware is
|
|
powered up, and that other front-ends may have been powered down to make
|
|
that possible.</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
|
|
<para>SYNOPSIS</para>
|
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
|
align="char">
|
|
<para>int open(const char ⋆deviceName, int flags);</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
<para>PARAMETERS
|
|
</para>
|
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
|
align="char">
|
|
<para>const char
|
|
*deviceName</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Name of specific video device.</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
<para>int flags</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>A bit-wise OR of the following flags:</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
</entry><entry
|
|
align="char">
|
|
<para>O_RDONLY read-only access</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
</entry><entry
|
|
align="char">
|
|
<para>O_RDWR read/write access</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
</entry><entry
|
|
align="char">
|
|
<para>O_NONBLOCK open in non-blocking mode</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
</entry><entry
|
|
align="char">
|
|
<para>(blocking mode is the default)</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
<para>RETURN VALUE</para>
|
|
<informaltable><tgroup cols="2"><tbody><row><entry
|
|
align="char">
|
|
<para>ENODEV</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Device driver not loaded/available.</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
<para>EINTERNAL</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Internal error.</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
<para>EBUSY</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Device or resource busy.</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
<para>EINVAL</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Invalid argument.</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
</section>
|
|
|
|
<section id="frontend_f_close">
|
|
<title>close()</title>
|
|
<para>DESCRIPTION
|
|
</para>
|
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
|
align="char">
|
|
<para>This system call closes a previously opened front-end device. After closing
|
|
a front-end device, its corresponding hardware might be powered down
|
|
automatically.</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
<para>SYNOPSIS
|
|
</para>
|
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
|
align="char">
|
|
<para>int close(int fd);</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></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></tbody></tgroup></informaltable>
|
|
</section>
|
|
|
|
|
|
<section id="FE_DISEQC_RESET_OVERLOAD">
|
|
<title>FE_DISEQC_RESET_OVERLOAD</title>
|
|
<para>DESCRIPTION
|
|
</para>
|
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
|
align="char">
|
|
<para>If the bus has been automatically powered off due to power overload, this ioctl
|
|
call restores the power to the bus. The call requires read/write access to the
|
|
device. This call has no effect if the device is manually powered off. Not all
|
|
DVB adapters support this ioctl.</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_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link>);</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_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link> for this
|
|
command.</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
|
|
&return-value-dvb;
|
|
</section>
|
|
|
|
<section id="FE_DISEQC_SEND_MASTER_CMD">
|
|
<title>FE_DISEQC_SEND_MASTER_CMD</title>
|
|
<para>DESCRIPTION
|
|
</para>
|
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
|
align="char">
|
|
<para>This ioctl call is used to send a a DiSEqC command.</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_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link>, struct
|
|
dvb_diseqc_master_cmd ⋆cmd);</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_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link> for this
|
|
command.</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
<para>struct
|
|
dvb_diseqc_master_cmd
|
|
*cmd</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Pointer to the command to be transmitted.</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
|
|
&return-value-dvb;
|
|
</section>
|
|
|
|
<section id="FE_DISEQC_RECV_SLAVE_REPLY">
|
|
<title>FE_DISEQC_RECV_SLAVE_REPLY</title>
|
|
<para>DESCRIPTION
|
|
</para>
|
|
<informaltable><tgroup cols="1"><tbody><row><entry
|
|
align="char">
|
|
<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</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_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link>, struct
|
|
dvb_diseqc_slave_reply ⋆reply);</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_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link> for this
|
|
command.</para>
|
|
</entry>
|
|
</row><row><entry
|
|
align="char">
|
|
<para>struct
|
|
dvb_diseqc_slave_reply
|
|
*reply</para>
|
|
</entry><entry
|
|
align="char">
|
|
<para>Pointer to the command to be received.</para>
|
|
</entry>
|
|
</row></tbody></tgroup></informaltable>
|
|
&return-value-dvb;
|
|
</section>
|
|
|
|
&sub-fe-diseqc-send-burst;
|
|
&sub-fe-set-tone;
|
|
&sub-fe-set-voltage;
|
|
&sub-fe-enable-high-lnb-voltage;
|
|
&sub-fe-set-frontend-tune-mode;
|
|
|
|
</section>
|
|
|
|
<section id="frontend_legacy_dvbv3_api">
|
|
<title>DVB Frontend legacy API (a. k. a. DVBv3)</title>
|
|
<para>The usage of this API is deprecated, as it doesn't support all digital
|
|
TV standards, doesn't provide good statistics measurements and provides
|
|
incomplete information. This is kept only to support legacy applications.</para>
|
|
|
|
&sub-frontend_legacy_api;
|
|
</section>
|