| ||||||||||||
| |||||||||||||
|  | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| DVB Frontend APIThe DVB frontend device controls the frontend of the DVB hardware, e.g. tuning, symbol rate, error correction, ... It is accessed through /dev/ost/qpskfe. The function calls defined in the include file frontend.h are described in detail below: Frontend API IO control calls
int open(const char *deviceName, int flags);
DESCRIPTION
This system call opens a named front-end device (e.g. /dev/qpskfe) for
subsequent use. 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.
PARAMETERS
const char *deviceName I Name of specific front-end device. In the
current implementation, /dev/qpskfe is the
only one available (QPSK satellite front-end.)
int flags I 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)
RETURNS
ENODEV Device driver not loaded/available.
EBUSY Device or resource busy.
EINVAL Invalid argument.
int close(int fd);
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, but only when this is needed to open another front-end device.
To affect an unconditional power down, it should be done explicitly using
the OST_SET_POWER_STATE ioctl.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
RETURNS
EBADF fd is not a valid open file descriptor
int ioctl(int fd, int request = OST_SELFTEST);
DESCRIPTION
This ioctl call initiates an automatic self-test of the front-end hardware.
This call requires read/write access to the device.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals OST_SELFTEST for this command.
RETURNS
0 Success
-1 Failure
int ioctl(int fd, int request = OST_SET_POWER_STATE, uint32_t state);
DESCRIPTION
This ioctl call, implemented in many OST device drivers, enables direct
control over the power state of the hardware device, which may be on, off,
standby, or suspend. The latter two are low-power modes, which disable all
functionality of the device until turned on again. In contrast to the off
state, however, the standby and suspend states resume operation in the same
state as when the device was active. The only difference between the standby
and suspend states is a different tradeoff between resume time and power
consumption power consumption may be lower in the suspend state at the
cost of a longer resume time.
A device that implements this call does not necessarily support two low-power
modes. If it only support one low-power state, or none at all, the
OST_SET_POWER_STATE operation for the missing states will still succeed, but
it will be mapped to an existing state as per this table:
number of low-power requested state resulting state
states supported
1 standby suspend
1 suspend suspend
0 standby on
0 suspend on
For other cases where a required state is missing, an error code will be
returned. This can happen if a device does not support the power-off state,
but nevertheless implements this ioctl operation for control of low-power
states.
When opening a device in read/write mode, the driver ensures that the
corresponding hardware device is turned on initially. If the device is
later turned off or put in suspend mode, it has to be explicitly turned on
again.
This call requires read/write access to the device. (Note that the power
management driver can affect the power state of devices without using this
ioctl operation, so having exclusive read/write access to a device does not
imply total control over the power state.)
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals OST_SET_POWER_STATE for this command.
uint32_t state I Requested power state. One of:
OST_POWER_ON: turn power on
OST_POWER_STANDBY: set device in standby mode
OST_POWER_SUSPEND: set device in suspend mode
OST_POWER_OFF: turn power off
RETURNS
EBADF fd is not a valid open file descriptor
EINVAL illegal state, or not available on this device
EPERM permission denied (needs read/write access)
ENOSYS Function not available for this device.
int ioctl(int fd, int request = OST_GET_POWER_STATE, uint32_t *state);
DESCRIPTION
This ioctl call, implemented in many OST device drivers, obtains the power
state of the hardware device, which may be on, off, standby, or suspend.
A device that implements this call does not necessarily support all four states.
If there is only one low-power state, the suspend state will be returned for
that state. If there is no low-power state, the on state will be reported
standby and suspend states will be equivalent to the on state.
For this command, read-only access to the device is sufficient.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals OST_GET_POWER_STATE for this command.
uint32_t *state O Pointer to a variable where the power state is
to be stored. Possible values are:
OST_POWER_ON power is on
OST_POWER_STANDBY device in
standby mode
OST_POWER_SUSPEND: device in
suspend mode
OST_POWER_OFF: power is off
RETURNS
EBADF fd is not a valid open file descriptor
EINVAL illegal state, or not available on this device
EFAULT state points to invalid address
EPERM permission denied (needs read/write access)
ENOSYS Function not available for this device.
int ioctl(int fd, int request = QPSK_READ_STATUS, feStatus *status);
DESCRIPTION
This ioctl call returns status information about the front-end.
This call only requires read-only access to the device.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_READ_STATUS for this command.
struct feStatus *status O Points to the location where the front-end
status word is to be stored.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT status points to invalid address
int ioctl(int fd, int request = FE_READ_BER, uint32_t *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.
FUNCTION PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_READ_BER for this command.
uint32_t *ber O The bit error rate, as a multiple of 10-9, is stored into *ber.
Example: a value of 2500 corresponds to a bit error
rate of 2.5 10-6, or 1 error in 400000 bits.
RETURNS
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.
int ioctl( int fd, int request = FE_READ_SIGNAL_STRENGTH, int32_t *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.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_READ_SIGNAL_STRENGTH for this
command.
int32_t *strength O The signal strength value, as a multiple of 10^-6 dBm,
is stored into *strength.
Example: a value of 12,500,000 corresponds to a signal
strength value of 12.5 dBm.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT strength 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.
int ioctl(int fd, int request = FE_READ_SNR, int32_t *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.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_READ_SNR for this command.
int32_t *snr O The signal-to-noise ratio, as a multiple of
10^-6 dB, is stored into *snr.
Example: a value of 12,300,000 corresponds
to a signal-to-noise ratio of 12.3 dB.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT snr points to invalid address
ENOSIGNAL No stable signal, thus no meaningful signal-to-
noise ratio. Also returned if front-end is not
turned on.
ENOSYS Function not available for this device.
int ioctl( int fd, int request = FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks);
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 calculated2. For this
command, read-only access to the device is sufficient.
2 Note that the counter will wrap to zero after its maximum count has
been reached (232-1).
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_READ_UNCORRECTED_BLOCKS for this command.
uint32_t *ublocks O The total number of uncorrected blocks seen
by the driver so far.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT ublocks points to invalid address
ENOSYS Function not available for this device.
int ioctl( int fd, int request = FE_GET_NEXT_FREQUENCY, uint32_t *freq);
DESCRIPTION
When scanning a frequency range, it is desirable to use a scanning step size
that is as large as possible, yet small enough to be able to lock to any signal
within the range.
This ioctl operation does just that it increments a given frequency by a
step size suitable for efficient3 scanning.
The step size used by this function may be a quite complex function of the given
frequency, hardware capabilities, and parameter settings of the device. Thus, a
returned result is only valid for the current state of the device.
For this command, read-only access to the device is sufficient.
3 Note that scanning may still be excruciatingly slow on some hardware, for
other reasons than a non-optimal scanning step size.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_GET_NEXT_FREQUENCY for this command.
uint32_t *freq I/O Input: a given frequency
Output: the frequency corresponding to
the next higher frequency setting.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT freq points to invalid address
EINVAL maximum frequency reached
ENOSYS Function not available for this device.
int ioctl( int fd, int request = FE_GET_NEXT_SYMBOL_RATE, uint32_t *symbolRate);
DESCRIPTION
When scanning a range of symbol rates (e.g. for "blind acquisition") it is
desirable to use a scanning step size that is as large as possible, yet
small enough to detect any valid signal within the range. This ioctl
operation does just that it increments a given symbol rate by a step size
suitable for efficient4 scanning.
The step size used by this function may be a quite complex function of the given
symbol rate, hardware capabilities, and parameter settings of the device.
Thus, a returned result is only valid for the current state of the device.
For this command, read-only access to the device is sufficient.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals FE_GET_NEXT_SYMBOL_RATE for this command.
uint32_t *symbolRate I/O Input: a given symbol rate Output: the symbol rate corresponding to the next
higher symbol rate setting.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT symbolRate points to invalid address
EINVAL maximum symbol rate reached
ENOSYS Function not available for this device.
int ioctl(int fd, int request = QPSK_TUNE, struct qpskParameters *p);
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 QPSK_GET_EVENT and qpskEvent.)
If a new QPSK_TUNE 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.
PARAMETERS
int fd File descriptor returned by a previous call to open().
int request Equals QPSK_TUNE for this command.
struct qpskParameters *p Points to parameters for tuning operation.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT p points to invalid address
EINVAL parameter value(s) not valid
int ioctl(int fd, int request = QPSK_GET_EVENT, struct qpskEvent *ev);
DESCRIPTION
This ioctl call returns an event of type qpskEvent 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 (EBUFFEROVERFLOW) occurs
the next time the queue is read. After reporting the error condition in this
fashion, subsequent QPSK_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.
PARAMETERS
int fd File descriptor returned by a previous call to open().
int request I Equals QPSK_GET_EVENT for this command.
struct qpskEvent *ev O Points to the location where the event, if any, is to be stored.
RETURNS
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.
EBUFFEROVERFLOW Overflow in event queue - one or more events were lost.
int ioctl(int fd, int request = QPSK_FE_INFO, struct qpskFrontendInfo *info);
DESCRIPTION
This ioctl call returns information about the front-end.
This call only requires read-only access to the device.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals QPSK_FE_INFO for this command.
struct qpskFrontendInfo *info O Points to the location where the front-end
information is to be stored.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT info points to invalid address
int ioctl(int fd, int request = QPSK_WRITE_REGISTER, struct qpskRegister *reg);
DESCRIPTION
This ioctl call is intended for hardware-specific diagnostics. It writes
an 8-bit value at an 8-bit address of a register in a chip identified by an
8-bit index.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals QPSK_WRITE_REGISTER for this command.
struct qpskRegister *reg I Specifies a value that should be written
into a specified register in a specified chip.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT reg points to and invalid address
EINVAL Register specification invalid.
int ioctl(int fd, int request = QPSK_READ_REGISTER, struct qpskRegister *reg);
DESCRIPTION
This ioctl call is intended for hardware-specific diagnostics.
It reads an 8-bit value at an 8-bit address of a register in a chip
identified by an 8-bit index.
PARAMETERS
int fd I File descriptor returned by a previous call to open().
int request I Equals QPSK_READ_REGISTER for this command.
struct qpskRegister *reg I/O I: specifies a register in a specified
chip from which a value should be read.
O: the value is read into the
qpskRegister structure.
RETURNS
EBADF fd is not a valid open file descriptor
EFAULT reg points to and invalid address
EINVAL Register specification invalid.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
