DVB Frontend API

Frontend Data Types

frontend type For historical reasons frontend types are named after the type of modulation used in transmission. typedef enum fe_type { FE_QPSK, /⋆ DVB-S ⋆/ FE_QAM, /⋆ DVB-C ⋆/ FE_OFDM /⋆ DVB-T ⋆/ } fe_type_t;

frontend capabilities Capabilities describe what a frontend can do. Some capabilities can only be supported for a specific frontend type. typedef enum fe_caps { FE_IS_STUPID = 0, FE_CAN_INVERSION_AUTO = 0x1, FE_CAN_FEC_1_2 = 0x2, FE_CAN_FEC_2_3 = 0x4, FE_CAN_FEC_3_4 = 0x8, FE_CAN_FEC_4_5 = 0x10, FE_CAN_FEC_5_6 = 0x20, FE_CAN_FEC_6_7 = 0x40, FE_CAN_FEC_7_8 = 0x80, FE_CAN_FEC_8_9 = 0x100, FE_CAN_FEC_AUTO = 0x200, FE_CAN_QPSK = 0x400, FE_CAN_QAM_16 = 0x800, FE_CAN_QAM_32 = 0x1000, FE_CAN_QAM_64 = 0x2000, FE_CAN_QAM_128 = 0x4000, FE_CAN_QAM_256 = 0x8000, FE_CAN_QAM_AUTO = 0x10000, FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, FE_CAN_BANDWIDTH_AUTO = 0x40000, FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, FE_CAN_HIERARCHY_AUTO = 0x100000, FE_CAN_8VSB = 0x200000, FE_CAN_16VSB = 0x400000, FE_HAS_EXTENDED_CAPS = 0x800000, FE_CAN_TURBO_FEC = 0x8000000, FE_CAN_2G_MODULATION = 0x10000000, FE_NEEDS_BENDING = 0x20000000, FE_CAN_RECOVER = 0x40000000, FE_CAN_MUTE_TS = 0x80000000 } fe_caps_t;

frontend information Information about the frontend ca be queried with FE_GET_INFO. struct dvb_frontend_info { char name[128]; fe_type_t type; uint32_t frequency_min; uint32_t frequency_max; uint32_t frequency_stepsize; uint32_t frequency_tolerance; uint32_t symbol_rate_min; uint32_t symbol_rate_max; uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ uint32_t notifier_delay; /⋆ ms ⋆/ fe_caps_t caps; };

diseqc master command A message sent from the frontend to DiSEqC capable equipment. struct dvb_diseqc_master_cmd { uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ };

diseqc slave reply A reply to the frontend from DiSEqC 2.0 capable equipment. 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 ⋆/

diseqc slave reply The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation (horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec. typedef enum fe_sec_voltage { SEC_VOLTAGE_13, SEC_VOLTAGE_18 } fe_sec_voltage_t;

SEC continuous tone The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec. typedef enum fe_sec_tone_mode { SEC_TONE_ON, SEC_TONE_OFF } fe_sec_tone_mode_t;

SEC tone burst The 22KHz tone burst is usually used with non-DiSEqC capable switches to select between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to be switched consistently to the DiSEqC commands as described in the DiSEqC spec. typedef enum fe_sec_mini_cmd { SEC_MINI_A, SEC_MINI_B } fe_sec_mini_cmd_t;

frontend status Several functions of the frontend device use the fe_status data type defined by typedef enum fe_status { FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ } fe_status_t; /⋆ application is recommned to reset ⋆/ to indicate the current state and/or state changes of the frontend hardware.

frontend parameters The kind of parameters passed to the frontend device for tuning depend on the kind of hardware you are using. 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; } u; }; For satellite QPSK frontends you have to use the QPSKParameters member defined by 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 QAMParameters 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) ⋆/ }; DVB-T frontends are supported by the OFDMParamters 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; }; 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. The Inversion field can take one of these values: typedef enum fe_spectral_inversion { INVERSION_OFF, INVERSION_ON, INVERSION_AUTO } fe_spectral_inversion_t; It indicates if spectral inversion should be presumed or not. In the automatic setting (INVERSION_AUTO) the hardware will try to figure out the correct setting by itself. The possible values for the FEC_inner field are 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 } fe_code_rate_t; which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto detection. For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature modulation mode which can be one of the following: typedef enum fe_modulation { QPSK, QAM_16, QAM_32, QAM_64, QAM_128, QAM_256, QAM_AUTO } fe_modulation_t; Finally, there are several more parameters for OFDM: typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, TRANSMISSION_MODE_8K, TRANSMISSION_MODE_AUTO } fe_transmit_mode_t; typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, BANDWIDTH_7_MHZ, BANDWIDTH_6_MHZ, BANDWIDTH_AUTO } fe_bandwidth_t; typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, GUARD_INTERVAL_1_16, GUARD_INTERVAL_1_8, GUARD_INTERVAL_1_4, GUARD_INTERVAL_AUTO } fe_guard_interval_t; typedef enum fe_hierarchy { HIERARCHY_NONE, HIERARCHY_1, HIERARCHY_2, HIERARCHY_4, HIERARCHY_AUTO } fe_hierarchy_t;

