diff options
| -rw-r--r-- | dvb-spec/API/linux_dvb_api.xml | 3592 |
1 files changed, 3592 insertions, 0 deletions
diff --git a/dvb-spec/API/linux_dvb_api.xml b/dvb-spec/API/linux_dvb_api.xml new file mode 100644 index 000000000..b1040ffe5 --- /dev/null +++ b/dvb-spec/API/linux_dvb_api.xml @@ -0,0 +1,3592 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE article PUBLIC "-//Norman Walsh//DTD Simplified DocBook XML V4.1.2.2//EN" + "http://doc.convergence.de/sdocbook.dtd"> + +<article> + +<title>Linux DVB API</title> + +<subtitle>Documentation</subtitle> + +<artheader> + +<authorgroup> +<author> + <honorific>Dr.</honorific> + <firstname>Ralph</firstname> + <surname>Metzler</surname> + <email>rjkm@convergence.de</email> +</author> +<author> + <honorific></honorific> + <firstname>Andreas</firstname> + <surname>Bogk</surname> + <email>bogk@convergence.de</email> +</author> +</authorgroup> +<pubdate>feb. 7, 2000</pubdate> +<copyright><year>2000</year><holder><userinput>convergence</userinput> +integrated media GmbH</holder></copyright> + +<address>Rosenthalerstr. 51, 10178 Berlin</address> +<keywordset> + <keyword>linux</keyword> + <keyword>dvb</keyword> + <keyword>api</keyword> + <keyword>documentation</keyword> +</keywordset> + +<abstract> +<title>About the Linux DVB API</title> + +<para> + +The Linux DVB API is based on a proposal by Nokia. As a commitment to the +development of terminals based on open standards, Nokia and convergence published +it on <ulink url="http://linuxtv.org"><citetitle>linuxtv.org</citetitle></ulink>. + +</para> + +<para> <ulink +url="http://www.convergence.de"><citetitle>Convergence</citetitle></ulink> is +the maintainer of the Linux DVB API. Together with the LinuxTV community +(i.e. you, the reader of this document), the Linux DVB API will be constantly +reviewed and improved. With the Linux driver for the Siemens/ Hauppauge DVB PCI +card convergence provides a first implementation of the Linux DVB API. + +</para> +</abstract> + +</artheader> + +<part> + +<chapter> + <title>Introduction</title> + + <para> + + Part of the DVB API builds upon the <ulink + url="http://roadrunner.swansea.uk.linux.org/v4l.shtml"><citetitle>Video4Linux</citetitle></ulink> + (V4L) API. The Siemens DVB card uses the SAA7146 as PCI bridge. A + <ulink url="http://www.mihu.de/"><citetitle>generic SAA7146 Linux + driver</citetitle></ulink> for this chip implements the basic V4L + interface. + </para> + + <para> An older version of the API included the DVB specific calls into + the V4L interface. This turned out to be very cumbersome to + program. Since we also hoped to arrive at a common standard for all + Linux platforms, especially those in embedded consumer devices, we were + happy to find <ulink + url="http://www.nokia.com/multimedia"><citetitle>Nokia</citetitle></ulink> + as a partner in this effort. They will be using the same API in their + upcoming + <ulink url="http://www.nokia.com/multimedia/mediaterminal.html"> + <citetitle>Media Terminal</citetitle></ulink>. + </para> + + <para> In the new version of the API only display and grabbing of the + already decompressed images is handled through the V4L device. All + other DVB features like tuning, filtering and playback/recording of the + compressed data stream are accessed through separate devices. + </para> + + <para> A first implementations of the Linux DVB API for the Siemens/ + Hauppauge DVB PCI card is available in the <ulink + url="http://linuxtv.org/cvs/"><citetitle>LinuxTV Public + CVS</citetitle></ulink>. + </para> + +</chapter> + +<chapter> + <title>DVB Devices</title> + + <para> + There are currently 6 DVB devices: Video, Audio, Frontend, SEC, + Demux and CA. The APIs of those devices are described in the + sections below. + </para> + +<sect1> + <title>DVB Video API</title> + + <para> + The DVB video device controls the MPEG2 video decoder of the DVB hardware. + It can be accessed through /dev/ost/audio. + </para> + + <para> The include file <ulink + url="video.h"><citetitle>video.h</citetitle></ulink> describes the data + types and lists all i/o calls. A complete explanation of all calls can + be found below: + </para> + +<sect2> + <title>Video API IO control calls</title> + +<para> +<blockquote><literallayout> + +int open(const char *deviceName, int flags); + + FUNCTION + + This system call opens a named video device (e.g. /dev/ost/video) for subsequent + use. + When an open() call has succeeded, the device will be ready for use. + The significance of blocking or non-blocking mode is described in the documentation + for functions where there is a difference. It does not affect the semantics of the + open() call itself. A 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. + Only one user can open the Video Device in O_RDWR mode. All other attemts to + open the device in this mode will fail, and an errorcode will be returned. + If the Video Device is opened in O_RDONLY mode, the only ioctl call that can be used + is VIDEO_GET_STATUS. All other call will return an error code. + + + PARAMETERS + + const char *deviceName Name of specific video device. In the current + implementation, /dev/ost/video is the only + one available. + 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) + RETURNS + + ENODEV Device driver not loaded/available. + + EINTERNAL Internal error, possibly in the communication + with the DVB subsystem. + + EBUSY Device or resource busy. + + EINVAL Invalid argument. + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int close(int fd); + + DESCRIPTION + + This system call closes a previously opened video device + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + RETURNS + + EBADF fd is not a valid open file descriptor + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> +size_t write(int fd, const void *buf, size_t count); + + DESCRIPTION + + This system call is only provided if VIDEO_SOURCE_MEMORY is selected in the + ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in PES format. + If O_NONBLOCK is not specified the function will block until buffer space + is available. The amount of data to be transferred is implied by count. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + void *buf Pointer to the buffer containing the PES data. + + size_t count Size of buf. + + RETURNS + + EPERM Mode VIDEO_SOURCE_MEMORY not selected. + + ENOMEM Attempted to write more data than the internal buffer can hold. + + EBADF fd is not a valid open file descriptor + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_STOP, boolean mode); + + FUNCTION + + This ioctl call asks the Video Device to stop playing the current stream. + Depending on the input parameter, the screen can be blanked out or + displaying the last decoded frame. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_STOP for this command. + + Boolean mode Indicates how the screen shall be handled. + + TRUE: Blank screen when stop. + FALSE: Show last decoded frame. + + RETURNS + + EBADF fd is not a valid open file descriptor + + EINTERNAL Internal error, possibly in the communication with + the DVB subsystem. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_PLAY); + + FUNCTION + + This ioctl call asks the Video Device to start playing a video stream + from the selected source. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_PLAY for this command. + + + RETURNS + + EBADF fd is not a valid open file descriptor + + EINTERNAL Internal error, possibly in the communication with + the DVB subsystem. + + + +</literallayout></blockquote> +</para> + + +<para> +<blockquote><literallayout> +int ioctl(int fd, int request = VIDEO_FREEZE); + + FUNCTION + + This ioctl call suspends the live video stream being played. + Decoding and playing are frozen. It is then possible to restart + the decoding and playing process of the video stream using + VIDEO_CONTINUE command. If VIDEO_SOURCE_MEMORY is selected in the + ioctl call VIDEO_SELECT_SOURCE, the DVB-subsystem will not decode + any more data until the ioctl call VIDEO_FREEZE or VIDEO_PLAY is + performed. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_FREEZE for this command. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error, possibly in the communication with + the DVB subsystem. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_CONTINUE); + + FUNCTION + + This ioctl call restarts decoding and playing processes of the video + stream which was played before a call to VIDEO_FREEZE was made. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_CONTINUE for this command. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error, possibly in the communication with + the DVB subsystem. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_SELECT_SOURCE, videoStreamSource_t source); + + FUNCTION + + This ioctl call informs the video device which source shall be used + for the input data. The possible sources are demux or memory. If + internal is selected, the data is feed to the Video Device through + the write command. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_SELECT_SOURCE for this command. + + videoStreamSource_t source + Indicates which source shall be used for the Video stream. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error, possibly in the communication with + the DVB subsystem. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_SET_BLANK, boolean mode); + + DESCRIPTION + + This ioctl call asks the Video Device to blank out the picture. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_SET_BLANK for this command. + + boolean mode TRUE: Blank screen when stop. + FALSE: Show last decoded frame. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EINVAL Illegal input parameter. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_GET_STATUS, struct videoStatus *status); + + DESCRIPTION + + This ioctl call asks the Video Device to return the current status of the device. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_GET_STATUS for this command. + + struct videoStatus Returns the current status of the Video Device. + *status + + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EFAULT status points to invalid address + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_GET_EVENT, struct videoEvent *ev); + + DESCRIPTION + + This ioctl call returns an event of type videoEvent 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. + Read-only permissions are sufficient for this ioctl call. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_GET_EVENT for this command. + + struct videoEvent *ev 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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_SET_DISPLAY_FORMAT, videoDisplayFormat_t format); + + DESCRIPTION + + This ioctl call asks the Video Device to select the video format to be applied + by the MPEG chip on the video. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_SET_DISPLAY_FORMAT for this command. + + videoDisplayFormat_t Selects the video format to be used. + format + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EINVAL Illegal parameter format. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_STILLPICTURE, struct videoDisplayStillPicture *sp); + + DESCRIPTION + + This ioctl call asks the Video Device to display a still picture (I-frame). + The input data shall contain an I-frame. If the pointer is NULL, then the + current displayed still picture is blanked. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_STILLPICTURE for this command. + + struct videoDisplayStillPicture *sp Pointer to a location where an I-frame + and size is stored. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EFAULT sp points to an invalid iframe. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_FAST_FORWARD, int nFrames); + + DESCRIPTION + + This ioctl call asks the Video Device to skip decoding of N number of I-frames. + This call can only be used if VIDEO_SOURCE_INTRENAL is selected. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_FAST_FORWARD for this command. + + int nFrames The number of frames to skip. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EPERM Mode VIDEO_SOURCE_MEMORY not selected. + + EINVAL Illegal parameter format. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = VIDEO_SLOWMOTION, int nFrames); + + DESCRIPTION + + This ioctl call asks the Video Device to repeat decoding frames N number of times. + This call can only be used if VIDEO_SOURCE_MEMORY is selected. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals VIDEO_SLOWMOTION for this command. + + int nFrames The number of frames to skip. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EPERM Mode VIDEO_SOURCE_MEMORY not selected. + + EINVAL Illegal parameter format. + +</literallayout></blockquote> +</para> + +</sect2> + +</sect1> + +<sect1> + <title>DVB Audio API</title> + + <para> The DVB audio device controls the MPEG2 audio decoder of the + DVB hardware. It can be accessed through /dev/ost/audio. + </para> + + <para> The function calls defined in the include file <ulink + url="audio.h"><citetitle>audio.h</citetitle></ulink> are described in + detail below: + </para> + +<sect2> + <title>Audio API IO control calls</title> + +<para> +<blockquote><literallayout> + +int open(const char *deviceName, int flags); + + DESCRIPTION + + This system call opens a named audio device (e.g. /dev/ost/audio) for subsequent + use. When an open() call has succeeded, the device will be ready for use. + The significance of blocking or non-blocking mode is described in the + documentation for functions where there is a difference. It does not affect + the semantics of the open() call itself. A 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. + Only one user can open the Audio Device in O_RDWR mode. All other attempts to + open the device in this mode will fail, and an errorcode will be returned. + If the Audio Device is opened in O_RDONLY mode, the only ioctl call that can + be used is AUDIO_GET_STATUS. All other call will return with an error code. + + + PARAMETERS + + const char *deviceName Name of specific audio 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) + + RETURNS + + ENODEV Device driver not loaded/available. + + EINTERNAL Internal error + + EBUSY Device or resource busy. + + EINVAL Invalid argument. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int close(int fd); + + DESCRIPTION + + This system call closes a previously opened audio device + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + RETURNS + + EBADF fd is not a valid open file descriptor + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +size_t write(int fd, const void *buf, size_t count); + + DESCRIPTION + + This system call can only be used if AUDIO_SOURCE_MEMORY is selected in the + ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in PES format. + If O_NONBLOCK is not specified the function will block until buffer space is + available. The amount of data to be transferred is implied by count. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + void *buf Pointer to the buffer containing the PES data. + + size_t count Size of buf. + + RETURNS + + EPERM Mode VIDEO_SOURCE_INTERNAL not selected. + + ENOMEM Attempted to write more data than the internal + buffer can hold. + + EBADF fd is not a valid open file descriptor + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_STOP); + + DESCRIPTION + + This ioctl call asks the Audio Device to stop playing the current stream. + + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_STOP for this command. + + RETURNS + + EBADF fd is not a valid open file descriptor + + EINTERNAL Internal error + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_PLAY); + + DESCRIPTION + + This ioctl call asks the Audio Device to start playing an audio stream from the + selected source. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_PLAY for this command. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_PAUSE); + + DESCRIPTION + + This ioctl call suspends the audio stream being played. Decoding and playing are + paused. It is then possible to restart again decoding and playing process of the + audio stream using AUDIO_CONTINUE command. + If AUDIO_SOURCE_MEMORY is selected in the ioctl call AUDIO_SELECT_SOURCE, the + DVB-subsystem will not decode (consume) any more data until the ioctl call + AUDIO_CONTINUE or AUDIO_PLAY is performed. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_PAUSE for this command. + + RETURNS + + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_CONTINUE); + + DESCRIPTION + + This ioctl call restarts decoding and playing processes of the audio stream, + which was played before, a call to AUDIO_PAUSE was made. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_CONTINUE for this command. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error, possibly in the communication + with the DVB subsystem. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audioStreamSource_t source); + + DESCRIPTION + + This ioctl call informs the audio device which source shall be used for the + input data. The possible sources are demux or memory. If AUDIO_SOURCE_MEMORY + is selected, the data is fed to the Audio Device through the write command. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_SELECT_SOURCE for this command. + + audioStreamSource_t source Indicates the source that shall be used for the + Audio stream. + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state); + + DESCRIPTION + + This ioctl call asks the audio device to mute the stream that is currently being + played. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_SET_MUTE for this command. + + boolean state Indicates if audio device shall mute or not. + TRUE Audio Mute + FALSE Audio Unmute + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error, + + EINVAL Illegal input parameter. + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> +int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state); + + DESCRIPTION + + This ioctl call asks the Audio Device to turn ON or OFF A/V synchronisation. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_AV_SYNC for this command. + + boolean state Tells the DVB subsystem if A/V synchronisation shall be ON or OFF. + TRUE AV-sync ON + FALSE AV-sync OFF + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EINVAL Illegal input parameter. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode); + + DESCRIPTION + + This ioctl call asks the Audio Device to bypass the Audio decoder and forward + the stream without decoding. This mode shall be used if streams that can't be + handled by the DVB system shall be decoded. Dolby DigitalTM streams are + automatically forwarded by the DVB subsystem. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_SET_BYPASS_MODE for this command. + + boolean mode Enables or disables the decoding of the current + Audio stream in the DVB subsystem. + TRUE Bypass is disabled + FALSE Bypass is enabled + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EINVAL Illegal pointer mode. + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> +int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audioChannelSelect_t) + + DESCRIPTION + + This ioctl call asks the Audio Device to select the requested channel if possible. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_CHANNEL_SELECT for this command. + + audioChannelSelect_t ch Select the output format of the audio (Mono, stereo) + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EINVAL Illegal pointer ch. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audioStatus *status) + + DESCRIPTION + + This ioctl call asks the Audio Device to return the current state of the Audio + Device. + + PARAMETERS + + int fd File descriptor returned by a previous call to open(). + + int request Equals AUDIO_GET_STATUS for this command. + + struct audioStatus *status Returns the current state of Audio Device + + RETURNS + + EBADF fd is not a valid open file descriptor. + + EINTERNAL Internal error + + EFAULT status points to invalid address + + + +</literallayout></blockquote> +</para> + +</sect2> + +</sect1> + +<sect1> + <title>DVB Frontend API</title> + + <para> + The DVB frontend device controls the frontend of the DVB hardware, e.g. + tuning, symbol rate, error correction, ... + It is accessed through /dev/ost/qpskfe. + </para> + + <para> The function calls defined in the include file <ulink + url="frontend.h"><citetitle>frontend.h</citetitle></ulink> are described + in detail below: + </para> + +<sect2> + <title>Frontend API IO control calls</title> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +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. + + + +</literallayout></blockquote> +</para> + +</sect2> + +</sect1> + +<sect1> + <title>DVB SEC API</title> + + <para> + The DVB SEC device controls the Satellite Equipment Control of + the DVB hardware, i.e. DiSEqC and V-SEC. + It is accessed through /dev/ost/sec. + </para> + + <para> The function calls defined in the include file <ulink + url="sec.h"><citetitle>sec.h</citetitle></ulink> aredescribed in detail + below: + </para> + +<sect2> + <title>SEC API IO control calls</title> + +<para> +<blockquote><literallayout> + +int open(const char *deviceName, int flags); + + DESCRIPTION + + 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. + + PARAMETERS + + const char *deviceName I Name of the SEC device. + + int flags I Valid values are: + O_RDONLY read-only access + 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. + + RETURNS + + ENODEV Device not loaded/available + EFAULT deviceName does not refer to a valid memory area. + EINVAL Invalid argument + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int close(int fd); + + DESCRIPTION + + This system call closes a previously opened SEC device. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + RETURNS + + EBADF fd is not a valid file descriptor. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = SEC_GET_STATUS, struct secStatus* status); + + DESCRIPTION + + This call gets the status of the device. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals SEC_GET_STATUS for this command. + + struct secStatus* status O The status of the device. + + RETURNS + + 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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = SEC_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. + + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals SEC_RESET_OVERLOAD for this command. + + RETURNS + + EBADF fd is not a valid file descriptor. + + EPERM Permission denied (needs read/write access) + + EINTERNAL Internal error in the device driver + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = SEC_SEND_SEQUENCE, struct secCmdSequence *seq); + + DESCRIPTION + + 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 + signalling and it aborts the operation with an error code if a V-SEC + command is detected in the input data. + + ! 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. + + ! 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. + + This operation is atomic. If several processes calls this ioctl + simultaneously, the operations will be serialised so a complete sequence + is sent at a time. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals SEC_SEND_SEQUENCE for this command. + + struct secCmdSequence *seq I Pointer to the command sequence to be transmitted. + + RETURNS + + 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. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = SEC_SET_TONE, secToneMode tone); + + DESCRIPTION + + 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 (see section 4.4.5 ) as + an atomic operation, SEC_SET_TONE will block if a transmission is in + progress. This call requires read/write permissions. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals SEC_SET_TONE for this command. + + secToneMode tone I The requested tone generation mode (on/off). + + RETURNS + + 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 + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl(int fd, int request = SEC_SET_VOLTAGE, secVoltage voltage); + + DESCRIPTION + + 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 (see section 4.4.5 ) as + an atomic operation, SEC_SET_VOLTAGE will block if a transmission is in + progress. + This call requires read/write permissions. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals SEC_SET_VOLTAGE for this command. + + secVoltage voltage I The requested bus voltage. + + RETURNS + + 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 + + + +</literallayout></blockquote> +</para> + +</sect2> + +</sect1> + +<sect1> + <title>DVB Demux API</title> + + <para> + The DVB demux device lets you set TS, PID and section filters in the DVB + device. This is internally accomplished through calls to the + demux kernel module. + The demux device can be accessed through /dev/ost/demux. + </para> + + <para> The function calls defined in the include file <ulink + url="dmx.h"><citetitle>dmx.h</citetitle></ulink> are described in detail + below: + </para> + +<sect2> + <title>Demux API IO control calls</title> + +<para> +<blockquote><literallayout> + +int open(const char *deviceName, int flags); + + DESCRIPTION + + This system call, used with a device name of /dev/ost/demuxn, where n + denotes the specific demux device to be opened, allocates a new filter + and returns a handle which can be used for subsequent control of that + filter. This call has to be made for each filter to be used, i.e. every + returned file descriptor is a reference to a single filter. + /dev/ost/dvrn is a logical device to be used for retrieving Transport + Streams for digital video recording. n identifies the physical demux + device that provides the actual DVR functionlaity. When reading from + this device a transport stream containing the packets from all PES + filters set in the corresponfing demux device (/dev/osst/demuxn) + having the output set to DMX_OUT_TS_TAP. A recorded Transport Stream + is replayed by writing to this device. + This device can only be opened in read-write mode. + The significance of blocking or non-blocking mode is described in the + documentation for functions where there is a difference. It does not + affect the semantics of the open() call itself. A 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. + + + PARAMETERS + + const char *deviceName I Name of the demux device, which should be + /dev/ost/demuxn where n denotes the + specific demux device to be opened, or the + name of a logical DVR device, /dev/ost/dvrn. + + int flags I A bit-wise OR of the following flags: + O_RDWR read/write access. + O_NONBLOCK open in non-blocking mode + (blocking mode is the default). + + RETURNS + + ENODEV Device driver not loaded/available. + + EINVAL Invalid argument. + + EMFILE "Too many open files", i.e. no more filters available. + + ENOMEM The driver failed to allocate enough memory. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int close(int fd); + + DESCRIPTION + + This system call deactivates and deallocates a filter that was previously + allocated via the open() call. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + RETURNS + + EBADF fd is not a valid open file descriptor + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +size_t read(int fd, void *buf, size_t count); + + DESCRIPTION + + This system call returns filtered data, which might be section or PES + data. The filtered data is transferred from the driver's internal circular + buffer to buf. The maximum amount of data to be transferred is implied by + count. + + When returning section data the driver always tries to return a complete + single section (even though buf would provide buffer space for more data). + If the size of the buffer is smaller than the section as much as possible + will be returned, and the remaining data will be provided in subsequent + calls. + The size of the internal buffer is 2 * 4096 bytes (the size of two maximum + sized sections) by default. The size of this buffer may be changed by + using the DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, + or if the read operations are not performed fast enough, this may result + in a buffer overflow error. In this case EBUFFEROVERFLOW will be returned, + and the circular buffer will be emptied. + This call is blocking if there is no data to return, i.e. the process + will be put to sleep waiting for data, unless the O_NONBLOCK flag is + specified. + Note that in order to be able to read, the filtering process has to be + started by defining either a section or a PES filter by means of the + ioctl functions, and then starting the filtering process via the DMX_START + ioctl function or by setting the DMX_IMMEDIATE_START flag. + If the reading is done from a logical DVR demux device, the data will + constitute a Transport Stream including the packets from all PES filters + in the corresponding demux device /dev/ost/demuxn having the output set + to DMX_OUT_TS_TAP. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + void *buf O Pointer to the buffer to be used for returned filtered data. + + size_t count I Size of buf. + + RETURNS + + EWOULDBLOCK No data to return and O_NONBLOCK was specified. + + EBADF fd is not a valid open file descriptor + + ECRC Last section had a CRC error - no data + returned. The buffer is flushed. + + EBUFFEROVERFLOW The filtered data was not read from the buffer in + due time, resulting in non-read data being lost. + The buffer is flushed. + + ETIMEDOUT The section was not loaded within the stated + timeout period. See ioctl DMX_SET_FILTER for + how to set a timeout. + + EFAULT The driver failed to write to the callers buffer + due to an invalid *buf pointer. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +ssize_t write(int fd, const void *buf, size_t count); + + DESCRIPTION + + This system call is only provided by the logical device /dev/ost/dvrn, + where n identifies the physical demux device that provides the actual + DVR functionality. It is used for replay of a digitally recorded + Transport Stream. Matching filters have to be defined in the + corresponding physical demux device, /dev/ost/demuxn. + The amount of data to be transferred is implied by count. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + void *buf I Pointer to the buffer containing the Transport Stream. + + size_t count I Size of buf. + + RETURNS + + EWOULDBLOCK No data was written. This might happen if + O_NONBLOCK was specified and there is no more + buffer space available (if O_NONBLOCK is not + specified the function will block until buffer + space is available). + + EBUSY This error code indicates that there are + conflicting requests. The corresponding demux + device is setup to receive data from the front- + end. Make sure that these filters are stopped + and that the filters with input set to DMX_IN_DVR + are started. + + EBADF fd is not a valid open file descriptor + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl( int fd, int request = DMX_START); + + DESCRIPTION + + This ioctl call is used to start the actual filtering operation + defined via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals DMX_START for this command. + + RETURNS + + EBADF fd is not a valid file descriptor + + EINVAL Invalid argument, i.e. no filtering parameters + provided via the DMX_SET_FILTER or + DMX_SET_PES_FILTER functions. + + EBUSY This error code indicates that there are + conflicting requests. There are active filters + filtering data from another input source. Make + sure that these filters are stopped before starting + this filter. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl( int fd, int request = DMX_STOP); + + DESCRIPTION + + This ioctl call is used to stop the actual filtering operation defined + via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via + the DMX_START command. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals DMX_STOP for this command. + + RETURNS + + EBADF fd is not a valid file descriptor + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl( int fd, int request = DMX_SET_FILTER, struct dmxSctFilterParams *params); + + DESCRIPTION + + This ioctl call sets up a filter according to the filter and mask + parameters provided. A timeout may be defined stating number of seconds + to wait for a section to be loaded. A value of 0 means that no timeout + should be applied. Finally there is a flag field where it is possible to + state whether a section should be CRC-checked, whether the filter should + be a "one-shot" filter, i.e. if the filtering operation should be stopped + after the first section is received, and whether the filtering operation + should be started immediately (without waiting for a DMX_START ioctl call). + If a filter was previously set-up, this filter will be cancelled, and the + receive buffer will be flushed. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals DMX_SET_FILTER for this command. + + struct I Pointer to structure containing filter + + dmxSctFilterParams parameters. + *params + + RETURNS + + EBADF fd is not a valid file descriptor + + EINVAL Invalid argument. + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl( int fd, int request = DMX_SET_PES_FILTER, struct dmxPesFilterParams *params); + + DESCRIPTION + + This ioctl call sets up a PES filter according to the parameters provided. + By a PES filter is meant a filter that is based just on the packet + identifier (PID), i.e. no PES header or payload filtering capability is + supported. + The transport stream destination for the filtered output may be set. Also + the PES type may be stated in order to be able to e.g. direct a video + stream directly to the video decoder. Finally there is a flag field where + it is possible to state whether the filtering operation should be started + immediately (without waiting for a DMX_START ioctl call). + If a filter was previously set-up, this filter will be cancelled, and the + receive buffer will be flushed. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals DMX_SET_PES_FILTER for this command. + + struct I Pointer to structure containing filter + + dmxPesFilterParams parameters. + *params + + RETURNS + + EBADF fd is not a valid file descriptor + + EINVAL Invalid argument. + + EBUSY This error code indicates that there are + conflicting requests. There are active filters + filtering data from another input source. Make + sure that these filters are stopped before starting + this filter. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl( int fd, int request = DMX_SET_BUFFER_SIZE, unsigned long size); + + DESCRIPTION + + This ioctl call is used to set the size of the circular buffer used + for filtered data. The default size is two maximum sized sections, i.e. + if this function is not called a buffer size of 2 * 4096 bytes will be + used. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals DMX_SET_BUFFER_SIZE for this command. + + unsigned long size I Size of circular buffer. + + RETURNS + + EBADF fd is not a valid file descriptor. + + ENOMEM The driver was not able to allocate a buffer of the requested size. + + + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int ioctl( int fd, int request = DMX_GET_EVENT, struct dmxEvent *ev); + + DESCRIPTION + + This ioctl call returns an 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. + Only the latest event for each filter is saved. + + PARAMETERS + + int fd I File descriptor returned by a previous call to open(). + + int request I Equals DMX_SET_BUFFER_SIZE for this command. + + struct dmxEvent *ev O Pointer to the location where the event is to be stored. + + RETURNS + + EBADF fd is not a valid file descriptor. + + EFAULT ev points to an invalid address. + + EWOULDBLOCK There is no event pending, and the device is in non-blocking mode. + + + +</literallayout></blockquote> +</para> + +</sect2> + +</sect1> + +<sect1> + <title>DVB CA API</title> + + <para> The DVB CA device controls the conditional access hardware. + This allows functionalities like display of menues and entering of PIN numbers. + It can be accessed through /dev/ost/ca. + </para> + + <para> The function calls defined in the include file <ulink + url="ca.h"><citetitle>audio.h</citetitle></ulink> are described in + detail below: + </para> + +<sect2> + <title>CA API IO control calls</title> + + The exact io calls for this device have not been decided on yet. + +<para> + +</para> + +</sect2> + +</sect1> + + + +</chapter> + +<chapter> + <title>DVB Demux Kernel Module</title> + + <para> The demux device accesses the actual demux hardware through a + demux kernel module. This way other kernel modules (e.g. a generic DVB + network device) and not only the demux device can access the demux + hardware. + </para> + +<sect1> + <title>DVB Demux Kernel Module API</title> + + <para> The demux kernel API gives access to the demuxer of the DVB + hardware to other kernel modules which implement devices like the Demux + device or generic DVB network devices. + </para> + + <para> The function calls defined in the include file <ulink + url="demux.h"><citetitle>demux.h</citetitle></ulink> are described in + detail below: + </para> + +<sect2> + <title>Demux Directory API</title> + + <para> + The demux directory is a Linux kernel-wide facility for registering and + accessing the MPEG-2 TS demuxes in the system. Run-time registering and + unregistering of demux drivers is possible using this API. + </para> + <para> + All demux drivers in the directory implement the abstract interface dmx_demux_t. + </para> + +<para> +<blockquote><literallayout> +int dmx_register_demux ( dmx_demux_t* demux ) + + Description + + This function makes a demux driver interface available to the Linux kernel. + It is usually called by the init_module() function of the kernel module that + contains the demux driver. The caller of this function is responsible for + allocating dynamic or static memory for the demux structure and for initializing + its fields before calling this function. + The memory allocated for the demux structure must not be freed before calling + dmx_unregister_demux(), + + Returns + + 0 The command was successfully performed. + + -EEXIST A demux with the same value of the id field + already stored in the directory. + + -ENOSPC No space left in the directory. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int dmx_unregister_demux ( dmx_demux_t* demux ) + + Parameters + + dmx_demux_t* demux I/O Pointer to the demux API and instance variables. + + Description + + This function is called to indicate that the given demux interface is no longer + available. The caller of this function is responsible for freeing the memory of + the demux structure, if it was dynamically allocated before calling + dmx_register_demux(). + The cleanup_module() function of the kernel module that contains the demux + driver should call this function. Note that this function fails if the demux + is currently in use, i.e., release_demux() has not been called for the + interface. + + Returns + + 0 The command was successfully performed. + + -ENODEV No such demux registered. + + -EBUSY Demux is currently in use. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +struct list_head* dmx_get_demuxes () + + Description + + Provides the caller with the list of registered demux interfaces, using the + standard list structure defined in the include file linux/list.h. + The include file demux.h defines the macro DMX_DIR_ENTRY() for converting an + element of the generic type struct list_head* to the type dmx_demux_t*. + The caller must not free the memory of any of the elements obtained via this + function call. + + Returns + + A list of demux interfaces, or NULL in the case of an empty list. + + + +</literallayout></blockquote> +</para> +</sect2> + + +<sect2> + <title>Demux API</title> +<para> + The demux API should be implemented for each demux in the system. It is used to + select the TS source of a demux and to manage the demux resources. When the + demux client allocates a resource via the demux API, it receives a pointer + to the API of that resource. +</para> +<para> + Each demux receives its TS input from a DVB front-end or from the memory, as + set via the demux API. In a system with more than one front-end, the API can + be used to select one of the DVB front-ends as a TS source for a demux, unless + this is fixed in the HW platform. The demux API only controls front-ends + regarding their connections with demuxes; the APIs used to set the other + front-end parameters, such as tuning, are not defined in this document. +</para> +<para> + The functions that implement the abstract interface demux_t should be defined + static or module private and registered to the Demux Directory for external + access. It is not necessary to implement every function in the demux_t struct, + however (for example, a demux interface might support Section filtering, but + not TS or PES filtering). The API client is expected to check the value of any + function pointer before calling the function: the value of NULL means "function + not available". +</para> +<para> + Whenever the functions of the demux API modify shared data, the possibilities + of lost update and race condition problems should be addressed, e.g. by + protecting parts of code with mutexes. This is especially important on + multi-processor hosts. +</para> +<para> + Note that functions called from a bottom half context must not sleep, at least + in the 2.2.x kernels. Even a simple memory allocation can result in a kernel + thread being put to sleep if swapping is needed. For example, the Linux kernel + calls the functions of a network device interface from a bottom half context. + Thus, if a demux API function is called from network device code, the function + must not sleep. +</para> +<para> +<blockquote><literallayout> + +int open ( demux_t* demux ) + + + Parameters + + demux_t* demux I Pointer to the demux API and instance data. + + Description + + This function reserves the demux for use by the caller and, if necessary, + initializes the demux. When the demux is no longer needed, the function close() + should be called. + It should be possible for multiple clients to access the demux at the same time. + Thus, the function implementation should increment the demux usage count when + open() is called and decrement it when close() is called. + + Returns + + 0 The command was successfully performed. + + -EUSERS Maximum usage count reached. + + -EINVAL Bad parameter. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int close ( demux_t* demux ) + + Parameters + + demux_t* demux I Pointer to the demux API and instance data. + + Description + + The function is called to indicate that the API client does not need to use + the demux anymore. As a result of this function, the demux usage count is + decremented by one. + When the usage count drops to zero, any demux resources can be released. + + Returns + + 0 The command was successfully performed. + + -ENODEV The demux was not in use. + + -EINVAL Bad parameter. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int write ( demux_t* demux, const char* buf, size_t count) + + Parameters + + demux_t* demux I/O Pointer to the demux API and instance data. + + const char* buf I Pointer to the TS data in kernel-space memory. + + size_t length I Length of the TS data. + + + + Description + + This function provides the demux driver with a memory buffer containing TS + packets. Instead of receiving TS packets from the DVB front-end, the demux + driver software will read packets from the memory. Any clients of this demux + with active TS, PES or Section filters will receive filtered data via the Demux + callback API (see 0). The function returns when all the data in the buffer has + been consumed by the demux. + Demux hardware typically cannot read TS from the memory. If this is the case, + memory-based filtering has to be implemented entirely in software. + + Returns + + 0 The command was successfully performed. + + -ENOSYS The command is not implemented. + + -EINVAL Bad parameter. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int allocate_ts_feed ( dmx_demux_t* demux, dmx_ts_feed_t** feed, dmx_ts_cb callback ) + + Parameters + + demux_t* demux I/O Pointer to the demux API and instance data. + + dmx_ts_feed_t** feed O Pointer to the TS feed API and instance data. + + dmx_ts_cb callback I Pointer to the callback function for + passing received TS packet + + Description + + Allocates a new TS feed, which is used to filter the TS packets carrying a + certain PID. + The TS feed normally corresponds to a hardware PID filter on the demux chip. + + Returns + + 0 The command was successfully performed. + + -EBUSY No more TS feeds available. + + -ENOSYS The command is not implemented. + + -EINVAL Bad parameters. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +int release_ts_feed ( dmx_demux_t* demux, dmx_ts_feed_t* feed) + + Parameters + + dmx_demux_t* demux I/O Pointer to the demux API and + instance data. + dmx_ts_feed_t* feed I Pointer to the TS feed API and + instance data. + + Function Detailed Description + Releases the resources allocated with allocate_ts_feed(). Any filtering in progress + on the TS feed should be stopped before calling this function. + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +allocate_pes_feed() + + TBD + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +release_pes_feed() + + TBD + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +int allocate_section_feed ( dmx_demux_t* demux, + dmx_section_feed_t** + feed, + dmx_section_cb callback ) + + Function Parameters + demux_t* demux I/O Pointer to the demux API and + instance data. + dmx_section_feed_t** feed O Pointer to the section feed API and + + instance data. + dmx_section_cb callback I Pointer to the callback function for + passing received sections + + Function Detailed Description + Allocates a new section feed, i.e. a demux resource for filtering and receiving sections. + On platforms with hardware support for section filtering, a section feed is directly + mapped to the demux HW. On other platforms, TS packets are first PID filtered in + hardware and a hardware section filter then emulated in software. + The caller obtains an API pointer of type dmx_section_feed_t as an out parameter. + Using this API the caller can set filtering parameters and start receiving sections. + + Function Returns + 0 The command was successfully performed. + -EBUSY No more section feeds available. + -ENOSYS The command is not implemented. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int release_section_feed ( dmx_demux_t* demux, + dmx_section_feed_t* + feed + ) + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and + instance data. + dmx_section_feed_t* feed I Pointer to the section feed API and + instance data. + + Function Detailed Description + Releases the resources allocated with allocate_section_feed(), including allocated + filters. Any filtering in progress on the section feed should be stopped before calling + this function. + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int descramble_mac_address ( dmx_demux_t* demux, + __u8* + buffer1, + size_t + buffer1_length, + __u8* buffer2, + size_t + buffer2_length, + __u16 pid ) + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and + instance data. + __u8* buffer1 I Pointer to the first byte of the + section. + size_t buffer1_length I Length of the section data, + including headers and CRC, in + buffer1. + __u8* buffer2 I Pointer to the tail of the section + data, or NULL. The pointer has a + non-NULL value if the section wraps + past the end of a cyclic buffer. + size_t buffer2_length I Length of the section data, + including headers and CRC, in + buffer2 + __u16 pid I The PID on which the section was + received. Useful for obtaining the + descrambling key, e.g. from a DVB + Common Access facility. + + Function Detailed Description + This function runs a descrambling algorithm on the destination MAC address field of a + DVB Datagram Section, replacing the original address with its unencrypted version. + Otherwise, the description on the function descramble_section_payload() applies + also to this function. + + Function Returns + 0 The command was successfully performed. + -ENOSYS No descrambling facility available. + -EINVAL Bad parameters. + + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int descramble_section_payload ( dmx_demux_t* demux, + __u8* + buffer1, + size_t + buffer1_length, + __u8* buffer2, + size_t + buffer2_length, + __u16 pid ) + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and + instance data. + __u8* buffer1 I/O Pointer to the first byte of the + section. + size_t buffer1_length I Length of the section data, + including headers and CRC, in + buffer1. + __u8* buffer2 I Pointer to the tail of the section + data, or NULL. The pointer has a + non-NULL value if the section wraps + past the end of a cyclic buffer. + size_t buffer2_length I Length of the section data, + including headers and CRC, in + buffer2 + __u16 pid I The PID on which the section was + received. Useful for obtaining the + descrambling key, e.g. from a DVB + Common Access facility. + + Function Detailed Description + This function runs a descrambling algorithm on the payload of a DVB Datagram + Section, replacing the original payload with its unencrypted version. The function will + be called from the demux API implementation; the API client need not call this function + directly. + Section-level scrambling algorithms are currently standardized only for DVB-RCC + (return channel over 2-directional cable TV network) systems. For all other DVB + networks, encryption schemes are likely to be proprietary to each data broadcaster. + Thus, it is expected that this function pointer will have the value of NULL (i.e., function + not available) in most demux API implementations. Nevertheless, it should be possible + to use the function pointer as a hook for dynamically adding a "plug-in" descrambling + facility to a demux driver. + + + While this function is not needed with hardware-based section descrambling, the + descramble_section_payload function pointer can be used to override the default + hardware-based descrambling algorithm: if the function pointer has a non-NULL value, + the corresponding function should be used instead of any descrambling hardware. + + Function Returns + 0 The command was successfully performed. + -ENOSYS No descrambling facility available. + -EINVAL Bad parameters. + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int add_frontend ( dmx_demux_t* demux, + dmx_frontend_t* + frontend); + + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and instance + data. + dmx_frontend_t* frontend I/O Pointer to the front-end instance data. + + Function Detailed Description + Registers a connectivity between a demux and a front-end, i.e., indicates that the + demux can be connected via a call to connect_frontend() to use the given front-end + as a TS source. The client of this function has to allocate dynamic or static memory for + the frontend structure and initialize its fields before calling this function. + This function is normally called during the driver initialization. The caller must not free + the memory of the frontend struct before successfully calling remove_frontend(). + + Function Returns + 0 The command was successfully performed. + -EEXIST A front-end with the same value of the id field + already registered. + -EINUSE The demux is in use. + -ENOMEM No more front-ends can be added. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int remove_frontend ( dmx_demux_t* demux, + dmx_frontend_t* frontend ) + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and instance + data. + dmx_frontend_t* frontend I/O Pointer to the front-end instance data. + + Function Detailed Description + Indicates that the given front-end, registered by a call to add_frontend(), can no + longer be connected as a TS source by this demux. The function should be called + when a front-end driver or a demux driver is removed from the system. If the front-end + is in use, the function fails with the return value of -EBUSY. + After succesfully calling this function, the caller can free the memory of the frontend + struct if it was dynamically allocated before the add_frontend() operation. + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + -EBUSY The front-end is in use, i.e. a call to + connect_frontend() has not been followed by + a call to disconnect_frontend(). + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +struct list_head* get_frontends ( dmx_demux_t* demux ) + Function Parameters + dmx_demux_t* demux I Pointer to the demux API and + instance data. + + Function Detailed Description + Provides the APIs of the front-ends that have been registered for this demux. Any of + the front-ends obtained with this call can be used as a parameter for + connect_frontend(). + + + The include file demux.h contains the macro DMX_FE_ENTRY() for converting an + element of the generic type struct list_head* to the type dmx_frontend_t*. + The caller must not free the memory of any of the elements obtained via this function + call. + + Function Returns + A list of front-end interfaces, or NULL in the case of an empty list. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int connect_frontend ( dmx_demux_t* demux, + dmx_frontend_t* frontend ) + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and instance + data. + dmx_frontend_t* frontend I/O Pointer to the front-end instance data. + + Function Detailed Description + Connects the TS output of the front-end to the input of the demux. A demux can only + be connected to a front-end registered to the demux with the function + add_frontend(). + It may or may not be possible to connect multiple demuxes to the same front-end, + depending on the capabilities of the HW platform. When not used, the front-end should + be released by calling disconnect_frontend(). + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + -EBUSY The front-end is in use. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int disconnect_frontend ( dmx_demux_t* demux ) + + + Function Parameters + dmx_demux_t* demux I/O Pointer to the demux API and instance data. + + Function Detailed Description + Disconnects the demux and a front-end previously connected by a + connect_frontend() call. + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + + +</literallayout></blockquote> +</para> +</sect2> + +<sect2> + <title>Demux Callback API</title> +<para> + This kernel-space API comprises the callback functions that deliver filtered data to the + demux client. Unlike the other APIs, these API functions are provided by the client and + called from the demux code. +</para> +<para> + The function pointers of this abstract interface are not packed into a structure as in the + other demux APIs, because the callback functions are registered and used + independent of each other. As an example, it is possible for the API client to provide + several callback functions for receiving TS packets and no callbacks for PES packets + or sections. +</para> +<para> + The functions that implement the callback API need not be re-entrant: when a demux + driver calls one of these functions, the driver is not allowed to call the function again + before the original call returns. If a callback is triggered by a hardware interrupt, it is + recommended to use the Linux "bottom half" mechanism or start a tasklet instead of + making the callback function call directly from a hardware interrupt. + +</para> +<para> +<blockquote><literallayout> +int dmx_ts_cb ( __u8* buffer1, size_t buffer1_length, + __u8* buffer2, size_t buffer2_length, + dmx_ts_feed_t* source, dmx_success_t success ) + + Parameters + + __u8* buffer1 I Pointer to the start of the filtered TS packets. + + size_t buffer1_length I Length of the TS data in buffer1. + + __u8* buffer2 I Pointer to the tail of the filtered TS packets, or NULL. + + size_t buffer2_length I Length of the TS data in buffer2. + + dmx_ts_feed_t* source I Indicates which TS feed is the source of the callback. + + dmx_success_t success I Indicates if there was an error in TS reception. + + Description + + This function, provided by the client of the demux API, is called from the + demux code. The function is only called when filtering on this TS feed has + been enabled using the start_filtering() function. If conflict resolution + is used (see Error! Reference source not found.), no callbacks are made to + clients that have been put "on hold" regarding a TS Feed resource. + Any TS packets that match the filter settings are copied to a cyclic buffer. + The filtered TS packets are delivered to the client using this callback + function. The size of the cyclic buffer is controlled by the + circular_buffer_size parameter of the set() function in the TS Feed API. It is + expected that the buffer1 and buffer2 callback parameters point to addresses + within the circular buffer, but other implementations are also + possible. Note that the called party should not try to free the memory the + buffer1 and buffer2 parameters point to. + When this function is called, the buffer1 parameter typically points to the + start of the first undelivered TS packet within a cyclic buffer. The buffer2 + buffer parameter is normally NULL, except when the received TS packets have + crossed the last address of the cyclic buffer and "wrapped" to the beginning + of the buffer. In the latter case the buffer1 parameter would contain an + address within the cyclic buffer, while the buffer2 parameter would contain + the first address of the cyclic buffer. + The number of bytes delivered with this function (i.e. buffer1_length + + buffer2_length) is usually equal to the value of callback_length parameter given + in the set() function, with one exception: if a timeout occurs before receiving + callback_length bytes of TS data, any undelivered packets are immediately + delivered to the client by calling this function. The timeout duration is + controlled by the set() function in the TS Feed API. + If a TS packet is received with errors that could not be fixed by the TS-level + forward error correction (FEC), the Transport_error_indicator flag of the TS + packet header should be set. The TS packet should not be discarded, as the + error can possibly be corrected by a higher layer protocol. + If the called party is slow in processing the callback, it is possible that + the circular buffer eventually fills up. If this happens, the demux driver + should discard any TS packets received while the buffer is full. The error + should be indicated to the client on the next callback by setting the success + parameter to the value of DMX_OVERRUN_ERROR. + + The type of data returned to the callback can be selected by the + new function int (*set_type) (struct dmx_ts_feed_s* feed, int type, + dmx_ts_pes_t pes_type) which is part of the dmx_ts_feed_s struct + (also cf. to the include file ost/demux.h) + The type parameter decides if the raw TS packet (TS_PACKET) or just the + payload (TS_PACKET|TS_PAYLOAD_ONLY) should be returned. + If additionally the TS_DECODER bit is set the stream will also be sent + to the hardware MPEG decoder. In this case, the second flag decides + as what kind of data the stream should be interpreted. + The possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, + DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, DMX_TS_PES_PCR, or + DMX_TS_PES_OTHER. + + + Returns + + 0 Continue filtering. + + -1 Stop filtering - has the same effect as a call + to stop_filtering() on the TS Feed API. + + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +dmx_pes_cb() + + TBD + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int dmx_section_cb ( __u8* buffer1, + size_t + buffer1_length, + __u8* + buffer2, + size_t buffer2_length, + dmx_section_filter_t* + source, + dmx_success_t success ) + + Function Parameters + __u8* buffer1 I Pointer to the start of the filtered section, e.g. + within the cyclic buffer of the demux driver. + size_t buffer1_length I Length of the filtered section data in buffer1, + including headers and CRC. + __u8* buffer2 Pointer to the tail of the filtered section data, or + NULL. Useful to handle the wrapping of a cyclic + buffer. + size_t buffer2_length Length of the filtered section data in buffer2, + including headers and CRC. + dmx_section_filter_t* I Indicates the filter that triggered the callback. + filter + dmx_success_t success I Indicates if there was an error in section + reception. + + Function Detailed Description + This function, provided by the client of the demux API, is called from the demux code. + The function is only called when filtering of sections has been enabled using the + function start_filtering() of the section feed API. + When the demux driver has received a complete section that matches at least one + section filter, the client is notified via this callback function. Normally this function is + called for each received section; however, it is also possible to deliver multiple sections + with one callback, for example when the system load is high. + If an error occurs while receiving a section, this function should be called with the + corresponding error type set in the success field, whether or not there is data to + deliver. + The Section Feed implementation should maintain a cyclic buffer for received sections. + However, this is not necessary if the Section Feed API is implemented as a client of + + + the TS Feed API, because the TS Feed implementation then buffers the + received data. + The size of the circular buffer can be configured using the set() function in the + Section Feed API. If there is no room in the circular buffer when a new section is + received, the section must be discarded. If this happens, the value of the success + parameter should be DMX_OVERRUN_ERROR on the next callback. + + Function Returns + 0 Continue filtering. + -1 Stop filtering - has the same effect as a call + to stop_filtering() on the Section Feed + API. + +</literallayout></blockquote> +</para> + +</sect2> + +<sect2> + <title>TS Feed API</title> +<para> + A TS feed is typically mapped to a hardware PID filter on the demux chip. Using this + API, the client can set the filtering properties to start/stop filtering TS packets on a + particular TS feed. The API is defined as an abstract interface of the type + dmx_ts_feed_t. +</para> +<para> + The functions that implement the interface should be defined static or module + private. The client can get the handle of a TS feed API by calling the function + allocate_ts_feed() in the demux API. +</para> +<para> +<blockquote><literallayout> + +int set ( dmx_ts_feed_t* feed, + __u16 + pid, + size_t callback_length, + size_t + cyclic_buffer_size, + int + descramble, + struct timespec timeout) + + Parameters + + dmx_ts_feed_t* feed I/O Pointer to the TS feed API and + instance data. + __u16 pid I PID value to filter. Only the TS + packets carrying the specified PID will + be passed to the API client. + size_t callback_length I Number of bytes to deliver with each + call to the dmx_ts_cb() callback + function. The value of this + parameter should be a multiple of + 188. + + size_t cyclic_buffer_size I Size of the cyclic buffer for the filtered + TS packets. + int descramble I If non-zero, descramble the filtered + TS packets. + struct timespec timeout I Maximum time to wait before + delivering received TS packets to the + client. + + Function Detailed Description + This function sets the parameters of a TS feed. Any filtering in progress on the TS feed + must be stopped before calling this function. + + Function Returns + 0 The command was successfully performed. + -ENOMEM Not enough memory for the requested + buffer size. + -ENOSYS No descrambling facility available for TS + packets. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> + +<para> +<blockquote><literallayout> + +int start_filtering ( dmx_ts_feed_t* feed ) + + Parameters + + dmx_ts_feed_t* feed I Pointer to the TS feed API and instance data. + + Function Detailed Description + Starts filtering TS packets on this TS feed, according to its settings. The PID value to + filter can be set by the API client. All matching TS packets are delivered + asynchronously to the client, using the callback function registered with + allocate_ts_feed(). + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int stop_filtering ( dmx_ts_feed_t* feed ) + + Parameters + + dmx_ts_feed_t* feed I/O Pointer to the TS feed API and instance data. + + Description + + Stops filtering TS packets on this TS feed. + + Returns + + 0 The command was successfully performed. + + -EINVAL Bad parameters. + + + +</literallayout></blockquote> +</para> +</sect2> + +<sect2> + <title>PES Feed API</title> +<para> + TBD +</para> +</sect2> + +<sect2> + <title>Section Feed API</title> +<para> + A section feed is a resource consisting of a PID filter and a set of section filters. Using + this API, the client can set the properties of a section feed and to start/stop filtering. + The API is defined as an abstract interface of the type dmx_section_feed_t. + The functions that implement the interface should be defined static or module + private. The client can get the handle of a section feed API by calling the function + allocate_section_feed() in the demux API. +</para> +<para> + On demux platforms that provide section filtering in hardware, the Section Feed API + implementation provides a software wrapper for the demux hardware. Other platforms + may support only PID filtering in hardware, requiring that TS packets are converted to + sections in software. In the latter case the Section Feed API implementation can be a + client of the TS Feed API. +</para> + +<para> +<blockquote><literallayout> + +int set ( dmx_section_feed_t* feed, __u16 pid, size_t circular_buffer_size, + int descramble, int check_crc ) + + Parameters + + dmx_section_feed_t* feed I/O Pointer to the section feed API and + instance data. + __u16 pid I PID value to filter; only the TS packets + carrying the specified PID will be + accepted. + size_t circular_buffer_size I Size of the cyclic buffer for filtered + sections. + int descramble I If non-zero, descramble any sections + that are scrambled. + int check_crc I If non-zero, check the CRC values of + filtered sections. + + Function Detailed Description + This function sets the parameters of a section feed. Any filtering in progress on the + section feed must be stopped before calling this function. + If descrambling is enabled, the payload_scrambling_control and + address_scrambling_control fields of received DVB datagram sections should be + observed. If either one is non-zero, the section should be descrambled either in + hardware or using the functions descramble_mac_address() and + descramble_section_payload() of the demux API. Note that according to the + MPEG-2 Systems specification [3], only the payloads of private sections can be + scrambled while the rest of the section data must be sent in the clear. + + Function Returns + 0 The command was successfully performed. + -ENOMEM Not enough memory available for the requested + buffer size. + -ENOSYS No descrambling facility available for sections. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> + +int allocate_filter(dmx_section_feed_t* feed, dmx_section_filter_t** filter) + + Parameters + dmx_section_feed_t* feed I/O Pointer to the section feed API and + instance data. + dmx_section_filter_t** filter O Pointer to the allocated filter. + + + Function Detailed Description + This function is used to allocate a section filter on the demux. It should only be called + when no filtering is in progress on this section feed. If a filter cannot be allocated, the + function fails with -ENOSPC. See below for the format of the section filter struct provided + as an out parameter: + typedef struct { + __u8 filter_value [DMX_MAX_FILTER_SIZE]; + __u8 filter_mask [DMX_MAX_FILTER_SIZE]; + struct dmx_section_feed_s* parent; /* Back-pointer */ + void* priv; /* Private data of the client */ + } dmx_section_filter_t; + + The bitfields filter_mask and filter_value should only be modified when no + filtering is in progress on this section feed. filter_mask controls which bits of + filter_value are compared with the section headers/payload. On a binary value of 1 + in filter_mask, the corresponding bits are compared. The filter only accepts sections + that are equal to filter_value in all the tested bit positions. Any changes to the + values of filter_mask and filter_value are guaranteed to take effect only when + the start_filtering() function is called next time. The parent pointer in the struct + is initialized by the API implementation to the value of the feed parameter. The priv + pointer is not used by the API implementation, and can thus be freely utilized by the + caller of this function. Any data pointed to by the priv pointer is available to the + recipient of the dmx_section_cb() function call. + While the maximum section filter length (DMX_MAX_FILTER_SIZE) is currently set at 16 + bytes, hardware filters of that size are not available on all platforms. Therefore, section + filtering will often take place first in hardware, followed by filtering in software for the + header bytes that were not covered by a hardware filter. The filter_mask field can be + checked to determine how many bytes of the section filter are actually used, and if the + hardware filter will suffice. Additionally, software-only section filters can optionally be + allocated to clients when all hardware section filters are in use. + Note that on most demux hardware it is not possible to filter on the section_length field + of the section header - thus this field is ignored, even though it is included in + filter_value and filter_mask fields. + + Function Returns + 0 The command was successfully performed. + -ENOSPC No filters of given type and length available. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +int release_filter ( dmx_section_feed_t* feed, dmx_section_filter_t* filter) + + Parameters + dmx_section_feed_t* feed I/O Pointer to the section feed API and instance + data. + dmx_section_filter_t* I/O Pointer to the instance data of a section filter. + filter + + Function Detailed Description + This function releases all the resources of a previously allocated section filter. The + function should not be called while filtering is in progress on this section feed. After + calling this function, the caller should not try to dereference the filter pointer. + + Function Returns + 0 The command was successfully performed. + -ENODEV No such filter allocated. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +int start_filtering ( dmx_section_feed_t* feed ) + + Parameters + dmx_section_feed_t* feed I/O Pointer to the section feed API and + instance data. + + Function Detailed Description + Starts filtering sections on this section feed, according to its settings. Sections are first + filtered based on their PID and then matched with the section filters allocated for this + feed. If the section matches the PID filter and at least one section filter, it is delivered + to the API client. The section is delivered asynchronously using the callback function + registered with allocate_section_feed(). + + Function Returns + 0 The command was successfully performed. + -EINVAL Bad parameters. + +</literallayout></blockquote> +</para> +<para> +<blockquote><literallayout> +int stop_filtering ( dmx_section_feed_t* feed ) + + Parameters + + dmx_section_feed_t* feed I/O Pointer to the section feed API and instance data. + + Description + + Stops filtering sections on this section feed. Note that any changes to the + filtering parameters (filter_value, filter_mask, etc.) should only be made + when filtering is stopped. + + Returns + + 0 The command was successfully performed. + + -EINVAL Bad parameters. + + + +</literallayout></blockquote> +</para> + + +</sect2> + +</sect1> + +</chapter> + +</part> +</article> |