diff options
Diffstat (limited to 'Documentation/DocBook/media/dvb/frontend_legacy_api.xml')
| -rw-r--r-- | Documentation/DocBook/media/dvb/frontend_legacy_api.xml | 654 |
1 files changed, 0 insertions, 654 deletions
diff --git a/Documentation/DocBook/media/dvb/frontend_legacy_api.xml b/Documentation/DocBook/media/dvb/frontend_legacy_api.xml deleted file mode 100644 index 8fadf3a4ba44..000000000000 --- a/Documentation/DocBook/media/dvb/frontend_legacy_api.xml +++ /dev/null @@ -1,654 +0,0 @@ -<section id="frontend_legacy_types"> -<title>Frontend Legacy Data Types</title> - -<section id="fe-type-t"> -<title>Frontend type</title> - -<para>For historical reasons, frontend types are named by the type of modulation - used in transmission. The fontend types are given by fe_type_t type, defined as:</para> - -<table pgwide="1" frame="none" id="fe-type"> -<title>Frontend types</title> -<tgroup cols="3"> - &cs-def; - <thead> - <row> - <entry>fe_type</entry> - <entry>Description</entry> - <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="FE-QPSK"><constant>FE_QPSK</constant></entry> - <entry>For DVB-S standard</entry> - <entry><constant>SYS_DVBS</constant></entry> - </row> - <row> - <entry id="FE-QAM"><constant>FE_QAM</constant></entry> - <entry>For DVB-C annex A standard</entry> - <entry><constant>SYS_DVBC_ANNEX_A</constant></entry> - </row> - <row> - <entry id="FE-OFDM"><constant>FE_OFDM</constant></entry> - <entry>For DVB-T standard</entry> - <entry><constant>SYS_DVBT</constant></entry> - </row> - <row> - <entry id="FE-ATSC"><constant>FE_ATSC</constant></entry> - <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry> - <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry> - </row> -</tbody></tgroup></table> - -<para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're -supported via the new <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter. -</para> - -<para>In the old days, &dvb-frontend-info; used to contain - <constant>fe_type_t</constant> field to indicate the delivery systems, - filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this is - still filled to keep backward compatibility, the usage of this - field is deprecated, as it can report just one delivery system, but some - devices support multiple delivery systems. Please use - <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead. -</para> -<para>On devices that support multiple delivery systems, - &dvb-frontend-info;::<constant>fe_type_t</constant> is filled with the - currently standard, as selected by the last call to - <link linkend="FE_GET_PROPERTY">FE_SET_PROPERTY</link> - using the &DTV-DELIVERY-SYSTEM; property.</para> -</section> - -<section id="fe-bandwidth-t"> -<title>Frontend bandwidth</title> - -<table pgwide="1" frame="none" id="fe-bandwidth"> - <title>enum fe_bandwidth</title> - <tgroup cols="2"> - &cs-def; - <thead> - <row> - <entry>ID</entry> - <entry>Description</entry> - </row> - </thead> - <tbody valign="top"> - <row> - <entry id="BANDWIDTH-AUTO"><constant>BANDWIDTH_AUTO</constant></entry> - <entry>Autodetect bandwidth (if supported)</entry> - </row><row> - <entry id="BANDWIDTH-1-712-MHZ"><constant>BANDWIDTH_1_712_MHZ</constant></entry> - <entry>1.712 MHz</entry> - </row><row> - <entry id="BANDWIDTH-5-MHZ"><constant>BANDWIDTH_5_MHZ</constant></entry> - <entry>5 MHz</entry> - </row><row> - <entry id="BANDWIDTH-6-MHZ"><constant>BANDWIDTH_6_MHZ</constant></entry> - <entry>6 MHz</entry> - </row><row> - <entry id="BANDWIDTH-7-MHZ"><constant>BANDWIDTH_7_MHZ</constant></entry> - <entry>7 MHz</entry> - </row><row> - <entry id="BANDWIDTH-8-MHZ"><constant>BANDWIDTH_8_MHZ</constant></entry> - <entry>8 MHz</entry> - </row><row> - <entry id="BANDWIDTH-10-MHZ"><constant>BANDWIDTH_10_MHZ</constant></entry> - <entry>10 MHz</entry> - </row> - </tbody> - </tgroup> -</table> - -</section> - -<section id="dvb-frontend-parameters"> -<title>frontend parameters</title> -<para>The kind of parameters passed to the frontend device for tuning depend on -the kind of hardware you are using.</para> -<para>The struct <constant>dvb_frontend_parameters</constant> uses an -union with specific per-system parameters. However, as newer delivery systems -required more data, the structure size weren't enough to fit, and just -extending its size would break the existing applications. So, those parameters -were replaced by the usage of <link linkend="FE_GET_PROPERTY"> -<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The -new API is flexible enough to add new parameters to existing delivery systems, -and to add newer delivery systems.</para> -<para>So, newer applications should use <link linkend="FE_GET_PROPERTY"> -<constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in -order to be able to support the newer System Delivery like DVB-S2, DVB-T2, -DVB-C2, ISDB, etc.</para> -<para>All kinds of parameters are combined as an union in the FrontendParameters structure: -<programlisting> -struct dvb_frontend_parameters { - uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ - /⋆ intermediate frequency in kHz for QPSK ⋆/ - &fe-spectral-inversion-t; inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - struct dvb_vsb_parameters vsb; - } u; -}; -</programlisting></para> -<para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of -the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and -OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz. -</para> - -<section id="dvb-qpsk-parameters"> -<title>QPSK parameters</title> -<para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para> -<programlisting> - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - &fe-code-rate-t; fec_inner; /⋆ forward error correction (see above) ⋆/ - }; -</programlisting> -</section> - -<section id="dvb-qam-parameters"> -<title>QAM parameters</title> -<para>for cable QAM frontend you use the <constant>dvb_qam_parameters</constant> structure:</para> -<programlisting> - struct dvb_qam_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - &fe-code-rate-t; fec_inner; /⋆ forward error correction (see above) ⋆/ - &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/ - }; -</programlisting> -</section> - -<section id="dvb-vsb-parameters"> -<title>VSB parameters</title> -<para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para> -<programlisting> -struct dvb_vsb_parameters { - &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/ -}; -</programlisting> -</section> - -<section id="dvb-ofdm-parameters"> -<title>OFDM parameters</title> -<para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</constant> structure:</para> -<programlisting> - struct dvb_ofdm_parameters { - &fe-bandwidth-t; bandwidth; - &fe-code-rate-t; code_rate_HP; /⋆ high priority stream code rate ⋆/ - &fe-code-rate-t; code_rate_LP; /⋆ low priority stream code rate ⋆/ - &fe-modulation-t; constellation; /⋆ modulation type (see above) ⋆/ - &fe-transmit-mode-t; transmission_mode; - &fe-guard-interval-t; guard_interval; - &fe-hierarchy-t; hierarchy_information; - }; -</programlisting> -</section> -</section> - -<section id="dvb-frontend-event"> -<title>frontend events</title> - <programlisting> - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; -</programlisting> - </section> -</section> - -<section id="frontend_legacy_fcalls"> -<title>Frontend Legacy Function Calls</title> - -<para>Those functions are defined at DVB version 3. The support is kept in - the kernel due to compatibility issues only. Their usage is strongly - not recommended</para> - -<section id="FE_READ_BER"> -<title>FE_READ_BER</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the bit error rate for the signal currently - received/demodulated by the front-end. For this command, read-only access to - the device is sufficient.</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_BER">FE_READ_BER</link>, - uint32_t ⋆ber);</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_BER">FE_READ_BER</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint32_t *ber</para> -</entry><entry - align="char"> -<para>The bit error rate is stored into *ber.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_SNR"> -<title>FE_READ_SNR</title> - -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the signal-to-noise ratio for the signal currently received - by the front-end. For this command, read-only access to the device is sufficient.</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_SNR">FE_READ_SNR</link>, uint16_t - ⋆snr);</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_SNR">FE_READ_SNR</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint16_t *snr</para> -</entry><entry - align="char"> -<para>The signal-to-noise ratio is stored into *snr.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_SIGNAL_STRENGTH"> -<title>FE_READ_SIGNAL_STRENGTH</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the signal strength value for the signal currently received - by the front-end. For this command, read-only access to the device is sufficient.</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_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_t ⋆strength);</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_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint16_t *strength</para> -</entry><entry - align="char"> -<para>The signal strength value is stored into *strength.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_READ_UNCORRECTED_BLOCKS"> -<title>FE_READ_UNCORRECTED_BLOCKS</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the number of uncorrected blocks detected by the device - driver during its lifetime. For meaningful measurements, the increment in block - count during a specific time interval should be calculated. For this command, - read-only access to the device is sufficient.</para> -</entry> - </row><row><entry - align="char"> -<para>Note that the counter will wrap to zero after its maximum count has been - reached.</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_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t ⋆ublocks);</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_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint32_t *ublocks</para> -</entry><entry - align="char"> -<para>The total number of uncorrected blocks seen by the driver - so far.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -<section id="FE_SET_FRONTEND"> -<title>FE_SET_FRONTEND</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call starts a tuning operation using specified parameters. The result - of this call will be successful if the parameters were valid and the tuning could - be initiated. The result of the tuning operation in itself, however, will arrive - asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and - FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before - the previous one was completed, the previous operation will be aborted in favor - of the new one. This command requires read/write 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_SET_FRONTEND">FE_SET_FRONTEND</link>, - struct dvb_frontend_parameters ⋆p);</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_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_parameters - *p</para> -</entry><entry - align="char"> -<para>Points to parameters for tuning operation.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Maximum supported symbol rate reached.</para> -</entry> -</row></tbody></tgroup></informaltable> -</section> - -<section id="FE_GET_FRONTEND"> -<title>FE_GET_FRONTEND</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call queries the currently effective frontend parameters. For this - command, read-only access to the device is sufficient.</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_GET_FRONTEND">FE_GET_FRONTEND</link>, - struct dvb_frontend_parameters ⋆p);</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_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_parameters - *p</para> -</entry><entry - align="char"> -<para>Points to parameters for tuning operation.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Maximum supported symbol rate reached.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section> - -<section id="FE_GET_EVENT"> -<title>FE_GET_EVENT</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns a frontend event if available. If an event is not - available, the behavior depends on whether the device is in blocking or - non-blocking mode. In the latter case, the call fails immediately with errno - set to EWOULDBLOCK. In the former case, the call blocks until an event - becomes available.</para> -</entry> - </row><row><entry - align="char"> -<para>The standard Linux poll() and/or select() system calls can be used with the - device file descriptor to watch for new events. For select(), the file descriptor - should be included in the exceptfds argument, and for poll(), POLLPRI should - be specified as the wake-up condition. Since the event queue allocated is - rather small (room for 8 events), the queue must be serviced regularly to avoid - overflow. If an overflow happens, the oldest event is discarded from the queue, - and an error (EOVERFLOW) occurs the next time the queue is read. After - reporting the error condition in this fashion, subsequent - <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> - calls will return events from the queue as usual.</para> -</entry> - </row><row><entry - align="char"> -<para>For the sake of implementation simplicity, this command requires read/write - 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 = QPSK_GET_EVENT, - struct dvb_frontend_event ⋆ev);</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_GET_EVENT">FE_GET_EVENT</link> for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_event - *ev</para> -</entry><entry - align="char"> -<para>Points to the location where the event,</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>if any, is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -<para>Overflow in event queue - one or more events were lost.</para> -</entry> -</row></tbody></tgroup></informaltable> -</section> - -<section id="FE_DISHNETWORK_SEND_LEGACY_CMD"> - <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title> -<para>DESCRIPTION</para> -<informaltable><tgroup cols="1"><tbody><row> -<entry align="char"> -<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para> -<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para> -<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</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_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para> -</entry> -</row></tbody></tgroup></informaltable> - -<para>PARAMETERS</para> -<informaltable><tgroup cols="2"><tbody><row> -<entry align="char"> - <para>unsigned long cmd</para> -</entry> -<entry align="char"> -<para> -sends the specified raw cmd to the dish via DISEqC. -</para> -</entry> - </row></tbody></tgroup></informaltable> - -&return-value-dvb; -</section> - -</section> |