frontend events struct dvb_frontend_event { fe_status_t status; struct dvb_frontend_parameters parameters; };

Frontend Function Calls

open() DESCRIPTION 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 FE_GET_INFO. 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.) 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. SYNOPSIS int open(const char ⋆deviceName, int flags); PARAMETERS const char *deviceName Name of specific video device. int flags A bit-wise OR of the following flags: O_RDONLY read-only access O_RDWR read/write access O_NONBLOCK open in non-blocking mode (blocking mode is the default) ERRORS ENODEV Device driver not loaded/available. EINTERNAL Internal error. EBUSY Device or resource busy. EINVAL Invalid argument.

close() DESCRIPTION This system call closes a previously opened front-end device. After closing a front-end device, its corresponding hardware might be powered down automatically. SYNOPSIS int close(int fd); PARAMETERS int fd File descriptor returned by a previous call to open(). ERRORS EBADF fd is not a valid open file descriptor.

FE_READ_STATUS DESCRIPTION This ioctl call returns status information about the front-end. This call only requires read-only access to the device. SYNOPSIS int ioctl(int fd, int request = FE_READ_STATUS, fe_status_t ⋆status); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_READ_STATUS for this command. struct fe_status_t *status Points to the location where the front-end status word is to be stored. ERRORS EBADF fd is not a valid open file descriptor. EFAULT status points to invalid address.

FE_READ_BER 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. ERRORS EBADF fd is not a valid open file descriptor. EFAULT ber points to invalid address. ENOSIGNAL There is no signal, thus no meaningful bit error rate. Also returned if the front-end is not turned on. ENOSYS Function not available for this device.

FE_READ_SNR 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, int16_t ⋆snr); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_READ_SNR for this command. int16_t *snr The signal-to-noise ratio is stored into *snr. ERRORS EBADF fd is not a valid open file descriptor. EFAULT snr points to invalid address. ENOSIGNAL There is no signal, thus no meaningful signal strength value. Also returned if front-end is not turned on. ENOSYS Function not available for this device.

FE_READ_SIGNAL_STRENGTH 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, int16_t ⋆strength); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_READ_SIGNAL_STRENGTH for this command. int16_t *strength The signal strength value is stored into *strength. ERRORS EBADF fd is not a valid open file descriptor. EFAULT status points to invalid address. ENOSIGNAL There is no signal, thus no meaningful signal strength value. Also returned if front-end is not turned on. ENOSYS Function not available for this device.

FE_READ_UNCORRECTED_BLOCKS 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. ERRORS EBADF fd is not a valid open file descriptor. EFAULT ublocks points to invalid address. ENOSYS Function not available for this device.

FE_SET_FRONTEND 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. ERRORS EBADF fd is not a valid open file descriptor. EFAULT p points to invalid address. EINVAL Maximum supported symbol rate reached.

FE_GET_FRONTEND 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. ERRORS EBADF fd is not a valid open file descriptor. EFAULT p points to invalid address. EINVAL Maximum supported symbol rate reached.

FE_GET_EVENT 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. ERRORS EBADF fd is not a valid open file descriptor. EFAULT ev points to invalid address. 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.

FE_GET_INFO DESCRIPTION This ioctl call returns information about the front-end. This call only requires read-only access to the device. SYNOPSIS int ioctl(int fd, int request = FE_GET_INFO, struct dvb_frontend_info ⋆info); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_GET_INFO for this command. struct dvb_frontend_info *info Points to the location where the front-end information is to be stored. ERRORS EBADF fd is not a valid open file descriptor. EFAULT info points to invalid address.

