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.
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:
Table 9.24. Frontend types
| fe_type | Description | DTV_DELIVERY_SYSTEM equivalent type |
|---|---|---|
FE_QPSK | For DVB-S standard | SYS_DVBS |
FE_QAM | For DVB-C annex A standard | SYS_DVBC_ANNEX_A |
FE_OFDM | For DVB-T standard | SYS_DVBT |
FE_ATSC | For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used in US. | SYS_ATSC (terrestrial) or SYS_DVBC_ANNEX_B (cable) |
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 FE_GET_PROPERTY/FE_GET_SET_PROPERTY ioctl's, using the DTV_DELIVERY_SYSTEM parameter.
In the old days, struct dvb_frontend_info used to contain
fe_type_t 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
DTV_ENUM_DELSYS instead.
On devices that support multiple delivery systems,
struct dvb_frontend_info::fe_type_t is filled with the
currently standard, as selected by the last call to
FE_SET_PROPERTY
using the DTV_DELIVERY_SYSTEM property.
The kind of parameters passed to the frontend device for tuning depend on the kind of hardware you are using.
The struct dvb_frontend_parameters 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
FE_GET_PROPERTY/FE_SET_PROPERTY ioctl's. The
new API is flexible enough to add new parameters to existing delivery systems,
and to add newer delivery systems.
So, newer applications should use
FE_GET_PROPERTY/FE_SET_PROPERTY instead, in
order to be able to support the newer System Delivery like DVB-S2, DVB-T2,
DVB-C2, ISDB, etc.
All kinds of parameters are combined as an union in the FrontendParameters structure:
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;
};
In the case of QPSK frontends the frequency 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 frequency specifies the absolute frequency and is given in Hz.
For satellite QPSK frontends you have to use the dvb_qpsk_parameters structure:
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) ⋆/
};
for cable QAM frontend you use the dvb_qam_parameters structure:
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) ⋆/
};
ATSC frontends are supported by the dvb_vsb_parameters structure:
struct dvb_vsb_parameters {
fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/
};
DVB-T frontends are supported by the dvb_ofdm_parameters structure:
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;
};
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
DESCRIPTION
|
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. |
SYNOPSIS
|
int ioctl(int fd, int request = FE_READ_BER, uint32_t ⋆ber); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_READ_BER for this command. |
|
uint32_t *ber |
The bit error rate is stored into *ber. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
DESCRIPTION
|
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. |
SYNOPSIS
|
int ioctl(int fd, int request = FE_READ_SNR, uint16_t ⋆snr); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_READ_SNR for this command. |
|
uint16_t *snr |
The signal-to-noise ratio is stored into *snr. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
DESCRIPTION
|
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. |
SYNOPSIS
|
int ioctl( int fd, int request = FE_READ_SIGNAL_STRENGTH, uint16_t ⋆strength); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_READ_SIGNAL_STRENGTH for this command. |
|
uint16_t *strength |
The signal strength value is stored into *strength. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
DESCRIPTION
|
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. |
|
Note that the counter will wrap to zero after its maximum count has been reached. |
SYNOPSIS
|
int ioctl( int fd, int request = FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_READ_UNCORRECTED_BLOCKS for this command. |
|
uint32_t *ublocks |
The total number of uncorrected blocks seen by the driver so far. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
DESCRIPTION
|
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 FE_GET_EVENT and FrontendEvent.) If a new FE_SET_FRONTEND 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. |
SYNOPSIS
|
int ioctl(int fd, int request = FE_SET_FRONTEND, struct dvb_frontend_parameters ⋆p); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_SET_FRONTEND for this command. |
|
struct dvb_frontend_parameters *p |
Points to parameters for tuning operation. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
|
EINVAL |
Maximum supported symbol rate reached. |
DESCRIPTION
|
This ioctl call queries the currently effective frontend parameters. For this command, read-only access to the device is sufficient. |
SYNOPSIS
|
int ioctl(int fd, int request = FE_GET_FRONTEND, struct dvb_frontend_parameters ⋆p); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_SET_FRONTEND for this command. |
|
struct dvb_frontend_parameters *p |
Points to parameters for tuning operation. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
|
EINVAL |
Maximum supported symbol rate reached. |
DESCRIPTION
|
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. |
|
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 FE_GET_EVENT calls will return events from the queue as usual. |
|
For the sake of implementation simplicity, this command requires read/write access to the device. |
SYNOPSIS
|
int ioctl(int fd, int request = QPSK_GET_EVENT, struct dvb_frontend_event ⋆ev); |
PARAMETERS
|
int fd |
File descriptor returned by a previous call to open(). |
|
int request |
Equals FE_GET_EVENT for this command. |
|
struct dvb_frontend_event *ev |
Points to the location where the event, |
|
if any, is to be stored. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.
|
EWOULDBLOCK |
There is no event pending, and the device is in non-blocking mode. |
|
EOVERFLOW |
Overflow in event queue - one or more events were lost. |
DESCRIPTION
|
WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers. It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches. As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004. |
SYNOPSIS
|
int ioctl(int fd, int request = FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd); |
PARAMETERS
|
unsigned long cmd |
sends the specified raw cmd to the dish via DISEqC. |
RETURN VALUE
On success 0 is returned, on error -1 and the errno variable is set appropriately. The generic error codes are described at the Generic Error Codes chapter.