diff options
Diffstat (limited to 'dvb-spec/dvbapi/sec.tex')
| -rw-r--r-- | dvb-spec/dvbapi/sec.tex | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex new file mode 100644 index 000000000..88342c3a6 --- /dev/null +++ b/dvb-spec/dvbapi/sec.tex @@ -0,0 +1,282 @@ +\devsec{DVB SEC API} + +The DVB SEC device controls the Satellite Equipment Control of +the DVB hardware, i.e. DiSEqC and V-SEC. +It is accessed through \texttt{/dev/ost/sec}. + +\devsubsec{SEC Data Types} + +\devsubsubsec{secDiseqcCmd} +\label{secdiseqccmd} + +\begin{verbatim} +struct secDiseqcCmd { + uint8_t addr; + uint8_t cmd; + uint8_t numParams; + uint8_t params[SEC_MAX_DISEQC_PARAMS]; +}; +\end{verbatim} + + +\devsubsubsec{secVoltage} +\label{secvoltage} + +\begin{verbatim} +typedef uint32_t secVoltage; +\end{verbatim} +\begin{verbatim} +enum { + SEC_VOLTAGE_OFF, + SEC_VOLTAGE_LT, + SEC_VOLTAGE_13, + SEC_VOLTAGE_13_5, + SEC_VOLTAGE_18, + SEC_VOLTAGE_18_5 +}; +\end{verbatim} + + +\devsubsubsec{secToneMode} +\label{sectonemode} + +\begin{verbatim} +typedef uint32_t secToneMode; +\end{verbatim} +\begin{verbatim} +typedef enum { + SEC_TONE_ON, + SEC_TONE_OFF +} secToneMode_t; +\end{verbatim} + + +\devsubsubsec{secMiniCmd} +\label{secminicmd} + +\begin{verbatim} +typedef uint32_t secMiniCmd; +\end{verbatim} +\begin{verbatim} +typedef enum { + SEC_MINI_NONE, + SEC_MINI_A, + SEC_MINI_B +} secMiniCmd_t; +\end{verbatim} +\begin{verbatim} +struct secStatus { + int32_t busMode; + secVoltage selVolt; + secToneMode contTone; +}; +\end{verbatim} + +\begin{verbatim} +enum { + SEC_BUS_IDLE, + SEC_BUS_BUSY, + SEC_BUS_OFF, + SEC_BUS_OVERLOAD +}; +\end{verbatim} + + +\devsubsubsec{secCommand} +\label{seccommand} + +\begin{verbatim} +struct secCommand { + int32_t type; + union { + struct secDiseqcCmd diseqc; + uint8_t vsec; + uint32_t pause; + } u; +}; +\end{verbatim} + + +\devsubsubsec{secCmdSequence} +\label{seccmdsequence} + +\begin{verbatim} +struct secCmdSequence { + secVoltage voltage; + secMiniCmd miniCommand; + secToneMode continuousTone; + + uint32_t numCommands; + struct secCommand* commands; +}; +\end{verbatim} + +\begin{verbatim} +enum { + SEC_CMDTYPE_DISEQC, + SEC_CMDTYPE_VSEC, + SEC_CMDTYPE_PAUSE +}; +\end{verbatim} + +\begin{verbatim} +typedef enum { + SEC_DISEQC_SENT, + SEC_VSEC_SENT, + SEC_PAUSE_COMPLETE, + SEC_CALLBACK_ERROR +} secCallback_t; +\end{verbatim} + +\clearpage + +\devsubsec{SEC Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named SEC device for subsequent use. + If the device is opened in read-only mode, only status and statistics + monitoring is allowed. If the device is opened in read/write mode, all + types of operations can be performed. + Any number of applications can have simultaneous access to the device. + }{ + const char *deviceName & Name of specific SEC device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & The optional flag O\_NONBLOCK is not supported. If O\_NONBLOCK is set, + open() and most other subsequent calls to the device will return -1 and + set errno to EWOULDBLOCK. + The communication with the peripheral devices is sequential by nature, + so it is probably preferable to use the device in synchronous mode. + This is the motivation for not going through the extra effort of + implementing asynchronous operation of the device. + }{ + ENODEV & Device driver not loaded/available.\\ + EFAULT & deviceName does not refer to a valid memory area.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened SEC device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\ifunction{SEC\_GET\_STATUS}{ + int ioctl(int fd, int request = SEC\_GET\_STATUS, struct secStatus* status);}{ + This call gets the status of the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_GET\_STATUS for this command.\\ + struct secStatus* status & The status of the device.\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EFAULT & status is an invalid pointer.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ + EPERM & File not opened with read permissions.\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{SEC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = SEC\_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 SEC\_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{SEC\_SEND\_SEQUENCE}{ +int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); +}{ +This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC +commands. The first version of the SEC device does not support V-SEC +signaling and it aborts the operation with an error code if a V-SEC +command is detected in the input data.\\ +\begin{itemize} +\item[$\bullet$] The call will fail with errno set to EBUSOVERLOAD if the bus is +overloaded. If the bus is overloaded, SEC\_RESET\_OVERLOAD can be +called and the operation can be retried. +\item[$\bullet$] If seq.numCommands equals 0 and seq.miniCommand equals SEC\_MINI\_NONE, +the bus voltage will be switched and the continuous 22kHz tone +generation enabled/disabled immediately. +\end{itemize}\\ +This operation is atomic. If several processes calls this ioctl +simultaneously, the operations will be serialized so a complete sequence +is sent at a time. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_SEND\_SEQUENCE for this command.\\ + struct secCmdSequence *seq & Pointer to the command sequence 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.\\ + EBUSMODE & The device is not prepared for transmission + (e.g. it might be manually powered off).\\ + EBUSOVERLOAD & Bus overload has occurred.\\ +} + + +\ifunction{SEC\_SET\_TONE}{ +int ioctl(int fd, int request = SEC\_SET\_TONE, secToneMode tone); +}{ +This call is used to set the generation of the continuous 22kHz tone. +The possibility to just change the tone mode is already provided by +ioctl SEC\_SEND\_SEQUENCE, but SEC\_SET\_TONE is an easier to use interface. +To keep the transmission of a command sequence as +an atomic operation, SEC\_SET\_TONE will block if a transmission is in +progress. This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals SEC\_SET\_TONE for this command.\\ +secToneMode 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{SEC\_SET\_VOLTAGE}{ +int ioctl(int fd, int request = SEC\_SET\_VOLTAGE, secVoltage voltage); +}{ +This call is used to set the bus voltage. The possibility to just change +the bus voltage is already provided by ioctl SEC\_SEND\_SEQUENCE, but +SEC\_SET\_VOLTAGE is an easier to use interface. +To keep the transmission of a command sequence as +an atomic operation, SEC\_SET\_VOLTAGE will block if a transmission is in +progress. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals SEC\_SET\_VOLTAGE for this command.\\ +secVoltage 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.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: |