FE_DISEQC_RESET_OVERLOAD DESCRIPTION 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. SYNOPSIS int ioctl(int fd, int request = FE_DISEQC_RESET_OVERLOAD); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_DISEQC_RESET_OVERLOAD for this command. ERRORS EBADF fd is not a valid file descriptor. EPERM Permission denied (needs read/write access). EINTERNAL Internal error in the device driver.

FE_DISEQC_SEND_MASTER_CMD DESCRIPTION This ioctl call is used to send a a DiSEqC command. SYNOPSIS int ioctl(int fd, int request = FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd ⋆cmd); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_DISEQC_SEND_MASTER_CMD for this command. struct dvb_diseqc_master_cmd *cmd Pointer to the command to be transmitted. ERRORS EBADF fd is not a valid file descriptor. EFAULT Seq points to an invalid address. EINVAL The data structure referred to by seq is invalid in some way. EPERM Permission denied (needs read/write access). EINTERNAL Internal error in the device driver.

FE_DISEQC_RECV_SLAVE_REPLY DESCRIPTION This ioctl call is used to receive reply to a DiSEqC 2.0 command. SYNOPSIS int ioctl(int fd, int request = FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply ⋆reply); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_DISEQC_RECV_SLAVE_REPLY for this command. struct dvb_diseqc_slave_reply *reply Pointer to the command to be received. ERRORS EBADF fd is not a valid file descriptor. EFAULT Seq points to an invalid address. EINVAL The data structure referred to by seq is invalid in some way. EPERM Permission denied (needs read/write access). EINTERNAL Internal error in the device driver.

FE_DISEQC_SEND_BURST DESCRIPTION This ioctl call is used to send a 22KHz tone burst. SYNOPSIS int ioctl(int fd, int request = FE_DISEQC_SEND_BURST, fe_sec_mini_cmd_t burst); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_DISEQC_SEND_BURST for this command. fe_sec_mini_cmd_t burst burst A or B. ERRORS EBADF fd is not a valid file descriptor. EFAULT Seq points to an invalid address. EINVAL The data structure referred to by seq is invalid in some way. EPERM Permission denied (needs read/write access). EINTERNAL Internal error in the device driver.

FE_SET_TONE DESCRIPTION This call is used to set the generation of the continuous 22kHz tone. This call requires read/write permissions. SYNOPSIS int ioctl(int fd, int request = FE_SET_TONE, fe_sec_tone_mode_t tone); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_SET_TONE for this command. fe_sec_tone_mode_t tone The requested tone generation mode (on/off). ERRORS ENODEV Device driver not loaded/available. EBUSY Device or resource busy. EINVAL Invalid argument. EPERM File not opened with read permissions. EINTERNAL Internal error in the device driver.

FE_SET_VOLTAGE DESCRIPTION This call is used to set the bus voltage. This call requires read/write permissions. SYNOPSIS int ioctl(int fd, int request = FE_SET_VOLTAGE, fe_sec_voltage_t voltage); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_SET_VOLTAGE for this command. fe_sec_voltage_t voltage The requested bus voltage. ERRORS ENODEV Device driver not loaded/available. EBUSY Device or resource busy. EINVAL Invalid argument. EPERM File not opened with read permissions. EINTERNAL Internal error in the device driver.

FE_ENABLE_HIGH_LNB_VOLTAGE DESCRIPTION If high != 0 enables slightly higher voltages instead of 13/18V (to compensate for long cables). This call requires read/write permissions. Not all DVB adapters support this ioctl. SYNOPSIS int ioctl(int fd, int request = FE_ENABLE_HIGH_LNB_VOLTAGE, int high); PARAMETERS int fd File descriptor returned by a previous call to open(). int request Equals FE_SET_VOLTAGE for this command. int high The requested bus voltage. ERRORS ENODEV Device driver not loaded/available. EBUSY Device or resource busy. EINVAL Invalid argument. EPERM File not opened with read permissions. EINTERNAL Internal error in the device driver.

FE_SET_FRONTEND_TUNE_MODE DESCRIPTION Allow setting tuner mode flags to the frontend. SYNOPSIS int ioctl(int fd, int request = FE_SET_FRONTEND_TUNE_MODE, unsigned int flags); PARAMETERS unsigned int flags FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "normal" tuning behaviour. Additionally, there will be no automatic monitoring of the lock status, and hence no frontend events will be generated. If a frontend device is closed, this flag will be automatically turned off when the device is reopened read-write. ERRORS EINVAL Invalid argument.

FE_DISHNETWORK_SEND_LEGACY_CMD 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. ERRORS There are no errors in use for this call