1 <section id="frontend_legacy_types">
2 <title>Frontend Legacy Data Types</title>
4 <section id="fe-type-t">
5 <title>Frontend type</title>
7 <para>For historical reasons, frontend types are named by the type of modulation
8 used in transmission. The fontend types are given by fe_type_t type, defined as:</para>
10 <table pgwide="1" frame="none" id="fe-type">
11 <title>Frontend types</title>
16 <entry>fe_type</entry>
17 <entry>Description</entry>
18 <entry><link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> equivalent type</entry>
23 <entry id="FE_QPSK"><constant>FE_QPSK</constant></entry>
24 <entry>For DVB-S standard</entry>
25 <entry><constant>SYS_DVBS</constant></entry>
28 <entry id="FE_QAM"><constant>FE_QAM</constant></entry>
29 <entry>For DVB-C annex A standard</entry>
30 <entry><constant>SYS_DVBC_ANNEX_A</constant></entry>
33 <entry id="FE_OFDM"><constant>FE_OFDM</constant></entry>
34 <entry>For DVB-T standard</entry>
35 <entry><constant>SYS_DVBT</constant></entry>
38 <entry id="FE_ATSC"><constant>FE_ATSC</constant></entry>
39 <entry>For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US.</entry>
40 <entry><constant>SYS_ATSC</constant> (terrestrial) or <constant>SYS_DVBC_ANNEX_B</constant> (cable)</entry>
42 </tbody></tgroup></table>
44 <para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're
45 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.
48 <para>In the old days, &dvb-frontend-info; used to contain
49 <constant>fe_type_t</constant> field to indicate the delivery systems,
50 filled with either FE_QPSK, FE_QAM, FE_OFDM or FE_ATSC. While this is
51 still filled to keep backward compatibility, the usage of this
52 field is deprecated, as it can report just one delivery system, but some
53 devices support multiple delivery systems. Please use
54 <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead.
56 <para>On devices that support multiple delivery systems,
57 &dvb-frontend-info;::<constant>fe_type_t</constant> is filled with the
58 currently standard, as selected by the last call to
59 <link linkend="FE_GET_PROPERTY">FE_SET_PROPERTY</link>
60 using the &DTV-DELIVERY-SYSTEM; property.</para>
63 <section id="fe-bandwidth-t">
64 <title>Frontend bandwidth</title>
66 <table pgwide="1" frame="none" id="fe-bandwidth">
67 <title>enum fe_bandwidth</title>
73 <entry>Description</entry>
78 <entry>BANDWIDTH_AUTO</entry>
79 <entry>Autodetect bandwidth (if supported)</entry>
81 <entry>BANDWIDTH_1_712_MHZ</entry>
82 <entry>1.712 MHz</entry>
84 <entry>BANDWIDTH_5_MHZ</entry>
87 <entry>BANDWIDTH_6_MHZ</entry>
90 <entry>BANDWIDTH_7_MHZ</entry>
93 <entry>BANDWIDTH_8_MHZ</entry>
96 <entry>BANDWIDTH_10_MHZ</entry>
106 <section id="dvb-frontend-parameters">
107 <title>frontend parameters</title>
108 <para>The kind of parameters passed to the frontend device for tuning depend on
109 the kind of hardware you are using.</para>
110 <para>The struct <constant>dvb_frontend_parameters</constant> uses an
111 union with specific per-system parameters. However, as newer delivery systems
112 required more data, the structure size weren't enough to fit, and just
113 extending its size would break the existing applications. So, those parameters
114 were replaced by the usage of <link linkend="FE_GET_PROPERTY">
115 <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> ioctl's. The
116 new API is flexible enough to add new parameters to existing delivery systems,
117 and to add newer delivery systems.</para>
118 <para>So, newer applications should use <link linkend="FE_GET_PROPERTY">
119 <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in
120 order to be able to support the newer System Delivery like DVB-S2, DVB-T2,
121 DVB-C2, ISDB, etc.</para>
122 <para>All kinds of parameters are combined as an union in the FrontendParameters structure:
124 struct dvb_frontend_parameters {
125 uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/
126 /⋆ intermediate frequency in kHz for QPSK ⋆/
127 &fe-spectral-inversion-t; inversion;
129 struct dvb_qpsk_parameters qpsk;
130 struct dvb_qam_parameters qam;
131 struct dvb_ofdm_parameters ofdm;
132 struct dvb_vsb_parameters vsb;
135 </programlisting></para>
136 <para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate
137 frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
138 the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
139 OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz.
142 <section id="dvb-qpsk-parameters">
143 <title>QPSK parameters</title>
144 <para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para>
146 struct dvb_qpsk_parameters {
147 uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/
148 &fe-code-rate-t; fec_inner; /⋆ forward error correction (see above) ⋆/
153 <section id="dvb-qam-parameters">
154 <title>QAM parameters</title>
155 <para>for cable QAM frontend you use the <constant>dvb_qam_parameters</constant> structure:</para>
157 struct dvb_qam_parameters {
158 uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/
159 &fe-code-rate-t; fec_inner; /⋆ forward error correction (see above) ⋆/
160 &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/
165 <section id="dvb-vsb-parameters">
166 <title>VSB parameters</title>
167 <para>ATSC frontends are supported by the <constant>dvb_vsb_parameters</constant> structure:</para>
169 struct dvb_vsb_parameters {
170 &fe-modulation-t; modulation; /⋆ modulation type (see above) ⋆/
175 <section id="dvb-ofdm-parameters">
176 <title>OFDM parameters</title>
177 <para>DVB-T frontends are supported by the <constant>dvb_ofdm_parameters</constant> structure:</para>
179 struct dvb_ofdm_parameters {
180 &fe-bandwidth-t; bandwidth;
181 &fe-code-rate-t; code_rate_HP; /⋆ high priority stream code rate ⋆/
182 &fe-code-rate-t; code_rate_LP; /⋆ low priority stream code rate ⋆/
183 &fe-modulation-t; constellation; /⋆ modulation type (see above) ⋆/
184 &fe-transmit-mode-t; transmission_mode;
185 &fe-guard-interval-t; guard_interval;
186 fe_hierarchy_t hierarchy_information;
192 <section id="dvb-frontend-event">
193 <title>frontend events</title>
195 struct dvb_frontend_event {
197 struct dvb_frontend_parameters parameters;
203 <section id="frontend_fcalls">
204 <title>Frontend Legacy Function Calls</title>
206 <para>Those functions are defined at DVB version 3. The support is kept in
207 the kernel due to compatibility issues only. Their usage is strongly
208 not recommended</para>
210 <section id="FE_READ_BER">
211 <title>FE_READ_BER</title>
214 <informaltable><tgroup cols="1"><tbody><row><entry
216 <para>This ioctl call returns the bit error rate for the signal currently
217 received/demodulated by the front-end. For this command, read-only access to
218 the device is sufficient.</para>
220 </row></tbody></tgroup></informaltable>
223 <informaltable><tgroup cols="1"><tbody><row><entry
225 <para>int ioctl(int fd, int request = <link linkend="FE_READ_BER">FE_READ_BER</link>,
226 uint32_t ⋆ber);</para>
228 </row></tbody></tgroup></informaltable>
231 <informaltable><tgroup cols="2"><tbody><row><entry
236 <para>File descriptor returned by a previous call to open().</para>
240 <para>int request</para>
243 <para>Equals <link linkend="FE_READ_BER">FE_READ_BER</link> for this command.</para>
247 <para>uint32_t *ber</para>
250 <para>The bit error rate is stored into *ber.</para>
252 </row></tbody></tgroup></informaltable>
257 <section id="FE_READ_SNR">
258 <title>FE_READ_SNR</title>
262 <informaltable><tgroup cols="1"><tbody><row><entry
264 <para>This ioctl call returns the signal-to-noise ratio for the signal currently received
265 by the front-end. For this command, read-only access to the device is sufficient.</para>
267 </row></tbody></tgroup></informaltable>
270 <informaltable><tgroup cols="1"><tbody><row><entry
272 <para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, uint16_t
275 </row></tbody></tgroup></informaltable>
278 <informaltable><tgroup cols="2"><tbody><row><entry
283 <para>File descriptor returned by a previous call to open().</para>
287 <para>int request</para>
290 <para>Equals <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para>
294 <para>uint16_t *snr</para>
297 <para>The signal-to-noise ratio is stored into *snr.</para>
299 </row></tbody></tgroup></informaltable>
304 <section id="FE_READ_SIGNAL_STRENGTH">
305 <title>FE_READ_SIGNAL_STRENGTH</title>
308 <informaltable><tgroup cols="1"><tbody><row><entry
310 <para>This ioctl call returns the signal strength value for the signal currently received
311 by the front-end. For this command, read-only access to the device is sufficient.</para>
313 </row></tbody></tgroup></informaltable>
316 <informaltable><tgroup cols="1"><tbody><row><entry
318 <para>int ioctl( int fd, int request =
319 <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, uint16_t ⋆strength);</para>
321 </row></tbody></tgroup></informaltable>
325 <informaltable><tgroup cols="2"><tbody><row><entry
330 <para>File descriptor returned by a previous call to open().</para>
334 <para>int request</para>
337 <para>Equals <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this
342 <para>uint16_t *strength</para>
345 <para>The signal strength value is stored into *strength.</para>
347 </row></tbody></tgroup></informaltable>
352 <section id="FE_READ_UNCORRECTED_BLOCKS">
353 <title>FE_READ_UNCORRECTED_BLOCKS</title>
356 <informaltable><tgroup cols="1"><tbody><row><entry
358 <para>This ioctl call returns the number of uncorrected blocks detected by the device
359 driver during its lifetime. For meaningful measurements, the increment in block
360 count during a specific time interval should be calculated. For this command,
361 read-only access to the device is sufficient.</para>
365 <para>Note that the counter will wrap to zero after its maximum count has been
368 </row></tbody></tgroup></informaltable>
371 <informaltable><tgroup cols="1"><tbody><row><entry
373 <para>int ioctl( int fd, int request =
374 <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t ⋆ublocks);</para>
376 </row></tbody></tgroup></informaltable>
379 <informaltable><tgroup cols="2"><tbody><row><entry
384 <para>File descriptor returned by a previous call to open().</para>
388 <para>int request</para>
391 <para>Equals <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this
396 <para>uint32_t *ublocks</para>
399 <para>The total number of uncorrected blocks seen by the driver
402 </row></tbody></tgroup></informaltable>
407 <section id="FE_SET_FRONTEND">
408 <title>FE_SET_FRONTEND</title>
411 <informaltable><tgroup cols="1"><tbody><row><entry
413 <para>This ioctl call starts a tuning operation using specified parameters. The result
414 of this call will be successful if the parameters were valid and the tuning could
415 be initiated. The result of the tuning operation in itself, however, will arrive
416 asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and
417 FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before
418 the previous one was completed, the previous operation will be aborted in favor
419 of the new one. This command requires read/write access to the device.</para>
421 </row></tbody></tgroup></informaltable>
425 <informaltable><tgroup cols="1"><tbody><row><entry
427 <para>int ioctl(int fd, int request = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>,
428 struct dvb_frontend_parameters ⋆p);</para>
430 </row></tbody></tgroup></informaltable>
433 <informaltable><tgroup cols="2"><tbody><row><entry
438 <para>File descriptor returned by a previous call to open().</para>
442 <para>int request</para>
445 <para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
450 dvb_frontend_parameters
454 <para>Points to parameters for tuning operation.</para>
456 </row></tbody></tgroup></informaltable>
459 <informaltable><tgroup cols="2"><tbody><row><entry
464 <para>Maximum supported symbol rate reached.</para>
466 </row></tbody></tgroup></informaltable>
469 <section id="FE_GET_FRONTEND">
470 <title>FE_GET_FRONTEND</title>
473 <informaltable><tgroup cols="1"><tbody><row><entry
475 <para>This ioctl call queries the currently effective frontend parameters. For this
476 command, read-only access to the device is sufficient.</para>
478 </row></tbody></tgroup></informaltable>
482 <informaltable><tgroup cols="1"><tbody><row><entry
484 <para>int ioctl(int fd, int request = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>,
485 struct dvb_frontend_parameters ⋆p);</para>
487 </row></tbody></tgroup></informaltable>
491 <informaltable><tgroup cols="2"><tbody><row><entry
496 <para>File descriptor returned by a previous call to open().</para>
500 <para>int request</para>
503 <para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
508 dvb_frontend_parameters
512 <para>Points to parameters for tuning operation.</para>
514 </row></tbody></tgroup></informaltable>
517 <informaltable><tgroup cols="2"><tbody><row><entry
522 <para>Maximum supported symbol rate reached.</para>
524 </row></tbody></tgroup></informaltable>
528 <section id="FE_GET_EVENT">
529 <title>FE_GET_EVENT</title>
532 <informaltable><tgroup cols="1"><tbody><row><entry
534 <para>This ioctl call returns a frontend event if available. If an event is not
535 available, the behavior depends on whether the device is in blocking or
536 non-blocking mode. In the latter case, the call fails immediately with errno
537 set to EWOULDBLOCK. In the former case, the call blocks until an event
538 becomes available.</para>
542 <para>The standard Linux poll() and/or select() system calls can be used with the
543 device file descriptor to watch for new events. For select(), the file descriptor
544 should be included in the exceptfds argument, and for poll(), POLLPRI should
545 be specified as the wake-up condition. Since the event queue allocated is
546 rather small (room for 8 events), the queue must be serviced regularly to avoid
547 overflow. If an overflow happens, the oldest event is discarded from the queue,
548 and an error (EOVERFLOW) occurs the next time the queue is read. After
549 reporting the error condition in this fashion, subsequent
550 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link>
551 calls will return events from the queue as usual.</para>
555 <para>For the sake of implementation simplicity, this command requires read/write
556 access to the device.</para>
558 </row></tbody></tgroup></informaltable>
562 <informaltable><tgroup cols="1"><tbody><row><entry
564 <para>int ioctl(int fd, int request = QPSK_GET_EVENT,
565 struct dvb_frontend_event ⋆ev);</para>
567 </row></tbody></tgroup></informaltable>
571 <informaltable><tgroup cols="2"><tbody><row><entry
576 <para>File descriptor returned by a previous call to open().</para>
580 <para>int request</para>
583 <para>Equals <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> for this command.</para>
592 <para>Points to the location where the event,</para>
598 <para>if any, is to be stored.</para>
600 </row></tbody></tgroup></informaltable>
603 <informaltable><tgroup cols="2"><tbody><row><entry
605 <para>EWOULDBLOCK</para>
608 <para>There is no event pending, and the device is in
609 non-blocking mode.</para>
613 <para>EOVERFLOW</para>
616 <para>Overflow in event queue - one or more events were lost.</para>
618 </row></tbody></tgroup></informaltable>
621 <section id="FE_DISHNETWORK_SEND_LEGACY_CMD">
622 <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title>
623 <para>DESCRIPTION</para>
624 <informaltable><tgroup cols="1"><tbody><row>
626 <para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para>
627 <para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para>
628 <para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</para>
630 </row></tbody></tgroup></informaltable>
632 <para>SYNOPSIS</para>
633 <informaltable><tgroup cols="1"><tbody><row>
635 <para>int ioctl(int fd, int request =
636 <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para>
638 </row></tbody></tgroup></informaltable>
640 <para>PARAMETERS</para>
641 <informaltable><tgroup cols="2"><tbody><row>
643 <para>unsigned long cmd</para>
647 sends the specified raw cmd to the dish via DISEqC.
650 </row></tbody></tgroup></informaltable>