diff options
Diffstat (limited to 'dvb-spec/dvbapi/frontend.tex')
| -rw-r--r-- | dvb-spec/dvbapi/frontend.tex | 689 |
1 files changed, 362 insertions, 327 deletions
diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index e41ef3d54..bb177df1b 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -1,52 +1,176 @@ \devsec{DVB Frontend API} The DVB frontend device controls the tuner and DVB demodulator hardware. -It can be accessed through \texttt{/dev/ost/frontend}. -If you are using \texttt{devfs} you can use \texttt{/dev/dvb/card0/frontend}. -The frontend device will only be made visible through \texttt{devfs} -if the corresponding card actually has a frontend. Cards which support -the DVB API but, e.g., only can play back recordings, will not offer the -frontend device. +It can be accessed through \texttt{/dev/dvb/adapter0/frontend0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/frontend.h} in your application. + +DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) +and DVB-T (terrestrial). Transmission via the internet (DVB-IP) is +not handled by this API. +For DVB-S the frontend device also supports satellite equipment control +(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification +is available from Eutelsat \texttt{http://www.eutelsat.org/}. + +Note that the DVB API may also be used for MPEG decoder-only PCI cards, +in which case there exists no frontend device. \devsubsec{Frontend Data Types} -\devsubsubsec{frontend status} -\label{frontendstatus} +\devsubsubsec{frontend type} +\label{frontendtype} + +For historic reasons frontend types are named after the +type of modulation used in transmission. -Several functions of the frontend device use the feStatus data -type defined by \begin{verbatim} -typedef uint32_t feStatus; +typedef enum fe_type { + FE_QPSK, /* DVB-S */ + FE_QAM, /* DVB-C */ + FE_OFDM /* DVB-T */ +} fe_type_t; \end{verbatim} -to indicate the current state and/or state changes of -the frontend hardware. -\noindent -It can take on the values +\devsubsubsec{frontend capabilities} +\label{frontendcaps} + +Capabilities describe what a frontend can do. Some capabilities +can only be supported for a specific frontend type. + +\begin{verbatim} +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_MUTE_TS = 0x80000000, + FE_CAN_CLEAN_SETUP = 0x40000000 +} fe_caps_t; +\end{verbatim} + +\devsubsubsec{frontend information} +\label{frontendinfo} + +Information about the frontend ca be queried with +FE\_GET\_INFO (\ref{fegetinfo}). + +\begin{verbatim} +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; +}; +\end{verbatim} + +\devsubsubsec{diseqc master command} +\label{diseqcmastercmd} + +A message sent from the frontend to DiSEqC capable equipment. + +\begin{verbatim} +struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /* { framing, address, command, data[3] } */ + uint8_t msg_len; /* valid values are 3...6 */ +}; +\end{verbatim} + +\devsubsubsec{diseqc slave reply} +\label{diseqcslavereply} + +A reply to the frontend from DiSEqC 2.0 capable equipment. + +\begin{verbatim} +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 */ +\end{verbatim} + +\devsubsubsec{SEC voltage} +\label{secvoltage} + +The voltage is usually used with non-DiSEqC capable LNBs to +switch the polarzation (horizontal/vertical). + +\begin{verbatim} +typedef enum fe_sec_voltage { + SEC_VOLTAGE_13, + SEC_VOLTAGE_18 +} fe_sec_voltage_t; +\end{verbatim} + +\devsubsubsec{SEC continuous tone} +\label{sectone} + +The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to +switch the high/low band of a dual-band LNB. + +\begin{verbatim} +typedef enum fe_sec_tone_mode { + SEC_TONE_ON, + SEC_TONE_OFF +} fe_sec_tone_mode_t; +\end{verbatim} + +\devsubsubsec{SEC tone burst} +\label{sectoneburst} + +The 22KHz tone burst is usually used with non-DiSEqC capable +switches to select between two connected LNBs/satellites. + \begin{verbatim} -#define FE_HAS_POWER 1 -#define FE_HAS_SIGNAL 2 -#define FE_SPECTRUM_INV 4 -#define FE_HAS_LOCK 8 -#define FE_HAS_CARRIER 16 -#define FE_HAS_VITERBI 32 -#define FE_HAS_SYNC 64 -#define TUNER_HAS_LOCK 128 +typedef enum fe_sec_mini_cmd { + SEC_MINI_A, + SEC_MINI_B +} fe_sec_mini_cmd_t; \end{verbatim} -which can be ORed together and have the following meaning: -\medskip -\begin{tabular}{lp{11cm}} -FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ -FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ -FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ -FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ -FE\_HAS\_CARRIER & carrier detected in signal\\ -FE\_HAS\_VITERBI & lock at viterbi decoder stage\\ -FE\_HAS\_SYNC & TS sync bytes detected \\ -TUNER\_HAS\_LOCK & the tuner has a frequency lock -\end{tabular} +\devsubsubsec{frontend status} +\label{frontendstatus} + +Several functions of the frontend device use the fe\_status data +type defined by +\begin{verbatim} +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 */ +\end{verbatim} +to indicate the current state and/or state changes of +the frontend hardware. \devsubsubsec{frontend parameters} @@ -57,45 +181,44 @@ depend on the kind of hardware you are using. All kinds of parameters are combined as a union in the FrontendParameters structure: \begin{verbatim} -typedef struct { - __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ - /* intermediate frequency in kHz for QPSK */ - fe_spectral_inversion_t Inversion; /* spectral inversion */ +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 { - QPSKParameters qpsk; - QAMParameters qam; - OFDMParameters ofdm; + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; } u; -} FrontendParameters; +}; \end{verbatim} For satellite QPSK frontends you have to use QPSKParameters defined by \begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - fe_code_rate_t FEC_inner; /* forward error correction (see above) */ -} QPSKParameters; +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) */ +}; \end{verbatim} for cable QAM frontend you use the QAMParameters structure \begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - fe_code_rate_t FEC_outer; /* forward error correction (see above) */ - fe_code_rate_t FEC_inner; /* forward error correction (see above) */ - fe_modulation_t QAM; /* modulation type (see above) */ -} QAMParameters; +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) */ +}; \end{verbatim} DVB-T frontends are supported by the OFDMParamters structure \begin{verbatim} -typedef struct { - fe_bandwidth_t bandWidth; - fe_code_rate_t HP_fe_code_rate_t; /* high priority stream code rate */ - fe_code_rate_t LP_fe_code_rate_t; /* low priority stream code rate */ - fe_modulation_t Constellation; /* modulation type (see above) */ - fe_transmit_mode_t TransmissionMode; - fe_guard_interval_t guardInterval; - fe_hierarchy_t fe_hierarchy_tInformation; -} OFDMParameters; +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; +}; \end{verbatim} In the case of QPSK frontends the Frequency field specifies the intermediate @@ -107,7 +230,7 @@ and is given in Hz. The Inversion field can take one of these values: \begin{verbatim} -typedef enum { +typedef enum fe_spectral_inversion { INVERSION_OFF, INVERSION_ON, INVERSION_AUTO @@ -120,15 +243,18 @@ try to figure out the correct setting by itself. \noindent The possible values for the FEC\_inner field are \begin{verbatim} -enum { - FEC_AUTO, +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_NONE -}; + FEC_8_9, + FEC_AUTO +} fe_code_rate_t; \end{verbatim} which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., no error correction or auto detection. @@ -137,47 +263,52 @@ 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: \begin{verbatim} -typedef enum -{ QPSK, +typedef enum fe_modulation { + QPSK, QAM_16, QAM_32, QAM_64, QAM_128, - QAM_256 -} QAM_TYPE; + QAM_256, + QAM_AUTO +} fe_modulation_t; \end{verbatim} Finally, there are several more parameters for OFDM: \begin{verbatim} -typedef enum { +typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K + TRANSMISSION_MODE_8K, + TRANSMISSION_MODE_AUTO } fe_transmit_mode_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, BANDWIDTH_7_MHZ, - BANDWIDTH_6_MHZ + BANDWIDTH_6_MHZ, + BANDWIDTH_AUTO } fe_bandwidth_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, GUARD_INTERVAL_1_16, GUARD_INTERVAL_1_8, - GUARD_INTERVAL_1_4 + GUARD_INTERVAL_1_4, + GUARD_INTERVAL_AUTO } fe_guard_interval_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_hierarchy { HIERARCHY_NONE, HIERARCHY_1, HIERARCHY_2, - HIERARCHY_4 + HIERARCHY_4, + HIERARCHY_AUTO } fe_hierarchy_t; \end{verbatim} @@ -186,78 +317,12 @@ typedef enum { \label{frontendevents} \begin{verbatim} -enum { - FE_UNEXPECTED_EV, - FE_COMPLETION_EV, - FE_FAILURE_EV +struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; }; \end{verbatim} -\begin{verbatim} -typedef struct { - EventType type; /* type of event, FE_UNEXPECTED_EV, ... */ - long timestamp; /* time in seconds since 1970-01-01 */ - - union { - struct { - fe_status_t previousStatus; /* status before event */ - fe_status_t currentStatus; /* status during event */ - } unexpectedEvent; - FrontendParameters completionEvent; /* parameters for which the - tuning succeeded */ - fe_status_t failureEvent; /* status at failure (e.g. no lock) */ - } u; -} FrontendEvent; -\end{verbatim} - -\begin{verbatim} -struct qpskRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qamRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qpskFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -struct qamFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - FE_POWER_ON, - FE_POWER_STANDBY, - FE_POWER_SUSPEND, - FE_POWER_OFF -} powerState_t; -\end{verbatim} - - \clearpage @@ -265,9 +330,9 @@ typedef enum { \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named frontend device (e.g. /dev/ost/qpskfe - for a satellite frontend or /dev/ost/qamfe for a cable frontend) - for subsequent use. + 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 @@ -303,119 +368,21 @@ typedef enum { int close(int fd);}{ 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. + powered down automatically. }{ int fd & File descriptor returned by a previous call to open().\\ }{ EBADF & fd is not a valid open file descriptor.\\ } -\ifunction{OST\_SELFTEST}{ - int ioctl(int fd, int request = OST\_SELFTEST);}{ - This ioctl call initiates an automatic self-test of the front-end hardware. - This call requires read/write access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SELFTEST for this command.\\ - }{ - -1& Self test failure.\\ -} - -\ifunction{OST\_SET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_SET\_POWER\_STATE, uint32\_t state);}{ - 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 supports 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: \\ - \begin{center} - \begin{tabular}[h]{cll} - number of low-power & requested state & resulting state\\ - states supported &&\\ - \\ - 1 & standby & suspend \\ - 1 & suspend & suspend \\ - 0 & standby & on \\ - 0 & suspend & on - \end{tabular} - \end{center}\\ - 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.) - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SET\_POWER\_STATE for this command.\\ - uint32\_t state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - 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\\ - \end{tabular} - }{ - 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. -} - -\ifunction{FE\_GET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_GET\_POWER\_STATE, uint32\_t *state);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_GET\_POWER\_STATE for this command.\\ - uint32\_t *state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - 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\\ - \end{tabular} - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINVAL& Illegal state, or not available on this device.\\ - EFAULT& state points to invalid address.\\ - ENOSYS& Function not available for this device. -} - \ifunction{FE\_READ\_STATUS}{ - int ioctl(int fd, int request = FE\_READ\_STATUS, feStatus *status);}{ + int ioctl(int fd, int request = FE\_READ\_STATUS, fe\_status\_t *status);}{ This ioctl call returns status information about the front-end. This call only requires read-only access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_STATUS for this command.\\ - struct feStatus *status&Points to the location where the front-end + struct fe\_status\_t *status & Points to the location where the front-end status word is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ @@ -430,10 +397,7 @@ typedef enum { }{ 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, as a multiple of $10^{-9}$, - is stored into *ber.\\ - & Example: a value of 2500 corresponds to a bit error - rate of $2.5\cdot 10^{-6}$, or 1 error in 400000 bits. + uint32\_t *ber & The bit error rate is stored into *ber.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& ber points to invalid address.\\ @@ -443,17 +407,14 @@ typedef enum { } \ifunction{FE\_READ\_SNR}{ - int ioctl(int fd, int request = FE\_READ\_SNR, int32\_t *snr);}{ + int ioctl(int fd, int request = FE\_READ\_SNR, int16\_t *snr);}{ 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. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_SNR for this command.\\ - int32\_t *snr& 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. + int16\_t *snr& The signal-to-noise ratio is stored into *snr.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& snr points to invalid address.\\ @@ -463,7 +424,7 @@ typedef enum { } \ifunction{FE\_READ\_SIGNAL\_STRENGTH}{ - int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int32\_t *strength); + int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int16\_t *strength); }{ 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 @@ -471,11 +432,7 @@ is sufficient. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_SIGNAL\_STRENGTH for this command.\\ -int32\_t *strength & 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. +int16\_t *strength & The signal strength value is stored into *strength.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& status points to invalid address.\\ @@ -505,59 +462,8 @@ by the driver so far. } -\ifunction{FE\_GET\_NEXT\_FREQUENCY}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_FREQUENCY, uint32\_t *freq);}{ - 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 efficient 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.\\ - Note that scanning may still be excruciatingly slow on some hardware, for - other reasons than a non-optimal scanning step size. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_FREQUENCY for this command.\\ - uint32\_t *freq& Input: a given frequency \\ - & Output: the frequency corresponding to - the next higher frequency setting.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& freq points to invalid address.\\ - EINVAL& Maximum supported frequency reached.\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_GET\_NEXT\_SYMBOL\_RATE}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_SYMBOL\_RATE, uint32\_t *symbolRate); - }{ - 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 efficient 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_SYMBOL\_RATE for this command.\\ - uint32\_t *symbolRate& Input: a given symbol rate \\ - & Output: the symbol rate corresponding to - the next higher symbol rate.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& symbolRate points to invalid address.\\ - EINVAL& Maximum supported symbol rate reached.\\ - ENOSYS& Function not available for this device. -} - \ifunction{FE\_SET\_FRONTEND}{ - int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct FrontendParameters *p);}{ + int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct dvb\_frontend\_parameters *p);}{ 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. @@ -571,7 +477,21 @@ by the driver so far. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_SET\_FRONTEND for this command.\\ - struct FrontendParameters *p& Points to parameters for tuning operation.\\ + struct dvb\_frontend\_parameters *p& Points to parameters for tuning operation.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& p points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ +} + +\ifunction{FE\_GET\_FRONTEND}{ + int ioctl(int fd, int request = FE\_GET\_FRONTEND, struct dvb\_frontend\_parameters *p);}{ + This ioctl call queries the currently effective frontend parameters. + For this command, read-only access to the device is sufficient. + }{ + 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.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& p points to invalid address.\\ @@ -579,8 +499,8 @@ by the driver so far. } \ifunction{FE\_GET\_EVENT}{ - int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct qpskEvent *ev);}{ - This ioctl call returns an event of type qpskEvent if available. If an event + int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct dvb\_frontend\_event *ev);}{ + 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 @@ -593,14 +513,15 @@ by the driver so far. 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 QPSK\_GET\_EVENT calls will return events from the queue as + 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. }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals QPSK\_GET\_EVENT for this command.\\ - struct qpskEvent *ev&Points to the location where the event, if any, is to be stored. + 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. }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& ev points to invalid address.\\ @@ -611,19 +532,133 @@ by the driver so far. } \ifunction{FE\_GET\_INFO}{ - int ioctl(int fd, int request = FE\_GET\_INFO, struct FrontendInfo *info);}{ +\label{fegetinfo} + int ioctl(int fd, int request = FE\_GET\_INFO, struct dvb\_frontend\_info *info);}{ This ioctl call returns information about the front-end. This call only requires read-only access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_GET\_INFO for this command.\\ - struct qpskFrontendInfo *info & Points to the location where the front-end + struct dvb\_frontend\_info *info & Points to the location where the front-end information is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& info points to invalid address.\\ } +\ifunction{FE\_DISEC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = FE\_DISEC\_RESET\_OVERLOAD);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_RESET\_OVERLOAD for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{FE\_DISEC\_SEND\_MASTER\_CMD}{ +int ioctl(int fd, int request = FE\_DISEC\_SEND\_MASTER\_CMD, struct dvb\_diseqc\_master\_cmd *cmd);}{ + This ioctl call is used to send a a DiSEqC command.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_SEND\_MASTER\_CMD for this command.\\ + struct dvb\_diseqc\_master\_cmd *cmd & Pointer to the command to be transmitted.\\ + }{ + 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.\\ +} + +\ifunction{FE\_DISEC\_RECV\_SLAVE\_REPLY}{ +int ioctl(int fd, int request = FE\_DISEC\_RECV\_SLAVE\_REPLY, struct dvb\_diseqc\_slave\_reply *reply);}{ +This ioctl call is used to receive reply to a DiSEqC 2.0 command.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_RECV\_SLAVE\_REPLY for this command.\\ + struct dvb\_diseqc\_slave\_reply *reply & Pointer to the command to be received.\\ + }{ + 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.\\ +} + +\ifunction{FE\_DISEC\_SEND\_BURST}{ +int ioctl(int fd, int request = FE\_DISEC\_SEND\_BURST, fe\_sec\_mini\_cmd\_t burst);}{ +This ioctl call is used to send a 22KHz tone burst.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_SEND\_BURST for this command.\\ + fe\_sec\_mini\_cmd\_t burst & burst A or B.\\ + }{ + 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.\\ +} + + +\ifunction{FE\_SET\_TONE}{ +int ioctl(int fd, int request = FE\_SET\_TONE, fe\_sec\_tone\_mode\_t tone);}{ +This call is used to set the generation of the continuous 22kHz tone. +This call requires read/write permissions. +}{ +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).\\ +}{ +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.\\ +} + + +\ifunction{FE\_SET\_VOLTAGE}{ +int ioctl(int fd, int request = FE\_SET\_VOLTAGE, fe\_sec\_voltage\_t voltage);}{ +This call is used to set the bus voltage. +This call requires read/write permissions. +}{ +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.\\ +}{ +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.\\ +} + +\ifunction{FE\_ENABLE\_HIGH\_LNB\_VOLTAGE}{ +int ioctl(int fd, int request = FE\_ENABLE\_HIGH\_LNB\_VOLTAGE, int high);}{ +If high != 0 enables slightly higher voltages instead of 13/18V +(to compensate for long cables). +This call requires read/write permissions. +}{ +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.\\ +}{ +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.\\ +} + + %%% Local Variables: %%% mode: latex %%% TeX-master: "dvbapi" |