diff options
| -rw-r--r-- | dvb-spec/sgml/Makefile | 7 | ||||
| -rw-r--r-- | dvb-spec/sgml/README | 12 | ||||
| -rw-r--r-- | dvb-spec/sgml/audio.sgml | 1473 | ||||
| -rw-r--r-- | dvb-spec/sgml/ca.sgml | 221 | ||||
| -rw-r--r-- | dvb-spec/sgml/demux.sgml | 973 | ||||
| -rw-r--r-- | dvb-spec/sgml/dvbapi-complete.sgml | 9503 | ||||
| -rw-r--r-- | dvb-spec/sgml/dvbapi.sgml | 34 | ||||
| -rw-r--r-- | dvb-spec/sgml/dvbstb.pdf | bin | 1786 -> 1881 bytes | |||
| -rw-r--r-- | dvb-spec/sgml/examples.sgml | 365 | ||||
| -rw-r--r-- | dvb-spec/sgml/fdl.sgml | 374 | ||||
| -rw-r--r-- | dvb-spec/sgml/intro.sgml | 22 | ||||
| -rw-r--r-- | dvb-spec/sgml/kdapi.sgml | 2309 | ||||
| -rw-r--r-- | dvb-spec/sgml/net.sgml | 12 | ||||
| -rw-r--r-- | dvb-spec/sgml/video.sgml | 1971 |
14 files changed, 7740 insertions, 9536 deletions
diff --git a/dvb-spec/sgml/Makefile b/dvb-spec/sgml/Makefile index f39d7a97c..9471e4b98 100644 --- a/dvb-spec/sgml/Makefile +++ b/dvb-spec/sgml/Makefile @@ -4,7 +4,12 @@ SGMLS = \ dvbapi.sgml \ intro.sgml \ frontend.sgml \ - devices.sgml \ + demux.sgml \ + video.sgml \ + audio.sgml \ + ca.sgml \ + net.sgml \ + kdapi.sgml \ examples.sgml \ fdl.sgml \ entities.sgml \ diff --git a/dvb-spec/sgml/README b/dvb-spec/sgml/README index 99dd5fef3..6f62d3ae2 100644 --- a/dvb-spec/sgml/README +++ b/dvb-spec/sgml/README @@ -1,13 +1,11 @@ -This directory doesn't contain the official DVB API +This directory doesn't contain the official DVB API. -It contains an effort of porting it from LaTex to Docbook XML 4.1.2 +It contains a port from LaTex to Docbook XML 4.1.2 It is still a work undergoing. Contributions are welcome. CURRENT STATUS: -Chapters 1 and 2 were converted. The remaining chapters aren't yet. - -File dvbapi-complete.sgml is a temporary file generated by a tool that -automatically do the conversion. While it doesn't compile, it is a good -starting point for the conversion. +All chapters were converted. The resulting pdf and html are close to the +original LaTex book. Yet, it lacks some efforts to improve +the output layout and it lacks a topic index. diff --git a/dvb-spec/sgml/audio.sgml b/dvb-spec/sgml/audio.sgml new file mode 100644 index 000000000..eeb96b8a0 --- /dev/null +++ b/dvb-spec/sgml/audio.sgml @@ -0,0 +1,1473 @@ +<title>DVB Audio Device</title> +<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It +can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and +ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your +application. +</para> +<para>Please note that some DVB cards don’t have their own MPEG decoder, which results in +the omission of the audio and video device. +</para> + +<section id="audio_data_types"> +<title>Audio Data Types</title> +<para>This section describes the structures, data types and defines used when talking to the +audio device. +</para> + +<section id="audio_stream_source_t"> +<title>audio_stream_source_t</title> +<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take +the following values, depending on whether we are replaying from an internal (demux) or +external (user write) source. +</para> +<programlisting> + typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY + } audio_stream_source_t; +</programlisting> +<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the +DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY +is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system +call. +</para> + +</section> +<section id="audio_play_state_t"> +<title>audio_play_state_t</title> +<para>The following values can be returned by the AUDIO_GET_STATUS call representing the +state of audio playback. +</para> +<programlisting> + typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED + } audio_play_state_t; +</programlisting> + +</section> +<section id="audio_channel_select_t"> +<title>audio_channel_select_t</title> +<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the +following values. +</para> +<programlisting> + typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, + } audio_channel_select_t; +</programlisting> + +</section> +<section id="struct_audio_status"> +<title>struct audio_status</title> +<para>The AUDIO_GET_STATUS call returns the following structure informing about various +states of the playback operation. +</para> +<programlisting> + typedef struct audio_status { + boolean AV_sync_state; + boolean mute_state; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; + boolean bypass_mode; + } audio_status_t; +</programlisting> + +</section> +<section id="struct_audio_mixer"> +<title>struct audio_mixer</title> +<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio +volume. +</para> +<programlisting> + typedef struct audio_mixer { + unsigned int volume_left; + unsigned int volume_right; + } audio_mixer_t; +</programlisting> + +</section> +<section id="audio_encodings"> +<title>audio encodings</title> +<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following +bits set according to the hardwares capabilities. +</para> +<programlisting> + #define AUDIO_CAP_DTS 1 + #define AUDIO_CAP_LPCM 2 + #define AUDIO_CAP_MP1 4 + #define AUDIO_CAP_MP2 8 + #define AUDIO_CAP_MP3 16 + #define AUDIO_CAP_AAC 32 + #define AUDIO_CAP_OGG 64 + #define AUDIO_CAP_SDDS 128 + #define AUDIO_CAP_AC3 256 +</programlisting> + +</section> +<section id="struct_audio_karaoke"> +<title>struct audio_karaoke</title> +<para>The ioctl AUDIO_SET_KARAOKE uses the following format: +</para> +<programlisting> + typedef + struct audio_karaoke{ + int vocal1; + int vocal2; + int melody; + } audio_karaoke_t; +</programlisting> +<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both, +Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the +right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left +and right. +</para> + +</section> +<section id="audio_attributes"> +<title>audio attributes</title> +<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: +</para> +<programlisting> + typedef uint16_t audio_attributes_t; + /⋆ bits: descr. ⋆/ + /⋆ 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, ⋆/ + /⋆ 12 multichannel extension ⋆/ + /⋆ 11-10 audio type (0=not spec, 1=language included) ⋆/ + /⋆ 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) ⋆/ + /⋆ 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, ⋆/ + /⋆ 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) ⋆/ + /⋆ 2- 0 number of audio channels (n+1 channels) ⋆/ +</programlisting> + </section></section> +<section id="audio_function_calls"> +<title>Audio Function Calls</title> + + +<section id="audio_fopen"> +<title>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) + 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 error + code 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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific audio device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="audio_fclose"> +<title>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened audio device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="audio_fwrite"> +<title>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>size_t write(int fd, const void ⋆buf, size_t count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer containing the PES data.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode AUDIO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>Attempted to write more data than the internal buffer can + hold.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_STOP</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to stop playing the current stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_STOP);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_STOP for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_PLAY</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to start playing an audio stream from the + selected source.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_PLAY);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_PLAY for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_PAUSE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_PAUSE for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SELECT_SOURCE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, + audio_stream_source_t source);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SELECT_SOURCE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_stream_source_t + source</para> +</entry><entry + align="char"> +<para>Indicates the source that shall be used for the Audio + stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_MUTE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the audio device to mute the stream that is currently being + played.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_MUTE, + boolean state);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_MUTE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean state</para> +</entry><entry + align="char"> +<para>Indicates if audio device shall mute or not.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE Audio Mute</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE Audio Un-mute</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_AV_SYNC</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, + boolean state);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_AV_SYNC for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean state</para> +</entry><entry + align="char"> +<para>Tells the DVB subsystem if A/V synchronization shall be + ON or OFF.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE AV-sync ON</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE AV-sync OFF</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_BYPASS_MODE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 if the hardware can handle it.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_SET_BYPASS_MODE, boolean mode);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_BYPASS_MODE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean mode</para> +</entry><entry + align="char"> +<para>Enables or disables the decoding of the current Audio + stream in the DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE Bypass is disabled</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE Bypass is enabled</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_CHANNEL_SELECT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_CHANNEL_SELECT for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_channel_select_t + ch</para> +</entry><entry + align="char"> +<para>Select the output format of the audio (mono left/right, + stereo).</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter ch.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_GET_STATUS</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to return the current state of the Audio + Device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_GET_STATUS, + struct audio_status ⋆status);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_GET_STATUS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct audio_status + *status</para> +</entry><entry + align="char"> +<para>Returns the current state of Audio Device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_GET_CAPABILITIES</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities + of the audio hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_GET_CAPABILITIES, unsigned int ⋆cap);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_GET_CAPABILITIES for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned int *cap</para> +</entry><entry + align="char"> +<para>Returns a bit array of supported sound formats.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>cap points to an invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_CLEAR_BUFFER</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to clear all software and hardware buffers + of the audio decoder device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_CLEAR_BUFFER for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_ID</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl selects which sub-stream is to be decoded if a program or system + stream is sent to the video device. If no audio stream type is set the id has to be + in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] + for LPCM. More specifications may follow for other stream types. If the stream + type is set the id just specifies the substream id of the audio stream and only + the first 5 bits are recognized.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_ID, int + id);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int id</para> +</entry><entry + align="char"> +<para>audio sub-stream id</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid sub-stream id.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_MIXER</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = AUDIO_SET_MIXER, + audio_mixer_t ⋆mix);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_mixer_t *mix</para> +</entry><entry + align="char"> +<para>mixer settings.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>mix points to an invalid address.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_STREAMTYPE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl tells the driver which kind of audio stream to expect. This is useful + if the stream offers several audio sub-streams like LPCM and AC3.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, + int type);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_STREAMTYPE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>int type</para> +</entry><entry + align="char"> +<para>stream type</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>type is not a valid or supported stream type.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_EXT_ID</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl can be used to set the extension id for MPEG streams in DVD + playback. Only the first 3 bits are recognized.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int + id);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_EXT_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int id</para> +</entry><entry + align="char"> +<para>audio sub_stream_id</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>id is not a valid id.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_ATTRIBUTES</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is intended for DVD playback and allows you to set certain + information about the audio stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, + audio_attributes_t attr );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_attributes_t + attr</para> +</entry><entry + align="char"> +<para>audio attributes according to section ??</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>attr is not a valid or supported attribute setting.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>AUDIO_SET_KARAOKE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, + audio_karaoke_t ⋆karaoke);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_SET_STREAMTYPE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_karaoke_t + *karaoke</para> +</entry><entry + align="char"> +<para>karaoke settings according to section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>karaoke is not a valid or supported karaoke setting.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section> +</section> diff --git a/dvb-spec/sgml/ca.sgml b/dvb-spec/sgml/ca.sgml new file mode 100644 index 000000000..e2a70797d --- /dev/null +++ b/dvb-spec/sgml/ca.sgml @@ -0,0 +1,221 @@ +<title>DVB CA Device</title> +<para>The DVB CA device controls the conditional access hardware. It can be accessed through +<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by +including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application. +</para> + +<section id="ca_data_types"> +<title>CA Data Types</title> + + +<section id="ca_slot_info_t"> +<title>ca_slot_info_t</title> + <programlisting> + /⋆ slot interface types and info ⋆/ + + typedef struct ca_slot_info_s { + int num; /⋆ slot number ⋆/ + + int type; /⋆ CA interface this slot supports ⋆/ + #define CA_CI 1 /⋆ CI high level interface ⋆/ + #define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/ + #define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/ + #define CA_SC 128 /⋆ simple smart card interface ⋆/ + + unsigned int flags; + #define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/ + #define CA_CI_MODULE_READY 2 + } ca_slot_info_t; +</programlisting> + +</section> +<section id="ca_descr_info_t"> +<title>ca_descr_info_t</title> + <programlisting> + typedef struct ca_descr_info_s { + unsigned int num; /⋆ number of available descramblers (keys) ⋆/ + unsigned int type; /⋆ type of supported scrambling system ⋆/ + #define CA_ECD 1 + #define CA_NDS 2 + #define CA_DSS 4 + } ca_descr_info_t; +</programlisting> + +</section> +<section id="ca_cap_t"> +<title>ca_cap_t</title> + <programlisting> + typedef struct ca_cap_s { + unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/ + unsigned int slot_type; /⋆ OR of all supported types ⋆/ + unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/ + unsigned int descr_type;/⋆ OR of all supported types ⋆/ + } ca_cap_t; +</programlisting> + +</section> +<section id="ca_msg_t"> +<title>ca_msg_t</title> + <programlisting> + /⋆ a message to/from a CI-CAM ⋆/ + typedef struct ca_msg_s { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; + } ca_msg_t; +</programlisting> + +</section> +<section id="ca_descr_t"> +<title>ca_descr_t</title> + <programlisting> + typedef struct ca_descr_s { + unsigned int index; + unsigned int parity; + unsigned char cw[8]; + } ca_descr_t; +</programlisting> + </section></section> +<section id="ca_function_calls"> +<title>CA Function Calls</title> + + +<section id="ca_fopen"> +<title>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para> +<para>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 CA Device in O_RDWR + mode. All other attempts to open the device in this mode will fail, and an error + code will be returned.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific video device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="ca_fclose"> +<title>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened audio device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section> +</section>
\ No newline at end of file diff --git a/dvb-spec/sgml/demux.sgml b/dvb-spec/sgml/demux.sgml new file mode 100644 index 000000000..ad3448219 --- /dev/null +++ b/dvb-spec/sgml/demux.sgml @@ -0,0 +1,973 @@ +<title>DVB Demux Device</title> + +<para>The DVB demux device controls the filters of the DVB hardware/software. It can be +accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be +accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application. +</para> +<section id="dmx_types"> +<title>Demux Data Types</title> + +<section id="dmx_output_t"> +<title>dmx_output_t</title> + <programlisting> + typedef enum + { + DMX_OUT_DECODER, + DMX_OUT_TAP, + DMX_OUT_TS_TAP + } dmx_output_t; +</programlisting> +<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is +called. +</para> +<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>, +which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was +specified. +</para> +</section> + +<section id="dmx_input_t"> +<title>dmx_input_t</title> + <programlisting> + typedef enum + { + DMX_IN_FRONTEND, + DMX_IN_DVR + } dmx_input_t; +</programlisting> +</section> + +<section id="dmx_pes_type_t"> +<title>dmx_pes_type_t</title> + <programlisting> + typedef enum + { + DMX_PES_AUDIO, + DMX_PES_VIDEO, + DMX_PES_TELETEXT, + DMX_PES_SUBTITLE, + DMX_PES_PCR, + DMX_PES_OTHER + } dmx_pes_type_t; +</programlisting> +</section> + +<section id="dmx_event_t"> +<title>dmx_event_t</title> + <programlisting> + typedef enum + { + DMX_SCRAMBLING_EV, + DMX_FRONTEND_EV + } dmx_event_t; +</programlisting> +</section> + +<section id="dmx_scrambling_status_t"> +<title>dmx_scrambling_status_t</title> + <programlisting> + typedef enum + { + DMX_SCRAMBLING_OFF, + DMX_SCRAMBLING_ON + } dmx_scrambling_status_t; +</programlisting> +</section> + +<section id="dmx_filter"> +<title>struct dmx_filter</title> + <programlisting> + typedef struct dmx_filter + { + uint8_t filter[DMX_FILTER_SIZE]; + uint8_t mask[DMX_FILTER_SIZE]; + } dmx_filter_t; +</programlisting> +</section> + +<section id="dmx_sct_filter_params"> +<title>struct dmx_sct_filter_params</title> + <programlisting> + struct dmx_sct_filter_params + { + uint16_t pid; + dmx_filter_t filter; + uint32_t timeout; + uint32_t flags; + #define DMX_CHECK_CRC 1 + #define DMX_ONESHOT 2 + #define DMX_IMMEDIATE_START 4 + }; +</programlisting> +</section> + +<section id="dmx_pes_filter_params"> +<title>struct dmx_pes_filter_params</title> + <programlisting> + struct dmx_pes_filter_params + { + uint16_t pid; + dmx_input_t input; + dmx_output_t output; + dmx_pes_type_t pes_type; + uint32_t flags; + }; +</programlisting> +</section> + +<section id="dmx_event"> +<title>struct dmx_event</title> + <programlisting> + struct dmx_event + { + dmx_event_t event; + time_t timeStamp; + union + { + dmx_scrambling_status_t scrambling; + } u; + }; +</programlisting> +</section> + +<section id="dmx_stc"> +<title>struct dmx_stc</title> + <programlisting> + struct dmx_stc { + unsigned int num; /⋆ input : which STC? 0..N ⋆/ + unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/ + uint64_t stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/ + }; +</programlisting> + </section> + +</section> + +<section id="dmx_fcalls"> +<title>Demux Function Calls</title> + +<section id="dmx_fopen"> +<title>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call, used with a device name of /dev/dvb/adapter0/demux0, + 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/dvb/adapter0/dvr0 + is a logical device to be used for retrieving Transport Streams for digital + video recording. When reading from this device a transport stream containing + the packets from all PES filters set in the corresponding demux device + (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A + recorded Transport Stream is replayed by writing to this device. </para> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of demux device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EMFILE</para> +</entry><entry + align="char"> +<para>“Too many open files”, i.e. no more filters available.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>The driver failed to allocate enough memory.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_fclose"> +<title>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call deactivates and deallocates a filter that was previously + allocated via the open() call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_fread"> +<title>read()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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 EOVERFLOW 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.</para> +</entry> + </row><row><entry + align="char"> +<para>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/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>size_t read(int fd, void ⋆buf, size_t count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer to be used for returned filtered data.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>No data to return and O_NONBLOCK was specified.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>ECRC</para> +</entry><entry + align="char"> +<para>Last section had a CRC error - no data returned. The + buffer is flushed.</para> +</entry> + </row><row><entry + align="char"> +<para>EOVERFLOW</para> +</entry><entry + align="char"> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>The filtered data was not read from the buffer in due + time, resulting in non-read data being lost. The buffer is + flushed.</para> +</entry> + </row><row><entry + align="char"> +<para>ETIMEDOUT</para> +</entry><entry + align="char"> +<para>The section was not loaded within the stated timeout + period. See ioctl DMX_SET_FILTER for how to set a + timeout.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>The driver failed to write to the callers buffer due to an + invalid *buf pointer.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_fwrite"> +<title>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, + associated with 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/dvb/adapter0/demux0. The amount of data to be transferred is + implied by count.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>ssize_t write(int fd, const void ⋆buf, size_t + count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer containing the Transport Stream.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>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).</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_start"> +<title>DMX_START</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call is used to start the actual filtering operation defined via the ioctl + calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_START);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_START for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument, i.e. no filtering parameters provided via + the DMX_SET_FILTER or DMX_SET_PES_FILTER + functions.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_stop"> +<title>DMX_STOP</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_STOP);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_STOP for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_set_filter"> +<title>DMX_SET_FILTER</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 canceled, and the receive buffer will be flushed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_SET_FILTER, + struct dmx_sct_filter_params ⋆params);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_FILTER for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dmx_sct_filter_params + *params</para> +</entry><entry + align="char"> +<para>Pointer to structure containing filter parameters.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_set_pes_filter"> +<title>DMX_SET_PES_FILTER</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER, + struct dmx_pes_filter_params ⋆params);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_PES_FILTER for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + dmx_pes_filter_params + *params</para> +</entry><entry + align="char"> +<para>Pointer to structure containing filter parameters.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dms_set_buffer_size"> +<title>DMX_SET_BUFFER_SIZE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = + DMX_SET_BUFFER_SIZE, unsigned long size);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_BUFFER_SIZE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned long size</para> +</entry><entry + align="char"> +<para>Size of circular buffer.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>The driver was not able to allocate a buffer of the + requested size.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_get_event"> +<title>DMX_GET_EVENT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_GET_EVENT, + struct dmx_event ⋆ev);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_GET_EVENT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct dmx_event *ev</para> +</entry><entry + align="char"> +<para>Pointer to the location where the event is to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ev points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>There is no event pending, and the device is in + non-blocking mode.</para> +</entry> + </row></tbody></tgroup></informaltable> +</section> + +<section id="dmx_get_stc"> +<title>DMX_GET_STC</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns the current value of the system time counter (which is driven + by a PES filter of type DMX_PES_PCR). Some hardware supports more than one + STC, so you must specify which one by setting the num field of stc before the ioctl + (range 0...n). The result is returned in form of a ratio with a 64 bit numerator + and a 32 bit denominator, so the real 90kHz STC value is stc->stc / + stc->base + .</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl( int fd, int request = DMX_GET_STC, struct + dmx_stc ⋆stc);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_GET_STC for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct dmx_stc *stc</para> +</entry><entry + align="char"> +<para>Pointer to the location where the stc is to be stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>stc points to an invalid address.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid stc number.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section>
\ No newline at end of file diff --git a/dvb-spec/sgml/dvbapi-complete.sgml b/dvb-spec/sgml/dvbapi-complete.sgml deleted file mode 100644 index 753efd3fe..000000000 --- a/dvb-spec/sgml/dvbapi-complete.sgml +++ /dev/null @@ -1,9503 +0,0 @@ -<!DOCTYPE article [<!ENTITY % docbook.dtd PUBLIC -"-//OASIS//DTD DocBook XML V4.2CR1//EN" -"http://www.oasis-open.org/docbook/xml/4.2CR1/docbookx.dtd"> -%docbook.dtd; -] > -<!--translated from dvbapi.tex, on 2009-09-06 01:50:00, -by TeX4ht (http://www.cse.ohio-state.edu/~gurari/TeX4ht/) xhtml,docbook,html,refcaption --> - <?xtpipes file="docbook.4xt" ?> - <article role="book"> -<para role="maketitle"> -<note role="title"> -<para><emphasis role="bf">LINUX DVB API Version 3</emphasis></para></note> - <note role="author"> -<para><personname><othername> <graphic width="34.12749pt" fileref="cimlogo.psi" ></graphic> - Copyright 2002, 2003 Convergence GmbH - Written by Dr. Ralph J.K. Metzler - <emphasis role="tt"><rjkm@metzlerbros.de></emphasis> - and Dr. Marcus O.C. Metzler - <emphasis role="tt"><mocm@metzlerbros.de></emphasis> - </othername></personname></para></note> -<note role="date"> -<para>24/07/2003 -V 1.0.0</para></note> -</para> -<para>Permission is granted to copy, distribute and/or modify this document under the terms of -the GNU Free Documentation License, Version 1.1 or any later version published by the Free -Software Foundation. A copy of the license is included in the chapter entitled ”GNU Free -Documentation License”. -</para> - - - -<section -role="likechapter"><title>Contents</title> - <toc><tocpart> - </tocpart></toc> - - - -<section -role="chapter"><title>Introduction</title> - <section -role="section"><title><abbrev role="title-mark">1.1</abbrev>What you need to know</title> -<para>The reader of this document is required to have some knowledge in the area of digital -video broadcasting (DVB) and should be familiar with part I of the MPEG2 specification -ISO/IEC 13818 (aka ITU-T H.222), i.e you should know what a program/transport -stream (PS/TS) is and what is meant by a packetized elementary stream (PES) or an -I-frame. -</para> -<para>Various DVB standards documents are available from <emphasis role="tt">http://www.dvb.org/</emphasis> and/or -<emphasis role="tt">http://www.etsi.org/</emphasis>. -</para> -<para>It is also necessary to know how to access unix/linux devices and how to use ioctl calls. -This also includes the knowledge of C or C++. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">1.2</abbrev>History</title> -<para>The first API for DVB cards we used at Convergence in late 1999 was an extension of the -Video4Linux API which was primarily developed for frame grabber cards. As such it -was not really well suited to be used for DVB cards and their new features like -recording MPEG streams and filtering several section and PES data streams at the same -time. -</para> -<para>In early 2000, we were approached by Nokia with a proposal for a new standard Linux -DVB API. As a commitment to the development of terminals based on open standards, Nokia -and Convergence made it available to all Linux developers and published it on -<emphasis role="tt">http://www.linuxtv.org/</emphasis> in September 2000. Convergence 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> - -</section><section -role="section"><title><abbrev role="title-mark">1.3</abbrev>Overview</title> - <figure><title/><blockquote> -<section role="center"><title/> -<para><graphic width="306.14374pt" fileref="dvbstb.ps" ></graphic> -<blockquote role="caption"><title role="caption">Figure 1.1</title> -<para>Components of a DVB card/STB</para></blockquote> -</para></section> - </blockquote></figure> -<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the following main -hardware components: -</para> -<itemizedlist> - <listitem> -<para>Frontend consisting of tuner and DVB demodulator -</para> -<para>Here the raw signal reaches the DVB hardware from a satellite dish or antenna - or directly from cable. The frontend down-converts and demodulates this signal - into an MPEG transport stream (TS). In case of a satellite frontend, this includes - a facility for satellite equipment control (SEC), which allows control of LNB - polarization, multi feed switches or dish rotors. -</para> -</listitem> - <listitem> -<para>Conditional Access (CA) hardware like CI adapters and smartcard slots -</para> -<para>The complete TS is passed through the CA hardware. Programs to which the user - has access (controlled by the smart card) are decoded in real time and re-inserted - into the TS. -</para> -</listitem> - <listitem> -<para>Demultiplexer which filters the incoming DVB stream -</para> -<para>The demultiplexer splits the TS into its components like audio and video streams. - Besides usually several of such audio and video streams it also contains data - streams with information about the programs offered in this or other streams of - the same provider. -</para> -</listitem> - <listitem> -<para>MPEG2 audio and video decoder -</para> -<para>The main targets of the demultiplexer are the MPEG2 audio and video decoders. - After decoding they pass on the uncompressed audio and video to the computer - screen or (through a PAL/NTSC encoder) to a TV set.</para></listitem></itemizedlist> -<para>Figure ?? shows a crude schematic of the control and data flow between those -components. -</para> -<para>On a DVB PCI card not all of these have to be present since some functionality can be -provided by the main CPU of the PC (e.g. MPEG picture and sound decoding) or is not -needed (e.g. for data-only uses like “internet over satellite”). Also not every card or STB -provides conditional access hardware. -</para> -</section><section -role="section"><title><abbrev role="title-mark">1.4</abbrev>Linux DVB Devices</title> -<para>The Linux DVB API lets you control these hardware components through currently six -Unix-style character devices for video, audio, frontend, demux, CA and IP-over-DVB -networking. The video and audio devices control the MPEG2 decoder hardware, the frontend -device the tuner and the DVB demodulator. The demux device gives you control over the PES -and section filters of the hardware. If the hardware does not support filtering these filters can -be implemented in software. Finally, the CA device controls all the conditional access -capabilities of the hardware. It can depend on the individual security requirements of the -platform, if and how many of the CA functions are made available to the application through -this device. -</para> -<para>All devices can be found in the <emphasis role="tt">/dev</emphasis> tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices are -called -</para> -<itemizedlist> - <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>, -</para> -</listitem> - <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>, -</para> -</listitem> - <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>, -</para> -</listitem> - <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>, -</para> -</listitem> - <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>, -</para> -</listitem> - <listitem> -<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist> -<para>where N enumerates the DVB PCI cards in a system starting from 0, and M enumerates the -devices of each type within each adapter, starting from 0, too. We will omit the -“<emphasis role="tt">/dev/dvb/adapterN/</emphasis>” in the further dicussion of these devices. The naming scheme -for the devices is the same wheter devfs is used or not. -</para> -<para>More details about the data structures and function calls of all the devices are described in -the following chapters. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">1.5</abbrev>API include files</title> -<para>For each of the DVB devices a corresponding include file exists. The DVB API include -files should be included in application sources with a partial path like: -</para> -<programlisting> - #include <linux/dvb/frontend.h> -</programlisting> -<para>To enable applications to support different API version, an additional include file -<emphasis role="tt">linux/dvb/version.h</emphasis> exists, which defines the constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This -document describes <emphasis role="tt">DVB_API_VERSION 3</emphasis>. -</para> - -</section></section><section -role="chapter"><title>DVB Frontend API</title> -<para>The DVB frontend device controls the tuner and DVB demodulator hardware. It can be -accessed through <emphasis role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and ioctl -definitions can be accessed by including <emphasis role="tt">linux/dvb/frontend.h</emphasis> in your -application. -</para> -<para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) and DVB-T -(terrestrial). Transmission via the internet (DVB-IP) is not yet handled by this API but a -future extension is possible. For DVB-S the frontend device also supports satellite equipment -control (SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification is -available from Eutelsat <emphasis role="tt">http://www.eutelsat.org/</emphasis>. -</para> -<para>Note that the DVB API may also be used for MPEG decoder-only PCI cards, in which -case there exists no frontend device. -</para> -<section -role="section"><title><abbrev role="title-mark">2.1</abbrev>Frontend Data Types</title> - -<section -role="subsection"><title><abbrev role="title-mark">2.1.1</abbrev>frontend type</title> -<para>For historical reasons frontend types are named after the type of modulation used in -transmission. -</para> -<programlisting> - typedef enum fe_type { - FE_QPSK, /⋆ DVB-S ⋆/ - FE_QAM, /⋆ DVB-C ⋆/ - FE_OFDM /⋆ DVB-T ⋆/ - } fe_type_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.2</abbrev>frontend capabilities</title> -<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for -a specific frontend type. -</para> -<programlisting> - typedef enum fe_caps { - FE_IS_STUPID = 0, - FE_CAN_INVERSION_AUTO = 0x1, - FE_CAN_FEC_1_2 = 0x2, - FE_CAN_FEC_2_3 = 0x4, - FE_CAN_FEC_3_4 = 0x8, - FE_CAN_FEC_4_5 = 0x10, - FE_CAN_FEC_5_6 = 0x20, - FE_CAN_FEC_6_7 = 0x40, - FE_CAN_FEC_7_8 = 0x80, - FE_CAN_FEC_8_9 = 0x100, - FE_CAN_FEC_AUTO = 0x200, - FE_CAN_QPSK = 0x400, - FE_CAN_QAM_16 = 0x800, - FE_CAN_QAM_32 = 0x1000, - FE_CAN_QAM_64 = 0x2000, - FE_CAN_QAM_128 = 0x4000, - FE_CAN_QAM_256 = 0x8000, - FE_CAN_QAM_AUTO = 0x10000, - FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, - FE_CAN_BANDWIDTH_AUTO = 0x40000, - FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, - FE_CAN_HIERARCHY_AUTO = 0x100000, - FE_CAN_MUTE_TS = 0x80000000, - FE_CAN_CLEAN_SETUP = 0x40000000 - } fe_caps_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.3</abbrev>frontend information</title> -<para>Information about the frontend ca be queried with FE_GET_INFO (??). -</para> -<programlisting> - struct dvb_frontend_info { - char name[128]; - fe_type_t type; - uint32_t frequency_min; - uint32_t frequency_max; - uint32_t frequency_stepsize; - uint32_t frequency_tolerance; - uint32_t symbol_rate_min; - uint32_t symbol_rate_max; - uint32_t symbol_rate_tolerance; /⋆ ppm ⋆/ - uint32_t notifier_delay; /⋆ ms ⋆/ - fe_caps_t caps; - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.4</abbrev>diseqc master command</title> -<para>A message sent from the frontend to DiSEqC capable equipment. -</para> -<programlisting> - struct dvb_diseqc_master_cmd { - uint8_t msg [6]; /⋆ { framing, address, command, data[3] } ⋆/ - uint8_t msg_len; /⋆ valid values are 3...6 ⋆/ - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.5</abbrev>diseqc slave reply</title> -<para>A reply to the frontend from DiSEqC 2.0 capable equipment. -</para> -<programlisting> - struct dvb_diseqc_slave_reply { - uint8_t msg [4]; /⋆ { framing, data [3] } ⋆/ - uint8_t msg_len; /⋆ valid values are 0...4, 0 means no msg ⋆/ - int timeout; /⋆ return from ioctl after timeout ms with ⋆/ - }; /⋆ errorcode when no message was received ⋆/ -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.6</abbrev>SEC voltage</title> -<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation -(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched -consistently to the DiSEqC commands as described in the DiSEqC spec. -</para> -<programlisting> - typedef enum fe_sec_voltage { - SEC_VOLTAGE_13, - SEC_VOLTAGE_18 - } fe_sec_voltage_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.7</abbrev>SEC continuous tone</title> -<para>The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the -high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to -be switched consistently to the DiSEqC commands as described in the DiSEqC -spec. -</para> -<programlisting> - typedef enum fe_sec_tone_mode { - SEC_TONE_ON, - SEC_TONE_OFF - } fe_sec_tone_mode_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.8</abbrev>SEC tone burst</title> -<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select -between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to -be switched consistently to the DiSEqC commands as described in the DiSEqC -spec. -</para> -<programlisting> - typedef enum fe_sec_mini_cmd { - SEC_MINI_A, - SEC_MINI_B - } fe_sec_mini_cmd_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.9</abbrev>frontend status</title> -<para>Several functions of the frontend device use the fe_status data type defined -by -</para> -<programlisting> - typedef enum fe_status { - FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ - FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ - FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ - FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ - FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ - FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ - FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ - } fe_status_t; /⋆ application is recommned to reset ⋆/ -</programlisting> -<para>to indicate the current state and/or state changes of the frontend hardware. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.10</abbrev>frontend parameters</title> -<para>The kind of parameters passed to the frontend device for tuning depend on the kind of -hardware you are using. All kinds of parameters are combined as a union in the -FrontendParameters structure: -</para> -<programlisting> - struct dvb_frontend_parameters { - uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ - /⋆ intermediate frequency in kHz for QPSK ⋆/ - fe_spectral_inversion_t inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - } u; - }; -</programlisting> -<para>For satellite QPSK frontends you have to use the <remark role="obeylines-h">QPSKParameters</remark> member defined -by -</para> -<programlisting> - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ - }; -</programlisting> -<para>for cable QAM frontend you use the <remark role="obeylines-h">QAMParameters</remark> structure -</para> -<programlisting> - struct dvb_qam_parameters { - uint32_t symbol_rate; /⋆ symbol rate in Symbols per second ⋆/ - fe_code_rate_t fec_inner; /⋆ forward error correction (see above) ⋆/ - fe_modulation_t modulation; /⋆ modulation type (see above) ⋆/ - }; -</programlisting> -<para>DVB-T frontends are supported by the <remark role="obeylines-h">OFDMParamters</remark> structure -</para> -<programlisting> - struct dvb_ofdm_parameters { - fe_bandwidth_t bandwidth; - fe_code_rate_t code_rate_HP; /⋆ high priority stream code rate ⋆/ - fe_code_rate_t code_rate_LP; /⋆ low priority stream code rate ⋆/ - fe_modulation_t constellation; /⋆ modulation type (see above) ⋆/ - fe_transmit_mode_t transmission_mode; - fe_guard_interval_t guard_interval; - fe_hierarchy_t hierarchy_information; - }; -</programlisting> -<para>In the case of QPSK frontends the <remark role="obeylines-h">Frequency</remark> field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of -the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and -OFDM frontends the Frequency specifies the absolute frequency and is given in -Hz. -</para> -<para>The Inversion field can take one of these values: -</para> -<programlisting> - typedef enum fe_spectral_inversion { - INVERSION_OFF, - INVERSION_ON, - INVERSION_AUTO - } fe_spectral_inversion_t; -</programlisting> -<para>It indicates if spectral inversion should be presumed or not. In the automatic setting -(<remark role="obeylines-h">INVERSION_AUTO</remark>) the hardware will try to figure out the correct setting by -itself. -</para> -<para>The possible values for the <remark role="obeylines-h">FEC_inner</remark> field are -</para> -<programlisting> - typedef enum fe_code_rate { - FEC_NONE = 0, - FEC_1_2, - FEC_2_3, - FEC_3_4, - FEC_4_5, - FEC_5_6, - FEC_6_7, - FEC_7_8, - FEC_8_9, - FEC_AUTO - } fe_code_rate_t; -</programlisting> -<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto -detection. -</para> -<para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature -modulation mode which can be one of the following: -</para> -<programlisting> - typedef enum fe_modulation { - QPSK, - QAM_16, - QAM_32, - QAM_64, - QAM_128, - QAM_256, - QAM_AUTO - } fe_modulation_t; -</programlisting> -<para>Finally, there are several more parameters for OFDM: -</para> -<programlisting> - typedef enum fe_transmit_mode { - TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K, - TRANSMISSION_MODE_AUTO - } fe_transmit_mode_t; -</programlisting> - <programlisting> - typedef enum fe_bandwidth { - BANDWIDTH_8_MHZ, - BANDWIDTH_7_MHZ, - BANDWIDTH_6_MHZ, - BANDWIDTH_AUTO - } fe_bandwidth_t; -</programlisting> - <programlisting> - typedef enum fe_guard_interval { - GUARD_INTERVAL_1_32, - GUARD_INTERVAL_1_16, - GUARD_INTERVAL_1_8, - GUARD_INTERVAL_1_4, - GUARD_INTERVAL_AUTO - } fe_guard_interval_t; -</programlisting> - <programlisting> - typedef enum fe_hierarchy { - HIERARCHY_NONE, - HIERARCHY_1, - HIERARCHY_2, - HIERARCHY_4, - HIERARCHY_AUTO - } fe_hierarchy_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.1.11</abbrev>frontend events</title> - <programlisting> - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; -</programlisting> - </section></section><section -role="section"><title><abbrev role="title-mark">2.2</abbrev>Frontend Function Calls</title> - -<section -role="subsection"><title><abbrev role="title-mark">2.2.1</abbrev>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) - for subsequent use. Usually the first thing to do after a successful open is to - find out the frontend type with FE_GET_INFO. -<para>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.) -</para> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -</para> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific video device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.2</abbrev>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened front-end device. After closing - a front-end device, its corresponding hardware might be powered down - automatically.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.3</abbrev>FE_READ_STATUS<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns status information about the front-end. This call only - requires read-only access to the device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_READ_STATUS, - fe_status_t ⋆status);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_READ_STATUS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct fe_status_t - *status</para> -</entry><entry - align="char"> -<para>Points to the location where the front-end status word is - to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>status points to invalid address.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.4</abbrev>FE_READ_BER<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_READ_BER, - uint32_t ⋆ber);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_READ_BER for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint32_t *ber</para> -</entry><entry - align="char"> -<para>The bit error rate is stored into *ber.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>ber points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSIGNAL</para> -</entry><entry - align="char"> -<para>There is no signal, thus no meaningful bit error rate. Also - returned if the front-end is not turned on.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSYS</para> -</entry><entry - align="char"> -<para>Function not available for this device.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.5</abbrev>FE_READ_SNR<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_READ_SNR, int16_t - ⋆snr);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_READ_SNR for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int16_t *snr</para> -</entry><entry - align="char"> -<para>The signal-to-noise ratio is stored into *snr.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>snr points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSIGNAL</para> -</entry><entry - align="char"> -<para>There is no signal, thus no meaningful signal strength - value. Also returned if front-end is not turned on.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSYS</para> -</entry><entry - align="char"> -<para>Function not available for this device.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.6</abbrev>FE_READ_SIGNAL_STRENGTH<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = - FE_READ_SIGNAL_STRENGTH, int16_t ⋆strength);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_READ_SIGNAL_STRENGTH for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>int16_t *strength</para> -</entry><entry - align="char"> -<para>The signal strength value is stored into *strength.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>status points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSIGNAL</para> -</entry><entry - align="char"> -<para>There is no signal, thus no meaningful signal strength - value. Also returned if front-end is not turned on.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSYS</para> -</entry><entry - align="char"> -<para>Function not available for this device.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.7</abbrev>FE_READ_UNCORRECTED_BLOCKS<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the number of uncorrected blocks detected by the device - driver during its lifetime. For meaningful measurements, the increment in block - count during a specific time interval should be calculated. For this command, - read-only access to the device is sufficient.</para> -</entry> - </row><row><entry - align="char"> -<para>Note that the counter will wrap to zero after its maximum count has been - reached.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = - FE_READ_UNCORRECTED_BLOCKS, uint32_t ⋆ublocks);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_READ_UNCORRECTED_BLOCKS for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>uint32_t *ublocks</para> -</entry><entry - align="char"> -<para>The total number of uncorrected blocks seen by the driver - so far.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>ublocks points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOSYS</para> -</entry><entry - align="char"> -<para>Function not available for this device.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.8</abbrev>FE_SET_FRONTEND<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call starts a tuning operation using specified parameters. The result - of this call will be successful if the parameters were valid and the tuning could - be initiated. The result of the tuning operation in itself, however, will arrive - asynchronously as an event (see documentation for FE_GET_EVENT and - FrontendEvent.) If a new FE_SET_FRONTEND operation is initiated before - the previous one was completed, the previous operation will be aborted in favor - of the new one. This command requires read/write access to the device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_SET_FRONTEND, - struct dvb_frontend_parameters ⋆p);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_SET_FRONTEND for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_parameters - *p</para> -</entry><entry - align="char"> -<para>Points to parameters for tuning operation.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>p points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Maximum supported symbol rate reached.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.9</abbrev>FE_GET_FRONTEND<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call queries the currently effective frontend parameters. For this - command, read-only access to the device is sufficient.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_GET_FRONTEND, - struct dvb_frontend_parameters ⋆p);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_SET_FRONTEND for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_parameters - *p</para> -</entry><entry - align="char"> -<para>Points to parameters for tuning operation.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>p points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Maximum supported symbol rate reached.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.10</abbrev>FE_GET_EVENT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns a frontend event if available. If an event is not - available, the behavior depends on whether the device is in blocking or - non-blocking mode. In the latter case, the call fails immediately with errno - set to EWOULDBLOCK. In the former case, the call blocks until an event - becomes available.</para> -</entry> - </row><row><entry - align="char"> -<para>The standard Linux poll() and/or select() system calls can be used with the - device file descriptor to watch for new events. For select(), the file descriptor - should be included in the exceptfds argument, and for poll(), POLLPRI should - be specified as the wake-up condition. Since the event queue allocated is - rather small (room for 8 events), the queue must be serviced regularly to avoid - overflow. If an overflow happens, the oldest event is discarded from the queue, - and an error (EOVERFLOW) occurs the next time the queue is read. After - reporting the error condition in this fashion, subsequent FE_GET_EVENT - calls will return events from the queue as usual.</para> -</entry> - </row><row><entry - align="char"> -<para>For the sake of implementation simplicity, this command requires read/write - access to the device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = QPSK_GET_EVENT, - struct dvb_frontend_event ⋆ev);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_GET_EVENT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_event - *ev</para> -</entry><entry - align="char"> -<para>Points to the location where the event,</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>if any, is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>ev points to invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>Overflow in event queue - one or more events were lost.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.11</abbrev>FE_GET_INFO<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns information about the front-end. This call only requires - read-only access to the device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(int fd, int request = FE_GET_INFO, struct - dvb_frontend_info ⋆info);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_GET_INFO for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_frontend_info - *info</para> -</entry><entry - align="char"> -<para>Points to the location where the front-end information is - to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>info points to invalid address.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.12</abbrev>FE_DISEQC_RESET_OVERLOAD<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>If the bus has been automatically powered off due to power overload, this ioctl - call restores the power to the bus. The call requires read/write access to the - device. This call has no effect if the device is manually powered off. Not all - DVB adapters support this ioctl.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - FE_DISEQC_RESET_OVERLOAD);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_DISEQC_RESET_OVERLOAD for this - command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Permission denied (needs read/write access).</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.13</abbrev>FE_DISEQC_SEND_MASTER_CMD<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to send a a DiSEqC command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - FE_DISEQC_SEND_MASTER_CMD, struct - dvb_diseqc_master_cmd ⋆cmd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_DISEQC_SEND_MASTER_CMD for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_diseqc_master_cmd - *cmd</para> -</entry><entry - align="char"> -<para>Pointer to the command to be transmitted.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>Seq points to an invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>The data structure referred to by seq is invalid in some - way.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Permission denied (needs read/write access).</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.14</abbrev>FE_DISEQC_RECV_SLAVE_REPLY<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - FE_DISEQC_RECV_SLAVE_REPLY, struct - dvb_diseqc_slave_reply ⋆reply);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_DISEQC_RECV_SLAVE_REPLY for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dvb_diseqc_slave_reply - *reply</para> -</entry><entry - align="char"> -<para>Pointer to the command to be received.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>Seq points to an invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>The data structure referred to by seq is invalid in some - way.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Permission denied (needs read/write access).</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.15</abbrev>FE_DISEQC_SEND_BURST<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to send a 22KHz tone burst.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - FE_DISEQC_SEND_BURST, fe_sec_mini_cmd_t burst);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_DISEQC_SEND_BURST for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>fe_sec_mini_cmd_t - burst</para> -</entry><entry - align="char"> -<para>burst A or B.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>Seq points to an invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>The data structure referred to by seq is invalid in some - way.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Permission denied (needs read/write access).</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.16</abbrev>FE_SET_TONE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This call is used to set the generation of the continuous 22kHz tone. This call - requires read/write permissions.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_SET_TONE, - fe_sec_tone_mode_t tone);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_SET_TONE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>fe_sec_tone_mode_t - tone</para> -</entry><entry - align="char"> -<para>The requested tone generation mode (on/off).</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>File not opened with read permissions.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.17</abbrev>FE_SET_VOLTAGE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This call is used to set the bus voltage. This call requires read/write - permissions.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = FE_SET_VOLTAGE, - fe_sec_voltage_t voltage);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_SET_VOLTAGE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>fe_sec_voltage_t - voltage</para> -</entry><entry - align="char"> -<para>The requested bus voltage.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>File not opened with read permissions.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">2.2.18</abbrev>FE_ENABLE_HIGH_LNB_VOLTAGE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate - for long cables). This call requires read/write permissions. Not all DVB - adapters support this ioctl.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - FE_ENABLE_HIGH_LNB_VOLTAGE, int high);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals FE_SET_VOLTAGE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int high</para> -</entry><entry - align="char"> -<para>The requested bus voltage.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>File not opened with read permissions.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error in the device driver.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section></section></section><section -role="chapter"><title>DVB Demux Device</title> -<para>The DVB demux device controls the filters of the DVB hardware/software. It can be -accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be -accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application. -</para> -<section -role="section"><title><abbrev role="title-mark">3.1</abbrev>Demux Data Types</title> - -<section -role="subsection"><title><abbrev role="title-mark">3.1.1</abbrev>dmx_output_t</title> - <programlisting> - typedef enum - { - DMX_OUT_DECODER, - DMX_OUT_TAP, - DMX_OUT_TS_TAP - } dmx_output_t; -</programlisting> -<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is -called. -</para> -<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>, -which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was -specified. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.2</abbrev>dmx_input_t</title> - <programlisting> - typedef enum - { - DMX_IN_FRONTEND, - DMX_IN_DVR - } dmx_input_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.3</abbrev>dmx_pes_type_t</title> - <programlisting> - typedef enum - { - DMX_PES_AUDIO, - DMX_PES_VIDEO, - DMX_PES_TELETEXT, - DMX_PES_SUBTITLE, - DMX_PES_PCR, - DMX_PES_OTHER - } dmx_pes_type_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.4</abbrev>dmx_event_t</title> - <programlisting> - typedef enum - { - DMX_SCRAMBLING_EV, - DMX_FRONTEND_EV - } dmx_event_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.5</abbrev>dmx_scrambling_status_t</title> - <programlisting> - typedef enum - { - DMX_SCRAMBLING_OFF, - DMX_SCRAMBLING_ON - } dmx_scrambling_status_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.6</abbrev>struct dmx_filter</title> - <programlisting> - typedef struct dmx_filter - { - uint8_t filter[DMX_FILTER_SIZE]; - uint8_t mask[DMX_FILTER_SIZE]; - } dmx_filter_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.7</abbrev>struct dmx_sct_filter_params</title> - <programlisting> - struct dmx_sct_filter_params - { - uint16_t pid; - dmx_filter_t filter; - uint32_t timeout; - uint32_t flags; - #define DMX_CHECK_CRC 1 - #define DMX_ONESHOT 2 - #define DMX_IMMEDIATE_START 4 - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.8</abbrev>struct dmx_pes_filter_params</title> - <programlisting> - struct dmx_pes_filter_params - { - uint16_t pid; - dmx_input_t input; - dmx_output_t output; - dmx_pes_type_t pes_type; - uint32_t flags; - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.9</abbrev>struct dmx_event</title> - <programlisting> - struct dmx_event - { - dmx_event_t event; - time_t timeStamp; - union - { - dmx_scrambling_status_t scrambling; - } u; - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.1.10</abbrev>struct dmx_stc</title> - <programlisting> - struct dmx_stc { - unsigned int num; /⋆ input : which STC? 0..N ⋆/ - unsigned int base; /⋆ output: divisor for stc to get 90 kHz clock ⋆/ - uint64_t stc; /⋆ output: stc in 'base'⋆90 kHz units ⋆/ - }; -</programlisting> - </section></section><section -role="section"><title><abbrev role="title-mark">3.2</abbrev>Demux Function Calls</title> - -<section -role="subsection"><title><abbrev role="title-mark">3.2.1</abbrev>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call, used with a device name of /dev/dvb/adapter0/demux0, - 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/dvb/adapter0/dvr0 - is a logical device to be used for retrieving Transport Streams for digital - video recording. When reading from this device a transport stream containing - the packets from all PES filters set in the corresponding demux device - (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A - recorded Transport Stream is replayed by writing to this device. -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -</para> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of demux device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row><row><entry - align="char"> -<para>EMFILE</para> -</entry><entry - align="char"> -<para>“Too many open files”, i.e. no more filters available.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>The driver failed to allocate enough memory.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.2</abbrev>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call deactivates and deallocates a filter that was previously - allocated via the open() call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.3</abbrev>read()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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 EOVERFLOW 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.</para> -</entry> - </row><row><entry - align="char"> -<para>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/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>size_t read(int fd, void ⋆buf, size_t count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer to be used for returned filtered data.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>No data to return and O_NONBLOCK was specified.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>ECRC</para> -</entry><entry - align="char"> -<para>Last section had a CRC error - no data returned. The - buffer is flushed.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>The filtered data was not read from the buffer in due - time, resulting in non-read data being lost. The buffer is - flushed.</para> -</entry> - </row><row><entry - align="char"> -<para>ETIMEDOUT</para> -</entry><entry - align="char"> -<para>The section was not loaded within the stated timeout - period. See ioctl DMX_SET_FILTER for how to set a - timeout.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>The driver failed to write to the callers buffer due to an - invalid *buf pointer.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.4</abbrev>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, - associated with 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/dvb/adapter0/demux0. The amount of data to be transferred is - implied by count.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>ssize_t write(int fd, const void ⋆buf, size_t - count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer containing the Transport Stream.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>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).</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.5</abbrev>DMX_START<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call is used to start the actual filtering operation defined via the ioctl - calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_START);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_START for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument, i.e. no filtering parameters provided via - the DMX_SET_FILTER or DMX_SET_PES_FILTER - functions.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.6</abbrev>DMX_STOP<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_STOP);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_STOP for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.7</abbrev>DMX_SET_FILTER<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 canceled, and the receive buffer will be flushed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_SET_FILTER, - struct dmx_sct_filter_params ⋆params);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_FILTER for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dmx_sct_filter_params - *params</para> -</entry><entry - align="char"> -<para>Pointer to structure containing filter parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.8</abbrev>DMX_SET_PES_FILTER<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER, - struct dmx_pes_filter_params ⋆params);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_PES_FILTER for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - dmx_pes_filter_params - *params</para> -</entry><entry - align="char"> -<para>Pointer to structure containing filter parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.9</abbrev>DMX_SET_BUFFER_SIZE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = - DMX_SET_BUFFER_SIZE, unsigned long size);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_SET_BUFFER_SIZE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned long size</para> -</entry><entry - align="char"> -<para>Size of circular buffer.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>The driver was not able to allocate a buffer of the - requested size.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.10</abbrev>DMX_GET_EVENT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_GET_EVENT, - struct dmx_event ⋆ev);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_GET_EVENT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dmx_event *ev</para> -</entry><entry - align="char"> -<para>Pointer to the location where the event is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>ev points to an invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">3.2.11</abbrev>DMX_GET_STC<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns the current value of the system time counter (which is driven - by a PES filter of type DMX_PES_PCR). Some hardware supports more than one - STC, so you must specify which one by setting the num field of stc before the ioctl - (range 0...n). The result is returned in form of a ratio with a 64 bit numerator - and a 32 bit denominator, so the real 90kHz STC value is stc->stc / - stc->base - .</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl( int fd, int request = DMX_GET_STC, struct - dmx_stc ⋆stc);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals DMX_GET_STC for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct dmx_stc *stc</para> -</entry><entry - align="char"> -<para>Pointer to the location where the stc is to be stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>stc points to an invalid address.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid stc number.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section></section><section -role="chapter"><title>DVB Video Device</title> -<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It -can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and -ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your -application. -</para> -<para>Note that the DVB video device only controls decoding of the MPEG video stream, not -its presentation on the TV or computer screen. On PCs this is typically handled by an -associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output -windows. -</para> -<para>Some DVB cards don’t have their own MPEG decoder, which results in the omission of -the audio and video device as well as the video4linux device. -</para> -<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only -supported on some MPEG decoders made for DVD playback. -</para> -<section -role="section"><title><abbrev role="title-mark">4.1</abbrev>Video Data Types</title> - -<section -role="subsection"><title><abbrev role="title-mark">4.1.1</abbrev>video_format_t</title> -<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by -</para> -<programlisting> - typedef enum { - VIDEO_FORMAT_4_3, - VIDEO_FORMAT_16_9 - } video_format_t; -</programlisting> -<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio -the output hardware (e.g. TV) has. It is also used in the data structures video_status -(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by -VIDEO_GET_EVENT (??) which report about the display format of the current video -stream. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.2</abbrev>video_display_format_t</title> -<para>In case the display format of the video stream and of the display hardware differ the -application has to specify how to handle the cropping of the picture. This can be done using -the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts -</para> -<programlisting> - typedef enum { - VIDEO_PAN_SCAN, - VIDEO_LETTER_BOX, - VIDEO_CENTER_CUT_OUT - } video_display_format_t; -</programlisting> -<para>as argument. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.3</abbrev>video stream source</title> -<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take -the following values, depending on whether we are replaying from an internal (demuxer) or -external (user write) source. -</para> -<programlisting> - typedef enum { - VIDEO_SOURCE_DEMUX, - VIDEO_SOURCE_MEMORY - } video_stream_source_t; -</programlisting> -<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the -DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY -is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system -call. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.4</abbrev>video play state</title> -<para>The following values can be returned by the VIDEO_GET_STATUS call representing the -state of video playback. -</para> -<programlisting> - typedef enum { - VIDEO_STOPPED, - VIDEO_PLAYING, - VIDEO_FREEZED - } video_play_state_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.5</abbrev>struct video_event</title> -<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT -call. -</para> -<programlisting> - struct video_event { - int32_t type; - time_t timestamp; - union { - video_format_t video_format; - } u; - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.6</abbrev>struct video_status</title> -<para>The VIDEO_GET_STATUS call returns the following structure informing about various -states of the playback operation. -</para> -<programlisting> - struct video_status { - boolean video_blank; - video_play_state_t play_state; - video_stream_source_t stream_source; - video_format_t video_format; - video_displayformat_t display_format; - }; -</programlisting> -<para>If video_blank is set video will be blanked out if the channel is changed or if playback is -stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is -currently frozen, stopped, or being played back. The stream_source corresponds to the seleted -source for the video stream. It can come either from the demultiplexer or from memory. -The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently -played video stream. Finally, display_format corresponds to the selected cropping -mode in case the source video format is not the same as the format of the output -device. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.7</abbrev>struct video_still_picture</title> -<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the -following structure. -</para> -<programlisting> - /⋆ pointer to and size of a single iframe in memory ⋆/ - struct video_still_picture { - char ⋆iFrame; - int32_t size; - }; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.8</abbrev>video capabilities</title> -<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following -bits set according to the hardwares capabilities. -</para> -<programlisting> - /⋆ bit definitions for capabilities: ⋆/ - /⋆ can the hardware decode MPEG1 and/or MPEG2? ⋆/ - #define VIDEO_CAP_MPEG1 1 - #define VIDEO_CAP_MPEG2 2 - /⋆ can you send a system and/or program stream to video device? - (you still have to open the video and the audio device but only - send the stream to the video device) ⋆/ - #define VIDEO_CAP_SYS 4 - #define VIDEO_CAP_PROG 8 - /⋆ can the driver also handle SPU, NAVI and CSS encoded data? - (CSS API is not present yet) ⋆/ - #define VIDEO_CAP_SPU 16 - #define VIDEO_CAP_NAVI 32 - #define VIDEO_CAP_CSS 64 -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.9</abbrev>video system</title> -<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The -following system types can be set: -</para> -<programlisting> - typedef enum { - VIDEO_SYSTEM_PAL, - VIDEO_SYSTEM_NTSC, - VIDEO_SYSTEM_PALN, - VIDEO_SYSTEM_PALNc, - VIDEO_SYSTEM_PALM, - VIDEO_SYSTEM_NTSC60, - VIDEO_SYSTEM_PAL60, - VIDEO_SYSTEM_PALM60 - } video_system_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.10</abbrev>struct video_highlight</title> -<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The -call expects the following format for that information: -</para> -<programlisting> - typedef - struct video_highlight { - boolean active; /⋆ 1=show highlight, 0=hide highlight ⋆/ - uint8_t contrast1; /⋆ 7- 4 Pattern pixel contrast ⋆/ - /⋆ 3- 0 Background pixel contrast ⋆/ - uint8_t contrast2; /⋆ 7- 4 Emphasis pixel-2 contrast ⋆/ - /⋆ 3- 0 Emphasis pixel-1 contrast ⋆/ - uint8_t color1; /⋆ 7- 4 Pattern pixel color ⋆/ - /⋆ 3- 0 Background pixel color ⋆/ - uint8_t color2; /⋆ 7- 4 Emphasis pixel-2 color ⋆/ - /⋆ 3- 0 Emphasis pixel-1 color ⋆/ - uint32_t ypos; /⋆ 23-22 auto action mode ⋆/ - /⋆ 21-12 start y ⋆/ - /⋆ 9- 0 end y ⋆/ - uint32_t xpos; /⋆ 23-22 button color number ⋆/ - /⋆ 21-12 start x ⋆/ - /⋆ 9- 0 end x ⋆/ - } video_highlight_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.11</abbrev>video SPU</title> -<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the -following format: -</para> -<programlisting> - typedef - struct video_spu { - boolean active; - int stream_id; - } video_spu_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.12</abbrev>video SPU palette</title> -<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: -</para> -<programlisting> - typedef - struct video_spu_palette{ - int length; - uint8_t ⋆palette; - } video_spu_palette_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.13</abbrev>video NAVI pack</title> -<para>In order to get the navigational data the following structure has to be passed to the ioctl -VIDEO_GET_NAVI: -</para> -<programlisting> - typedef - struct video_navi_pack{ - int length; /⋆ 0 ... 1024 ⋆/ - uint8_t data[1024]; - } video_navi_pack_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.1.14</abbrev>video attributes</title> -<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: -</para> -<programlisting> - typedef uint16_t video_attributes_t; - /⋆ bits: descr. ⋆/ - /⋆ 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) ⋆/ - /⋆ 13-12 TV system (0=525/60, 1=625/50) ⋆/ - /⋆ 11-10 Aspect ratio (0=4:3, 3=16:9) ⋆/ - /⋆ 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca ⋆/ - /⋆ 7 line 21-1 data present in GOP (1=yes, 0=no) ⋆/ - /⋆ 6 line 21-2 data present in GOP (1=yes, 0=no) ⋆/ - /⋆ 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 ⋆/ - /⋆ 2 source letterboxed (1=yes, 0=no) ⋆/ - /⋆ 0 film/camera mode (0=camera, 1=film (625/50 only)) ⋆/ -</programlisting> - </section></section><section -role="section"><title><abbrev role="title-mark">4.2</abbrev>Video Function Calls</title> - -<section -role="subsection"><title><abbrev role="title-mark">4.2.1</abbrev>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) - for subsequent use. -<para>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 attempts to open the device in this mode will fail, and an - error-code 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.</para> -</entry> - </row></tbody></tgroup></informaltable> -</para> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific video device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.2</abbrev>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened video device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.3</abbrev>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected - in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in - PES format, unless the capability allows other formats. 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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>size_t write(int fd, const void ⋆buf, size_t count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer containing the PES data.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>Attempted to write more data than the internal buffer can - hold.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.4</abbrev>VIDEO_STOP<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_STOP, boolean - mode);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_STOP for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>Boolean mode</para> -</entry><entry - align="char"> -<para>Indicates how the screen shall be handled.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE: Blank screen when stop.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE: Show last decoded frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.5</abbrev>VIDEO_PLAY<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to start playing a video stream from the - selected source.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_PLAY);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_PLAY for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.6</abbrev>VIDEO_FREEZE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 the 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_CONTINUE or VIDEO_PLAY is performed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_FREEZE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_FREEZE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.7</abbrev>VIDEO_CONTINUE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call restarts decoding and playing processes of the video stream - which was played before a call to VIDEO_FREEZE was made.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_CONTINUE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.8</abbrev>VIDEO_SELECT_SOURCE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call informs the video device which source shall be used for the input - data. The possible sources are demux or memory. If memory is selected, the - data is fed to the video device through the write command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE, - video_stream_source_t source);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SELECT_SOURCE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_stream_source_t - source</para> -</entry><entry - align="char"> -<para>Indicates which source shall be used for the Video stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.9</abbrev>VIDEO_SET_BLANK<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to blank out the picture.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean - mode);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_BLANK for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean mode</para> -</entry><entry - align="char"> -<para>TRUE: Blank screen when stop.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE: Show last decoded frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal input parameter</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.10</abbrev>VIDEO_GET_STATUS<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to return the current status of the device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct - video_status ⋆status);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_STATUS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct video_status - *status</para> -</entry><entry - align="char"> -<para>Returns the current status of the Video Device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error, possibly in the communication with the - DVB subsystem.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>status points to invalid address</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.11</abbrev>VIDEO_GET_EVENT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call returns an event of type video_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. Read-only - permissions are sufficient for this ioctl call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct - video_event ⋆ev);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_EVENT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct video_event - *ev</para> -</entry><entry - align="char"> -<para>Points to the location where the event, if any, is to be - stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>ev points to invalid address</para> -</entry> - </row><row><entry - align="char"> -<para>EWOULDBLOCK</para> -</entry><entry - align="char"> -<para>There is no event pending, and the device is in - non-blocking mode.</para> -</entry> - </row><row><entry - align="char"> -<para>EOVERFLOW</para> -</entry><entry - align="char"> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>Overflow in event queue - one or more events were lost.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.12</abbrev>VIDEO_SET_DISPLAY_FORMAT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Video Device to select the video format to be applied - by the MPEG chip on the video.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = - VIDEO_SET_DISPLAY_FORMAT, video_display_format_t - format);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_DISPLAY_FORMAT for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_display_format_t - format</para> -</entry><entry - align="char"> -<para>Selects the video format to be used.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal parameter format.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.13</abbrev>VIDEO_STILLPICTURE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_STILLPICTURE, - struct video_still_picture ⋆sp);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_STILLPICTURE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct - video_still_picture - *sp</para> -</entry><entry - align="char"> -<para>Pointer to a location where an I-frame and size is stored.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>sp points to an invalid iframe.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.14</abbrev>VIDEO_FAST_FORWARD<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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_MEMORY is selected.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int - nFrames);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_FAST_FORWARD for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int nFrames</para> -</entry><entry - align="char"> -<para>The number of frames to skip.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal parameter format.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.15</abbrev>VIDEO_SLOWMOTION<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int - nFrames);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SLOWMOTION for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int nFrames</para> -</entry><entry - align="char"> -<para>The number of times to repeat each frame.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal parameter format.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.16</abbrev>VIDEO_GET_CAPABILITIES<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the video device about its decoding capabilities. On success - it returns and integer which has bits set according to the defines in section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, - unsigned int ⋆cap);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_CAPABILITIES for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned int *cap</para> -</entry><entry - align="char"> -<para>Pointer to a location where to store the capability - information.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>cap points to an invalid iframe.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.17</abbrev>VIDEO_SET_ID<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl selects which sub-stream is to be decoded if a program or system - stream is sent to the video device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = VIDEO_SET_ID, int - id);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int id</para> -</entry><entry - align="char"> -<para>video sub-stream id</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid sub-stream id.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.18</abbrev>VIDEO_CLEAR_BUFFER<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_CLEAR_BUFFER for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.19</abbrev>VIDEO_SET_STREAMTYPE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl tells the driver which kind of stream to expect being written to it. If - this call is not used the default of video PES is used. Some drivers might not - support this call and always expect PES.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, - int type);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_STREAMTYPE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int type</para> -</entry><entry - align="char"> -<para>stream type</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>type is not a valid or supported stream type.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.20</abbrev>VIDEO_SET_FORMAT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the screen format (aspect ratio) of the connected output device - (TV) so that the output of the decoder can be adjusted accordingly.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_FORMAT, - video_format_t format);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_FORMAT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_format_t - format</para> -</entry><entry - align="char"> -<para>video format of TV as defined in section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>format is not a valid video format.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.21</abbrev>VIDEO_SET_SYSTEM<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the television output format. The format (see section ??) may - vary from the color format of the displayed MPEG stream. If the hardware is - not able to display the requested format the call will return an error.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM , - video_system_t system);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_FORMAT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_system_t - system</para> -</entry><entry - align="char"> -<para>video system of TV output.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>system is not a valid or supported video system.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.22</abbrev>VIDEO_SET_HIGHLIGHT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT - ,video_highlight_t ⋆vhilite)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_highlight_t - *vhilite</para> -</entry><entry - align="char"> -<para>SPU Highlight information according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid highlight setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.23</abbrev>VIDEO_SET_SPU<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can - only be used, if the driver is able to handle a DVD stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_SPU , - video_spu_t ⋆spu)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_SPU for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_spu_t *spu</para> -</entry><entry - align="char"> -<para>SPU decoding (de)activation and subid setting according - to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid spu setting or driver cannot handle - SPU.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.24</abbrev>VIDEO_SET_SPU_PALETTE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl sets the SPU color palette.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE - ,video_spu_palette_t ⋆palette )</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_spu_palette_t - *palette</para> -</entry><entry - align="char"> -<para>SPU palette according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid palette or driver doesn’t handle SPU.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.25</abbrev>VIDEO_GET_NAVI<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl returns navigational information from the DVD stream. This is - especially needed if an encoded stream has to be decoded by the hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_GET_NAVI , - video_navi_pack_t ⋆navipack)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_GET_NAVI for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_navi_pack_t - *navipack</para> -</entry><entry - align="char"> -<para>PCI or DSI pack (private stream 2) according to section - ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>driver is not able to return navigational information</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">4.2.26</abbrev>VIDEO_SET_ATTRIBUTES<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is intended for DVD playback and allows you to set certain - information about the stream. Some hardware may not need this information, - but the call also tells the hardware to prepare for DVD playback.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE - ,video_attributes_t vattr)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>video_attributes_t - vattr</para> -</entry><entry - align="char"> -<para>video attributes according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>input is not a valid attribute setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section></section><section -role="chapter"><title>DVB Audio Device</title> -<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It -can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and -ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your -application. -</para> -<para>Please note that some DVB cards don’t have their own MPEG decoder, which results in -the omission of the audio and video device. -</para> -<section -role="section"><title><abbrev role="title-mark">5.1</abbrev>Audio Data Types</title> -<para>This section describes the structures, data types and defines used when talking to the -audio device. -</para> - -<section -role="subsection"><title><abbrev role="title-mark">5.1.1</abbrev>audio_stream_source_t</title> -<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take -the following values, depending on whether we are replaying from an internal (demux) or -external (user write) source. -</para> -<programlisting> - typedef enum { - AUDIO_SOURCE_DEMUX, - AUDIO_SOURCE_MEMORY - } audio_stream_source_t; -</programlisting> -<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the -DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY -is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system -call. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.2</abbrev>audio_play_state_t</title> -<para>The following values can be returned by the AUDIO_GET_STATUS call representing the -state of audio playback. -</para> -<programlisting> - typedef enum { - AUDIO_STOPPED, - AUDIO_PLAYING, - AUDIO_PAUSED - } audio_play_state_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.3</abbrev>audio_channel_select_t</title> -<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the -following values. -</para> -<programlisting> - typedef enum { - AUDIO_STEREO, - AUDIO_MONO_LEFT, - AUDIO_MONO_RIGHT, - } audio_channel_select_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.4</abbrev>struct audio_status</title> -<para>The AUDIO_GET_STATUS call returns the following structure informing about various -states of the playback operation. -</para> -<programlisting> - typedef struct audio_status { - boolean AV_sync_state; - boolean mute_state; - audio_play_state_t play_state; - audio_stream_source_t stream_source; - audio_channel_select_t channel_select; - boolean bypass_mode; - } audio_status_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.5</abbrev>struct audio_mixer</title> -<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio -volume. -</para> -<programlisting> - typedef struct audio_mixer { - unsigned int volume_left; - unsigned int volume_right; - } audio_mixer_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.6</abbrev>audio encodings</title> -<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following -bits set according to the hardwares capabilities. -</para> -<programlisting> - #define AUDIO_CAP_DTS 1 - #define AUDIO_CAP_LPCM 2 - #define AUDIO_CAP_MP1 4 - #define AUDIO_CAP_MP2 8 - #define AUDIO_CAP_MP3 16 - #define AUDIO_CAP_AAC 32 - #define AUDIO_CAP_OGG 64 - #define AUDIO_CAP_SDDS 128 - #define AUDIO_CAP_AC3 256 -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.7</abbrev>struct audio_karaoke</title> -<para>The ioctl AUDIO_SET_KARAOKE uses the following format: -</para> -<programlisting> - typedef - struct audio_karaoke{ - int vocal1; - int vocal2; - int melody; - } audio_karaoke_t; -</programlisting> -<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both, -Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the -right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left -and right. -</para> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.1.8</abbrev>audio attributes</title> -<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: -</para> -<programlisting> - typedef uint16_t audio_attributes_t; - /⋆ bits: descr. ⋆/ - /⋆ 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, ⋆/ - /⋆ 12 multichannel extension ⋆/ - /⋆ 11-10 audio type (0=not spec, 1=language included) ⋆/ - /⋆ 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) ⋆/ - /⋆ 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, ⋆/ - /⋆ 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) ⋆/ - /⋆ 2- 0 number of audio channels (n+1 channels) ⋆/ -</programlisting> - </section></section><section -role="section"><title><abbrev role="title-mark">5.2</abbrev>Audio Function Calls</title> - -<section -role="subsection"><title><abbrev role="title-mark">5.2.1</abbrev>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) - 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 error - code 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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific audio device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.2</abbrev>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened audio device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.3</abbrev>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>size_t write(int fd, const void ⋆buf, size_t count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>void *buf</para> -</entry><entry - align="char"> -<para>Pointer to the buffer containing the PES data.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t count</para> -</entry><entry - align="char"> -<para>Size of buf.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EPERM</para> -</entry><entry - align="char"> -<para>Mode AUDIO_SOURCE_MEMORY not selected.</para> -</entry> - </row><row><entry - align="char"> -<para>ENOMEM</para> -</entry><entry - align="char"> -<para>Attempted to write more data than the internal buffer can - hold.</para> -</entry> - </row><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.4</abbrev>AUDIO_STOP<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to stop playing the current stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_STOP);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_STOP for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.5</abbrev>AUDIO_PLAY<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to start playing an audio stream from the - selected source.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_PLAY);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_PLAY for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.6</abbrev>AUDIO_PAUSE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_PAUSE for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.7</abbrev>AUDIO_SELECT_SOURCE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, - audio_stream_source_t source);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SELECT_SOURCE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_stream_source_t - source</para> -</entry><entry - align="char"> -<para>Indicates the source that shall be used for the Audio - stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal input parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.8</abbrev>AUDIO_SET_MUTE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the audio device to mute the stream that is currently being - played.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_MUTE, - boolean state);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_MUTE for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean state</para> -</entry><entry - align="char"> -<para>Indicates if audio device shall mute or not.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE Audio Mute</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE Audio Un-mute</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal input parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.9</abbrev>AUDIO_SET_AV_SYNC<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, - boolean state);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_AV_SYNC for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean state</para> -</entry><entry - align="char"> -<para>Tells the DVB subsystem if A/V synchronization shall be - ON or OFF.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE AV-sync ON</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE AV-sync OFF</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal input parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.10</abbrev>AUDIO_SET_BYPASS_MODE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 if the hardware can handle it.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_SET_BYPASS_MODE, boolean mode);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_BYPASS_MODE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>boolean mode</para> -</entry><entry - align="char"> -<para>Enables or disables the decoding of the current Audio - stream in the DVB subsystem.</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>TRUE Bypass is disabled</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>FALSE Bypass is enabled</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal input parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.11</abbrev>AUDIO_CHANNEL_SELECT<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_CHANNEL_SELECT for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_channel_select_t - ch</para> -</entry><entry - align="char"> -<para>Select the output format of the audio (mono left/right, - stereo).</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Illegal input parameter ch.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.12</abbrev>AUDIO_GET_STATUS<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to return the current state of the Audio - Device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_GET_STATUS, - struct audio_status ⋆status);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_GET_STATUS for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>struct audio_status - *status</para> -</entry><entry - align="char"> -<para>Returns the current state of Audio Device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>status points to invalid address.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.13</abbrev>AUDIO_GET_CAPABILITIES<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities - of the audio hardware.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = - AUDIO_GET_CAPABILITIES, unsigned int ⋆cap);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_GET_CAPABILITIES for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>unsigned int *cap</para> -</entry><entry - align="char"> -<para>Returns a bit array of supported sound formats.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>cap points to an invalid address.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.14</abbrev>AUDIO_CLEAR_BUFFER<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl call asks the Audio Device to clear all software and hardware buffers - of the audio decoder device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_CLEAR_BUFFER for this command.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.15</abbrev>AUDIO_SET_ID<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl selects which sub-stream is to be decoded if a program or system - stream is sent to the video device. If no audio stream type is set the id has to be - in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7] - for LPCM. More specifications may follow for other stream types. If the stream - type is set the id just specifies the substream id of the audio stream and only - the first 5 bits are recognized.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_ID, int - id);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int id</para> -</entry><entry - align="char"> -<para>audio sub-stream id</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid sub-stream id.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.16</abbrev>AUDIO_SET_MIXER<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(int fd, int request = AUDIO_SET_MIXER, - audio_mixer_t ⋆mix);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_mixer_t *mix</para> -</entry><entry - align="char"> -<para>mixer settings.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EFAULT</para> -</entry><entry - align="char"> -<para>mix points to an invalid address.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.17</abbrev>AUDIO_SET_STREAMTYPE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl tells the driver which kind of audio stream to expect. This is useful - if the stream offers several audio sub-streams like LPCM and AC3.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, - int type);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_STREAMTYPE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>int type</para> -</entry><entry - align="char"> -<para>stream type</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>type is not a valid or supported stream type.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.18</abbrev>AUDIO_SET_EXT_ID<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl can be used to set the extension id for MPEG streams in DVD - playback. Only the first 3 bits are recognized.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int - id);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_EXT_ID for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>int id</para> -</entry><entry - align="char"> -<para>audio sub_stream_id</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>id is not a valid id.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.19</abbrev>AUDIO_SET_ATTRIBUTES<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl is intended for DVD playback and allows you to set certain - information about the audio stream.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, - audio_attributes_t attr );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_attributes_t - attr</para> -</entry><entry - align="char"> -<para>audio attributes according to section ??</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>attr is not a valid or supported attribute setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">5.2.20</abbrev>AUDIO_SET_KARAOKE<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, - audio_karaoke_t ⋆karaoke);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row><row><entry - align="char"> -<para>int request</para> -</entry><entry - align="char"> -<para>Equals AUDIO_SET_STREAMTYPE for this - command.</para> -</entry> - </row><row><entry - align="char"> -<para>audio_karaoke_t - *karaoke</para> -</entry><entry - align="char"> -<para>karaoke settings according to section ??.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>karaoke is not a valid or supported karaoke setting.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section></section><section -role="chapter"><title>DVB CA Device</title> -<para>The DVB CA device controls the conditional access hardware. It can be accessed through -<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by -including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application. -</para> -<section -role="section"><title><abbrev role="title-mark">6.1</abbrev>CA Data Types</title> - -<section -role="subsection"><title><abbrev role="title-mark">6.1.1</abbrev>ca_slot_info_t</title> - <programlisting> - /⋆ slot interface types and info ⋆/ - - typedef struct ca_slot_info_s { - int num; /⋆ slot number ⋆/ - - int type; /⋆ CA interface this slot supports ⋆/ - #define CA_CI 1 /⋆ CI high level interface ⋆/ - #define CA_CI_LINK 2 /⋆ CI link layer level interface ⋆/ - #define CA_CI_PHYS 4 /⋆ CI physical layer level interface ⋆/ - #define CA_SC 128 /⋆ simple smart card interface ⋆/ - - unsigned int flags; - #define CA_CI_MODULE_PRESENT 1 /⋆ module (or card) inserted ⋆/ - #define CA_CI_MODULE_READY 2 - } ca_slot_info_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">6.1.2</abbrev>ca_descr_info_t</title> - <programlisting> - typedef struct ca_descr_info_s { - unsigned int num; /⋆ number of available descramblers (keys) ⋆/ - unsigned int type; /⋆ type of supported scrambling system ⋆/ - #define CA_ECD 1 - #define CA_NDS 2 - #define CA_DSS 4 - } ca_descr_info_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">6.1.3</abbrev>ca_cap_t</title> - <programlisting> - typedef struct ca_cap_s { - unsigned int slot_num; /⋆ total number of CA card and module slots ⋆/ - unsigned int slot_type; /⋆ OR of all supported types ⋆/ - unsigned int descr_num; /⋆ total number of descrambler slots (keys) ⋆/ - unsigned int descr_type;/⋆ OR of all supported types ⋆/ - } ca_cap_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">6.1.4</abbrev>ca_msg_t</title> - <programlisting> - /⋆ a message to/from a CI-CAM ⋆/ - typedef struct ca_msg_s { - unsigned int index; - unsigned int type; - unsigned int length; - unsigned char msg[256]; - } ca_msg_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">6.1.5</abbrev>ca_descr_t</title> - <programlisting> - typedef struct ca_descr_s { - unsigned int index; - unsigned int parity; - unsigned char cw[8]; - } ca_descr_t; -</programlisting> - </section></section><section -role="section"><title><abbrev role="title-mark">6.2</abbrev>CA Function Calls</title> - -<section -role="subsection"><title><abbrev role="title-mark">6.2.1</abbrev>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use. -<para>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 CA Device in O_RDWR - mode. All other attempts to open the device in this mode will fail, and an error - code will be returned.</para> -</entry> - </row></tbody></tgroup></informaltable> -</para> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open(const char ⋆deviceName, int flags);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>const char - *deviceName</para> -</entry><entry - align="char"> -<para>Name of specific video device.</para> -</entry> - </row><row><entry - align="char"> -<para>int flags</para> -</entry><entry - align="char"> -<para>A bit-wise OR of the following flags:</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDONLY read-only access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_RDWR read/write access</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>O_NONBLOCK open in non-blocking mode</para> -</entry> - </row><row><entry - align="char"> -</entry><entry - align="char"> -<para>(blocking mode is the default)</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>Device driver not loaded/available.</para> -</entry> - </row><row><entry - align="char"> -<para>EINTERNAL</para> -</entry><entry - align="char"> -<para>Internal error.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>Device or resource busy.</para> -</entry> - </row><row><entry - align="char"> -<para>EINVAL</para> -</entry><entry - align="char"> -<para>Invalid argument.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">6.2.2</abbrev>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This system call closes a previously opened audio device.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(int fd);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>int fd</para> -</entry><entry - align="char"> -<para>File descriptor returned by a previous call to open().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>ERRORS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>EBADF</para> -</entry><entry - align="char"> -<para>fd is not a valid open file descriptor.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section></section><section -role="chapter"><title>DVB Network API</title> -<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets -received via DVB into the Linux network protocol stack, e.g. for internet via satellite -applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and -and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your -application. -</para> -<section -role="section"><title><abbrev role="title-mark">7.1</abbrev>DVB Net Data Types</title> -<para>To be written… -</para> - -</section></section><section -role="chapter"><title>Kernel Demux API</title> -<para>The kernel demux API defines a driver-internal interface for registering low-level, -hardware specific driver to a hardware independent demux layer. It is only of interest for -DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in -<emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>. -</para> -<para>Maintainer note: This section must be reviewed. It is probably out of date. -</para> -<section -role="section"><title><abbrev role="title-mark">8.1</abbrev>Kernel Demux Data Types</title> - -<section -role="subsection"><title><abbrev role="title-mark">8.1.1</abbrev>dmx_success_t</title> - <programlisting> - typedef enum { - DMX_OK = 0, /⋆ Received Ok ⋆/ - DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ - DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ - DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ - DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ - DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ - DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ - } dmx_success_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.1.2</abbrev>TS filter types</title> - <programlisting> - /⋆--------------------------------------------------------------------------⋆/ - /⋆ TS packet reception ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - /⋆ TS filter type for set_type() ⋆/ - - #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ - #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS - payload (<=184 bytes per packet) to callback ⋆/ - #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.1.3</abbrev>dmx_ts_pes_t</title> -<para>The structure -</para> -<programlisting> - typedef enum - { - DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ - DMX_TS_PES_VIDEO, /⋆ ... ⋆/ - DMX_TS_PES_TELETEXT, - DMX_TS_PES_SUBTITLE, - DMX_TS_PES_PCR, - DMX_TS_PES_OTHER, - } dmx_ts_pes_t; -</programlisting> -<para>describes the PES type for filters which write to a built-in decoder. The correspond (and -should be kept identical) to the types in the demux device. -</para> -<programlisting> - struct dmx_ts_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_ts_feed_s⋆ feed, - __u16 pid, - size_t callback_length, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); - int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, - int type, - dmx_ts_pes_t pes_type); - }; - - typedef struct dmx_ts_feed_s dmx_ts_feed_t; -</programlisting> - <programlisting> - /⋆--------------------------------------------------------------------------⋆/ - /⋆ PES packet reception (not supported yet) ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef struct dmx_pes_filter_s { - struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - } dmx_pes_filter_t; -</programlisting> - <programlisting> - typedef struct dmx_pes_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_pes_feed_s⋆ feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); - int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, - dmx_pes_filter_t⋆⋆ filter); - int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, - dmx_pes_filter_t⋆ filter); - } dmx_pes_feed_t; -</programlisting> - <programlisting> - 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; /⋆ Pointer to private data of the API client ⋆/ - } dmx_section_filter_t; -</programlisting> - <programlisting> - struct dmx_section_feed_s { - int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ - struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int (⋆set) (struct dmx_section_feed_s⋆ feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - int check_crc); - int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, - dmx_section_filter_t⋆⋆ filter); - int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, - dmx_section_filter_t⋆ filter); - int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); - int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); - }; - typedef struct dmx_section_feed_s dmx_section_feed_t; - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ Callback functions ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef 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); - - typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, - size_t buffer1_len, - __u8 ⋆ buffer2, - size_t buffer2_len, - dmx_section_filter_t ⋆ source, - dmx_success_t success); - - typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, - size_t buffer1_len, - __u8 ⋆ buffer2, - size_t buffer2_len, - dmx_pes_filter_t⋆ source, - dmx_success_t success); - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ DVB Front-End ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - typedef enum { - DMX_OTHER_FE = 0, - DMX_SATELLITE_FE, - DMX_CABLE_FE, - DMX_TERRESTRIAL_FE, - DMX_LVDS_FE, - DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ - DMX_MEMORY_FE - } dmx_frontend_source_t; - - typedef struct { - /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ - char⋆ id; /⋆ Unique front-end identifier ⋆/ - char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ - char⋆ model; /⋆ Name of the front-end model ⋆/ - struct list_head connectivity_list; /⋆ List of front-ends that can - be connected to a particular - demux ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - dmx_frontend_source_t source; - } dmx_frontend_t; - - /⋆--------------------------------------------------------------------------⋆/ - /⋆ MPEG-2 TS Demux ⋆/ - /⋆--------------------------------------------------------------------------⋆/ - - /⋆ - ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. - ⋆/ - - #define DMX_TS_FILTERING 1 - #define DMX_PES_FILTERING 2 - #define DMX_SECTION_FILTERING 4 - #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ - #define DMX_CRC_CHECKING 16 - #define DMX_TS_DESCRAMBLING 32 - #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 - #define DMX_MAC_ADDRESS_DESCRAMBLING 128 -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.1.4</abbrev>demux_demux_t</title> - <programlisting> - /⋆ - ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered - ⋆ front-ends from the generic type struct list_head - ⋆ to the type ⋆ dmx_frontend_t - ⋆. - ⋆/ - - #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) - - struct dmx_demux_s { - /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ - char⋆ id; /⋆ Unique demux identifier ⋆/ - char⋆ vendor; /⋆ Name of the demux vendor ⋆/ - char⋆ model; /⋆ Name of the demux model ⋆/ - __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ - dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ - struct list_head reg_list; /⋆ List of registered demuxes ⋆/ - void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ - int users; /⋆ Number of users ⋆/ - int (⋆open) (struct dmx_demux_s⋆ demux); - int (⋆close) (struct dmx_demux_s⋆ demux); - int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); - int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, - dmx_ts_feed_t⋆⋆ feed, - dmx_ts_cb callback); - int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, - dmx_ts_feed_t⋆ feed); - int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, - dmx_pes_feed_t⋆⋆ feed, - dmx_pes_cb callback); - int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, - dmx_pes_feed_t⋆ feed); - int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, - dmx_section_feed_t⋆⋆ feed, - dmx_section_cb callback); - int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, - dmx_section_feed_t⋆ feed); - int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, - __u8⋆ buffer1, - size_t buffer1_length, - __u8⋆ buffer2, - size_t buffer2_length, - __u16 pid); - int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, - __u8⋆ buffer1, - size_t buffer1_length, - __u8⋆ buffer2, size_t buffer2_length, - __u16 pid); - int (⋆add_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); - int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, - dmx_frontend_t⋆ frontend); - int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); - - - /⋆ added because js cannot keep track of these himself ⋆/ - int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); - }; - typedef struct dmx_demux_s dmx_demux_t; -</programlisting> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.1.5</abbrev>Demux directory</title> - <programlisting> - /⋆ - ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered - ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t - ⋆. - ⋆/ - - #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) - - int dmx_register_demux (dmx_demux_t⋆ demux); - int dmx_unregister_demux (dmx_demux_t⋆ demux); - struct list_head⋆ dmx_get_demuxes (void); -</programlisting> - </section></section><section -role="section"><title><abbrev role="title-mark">8.2</abbrev>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> - -<section -role="subsection"><title><abbrev role="title-mark">8.2.1</abbrev>dmx_register_demux()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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(),</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux structure.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EEXIST</para> -</entry><entry - align="char"> -<para>A demux with the same value of the id field already stored - in the directory.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSPC</para> -</entry><entry - align="char"> -<para>No space left in the directory.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.2.2</abbrev>dmx_unregister_demux()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux structure which is to be - unregistered.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>ENODEV</para> -</entry><entry - align="char"> -<para>The specified demux is not registered in the demux - directory.</para> -</entry> - </row><row><entry - align="char"> -<para>EBUSY</para> -</entry><entry - align="char"> -<para>The specified demux is currently in use.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.2.3</abbrev>dmx_get_demuxes()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>struct list_head ⋆dmx_get_demuxes ()</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>none</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>struct list_head *</para> -</entry><entry - align="char"> -<para>A list of demux interfaces, or NULL in the case of an - empty list.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section><section -role="section"><title><abbrev role="title-mark">8.3</abbrev>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 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 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> - -<section -role="subsection"><title><abbrev role="title-mark">8.3.1</abbrev>open()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int open ( demux_t⋆ demux );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EUSERS</para> -</entry><entry - align="char"> -<para>Maximum usage count reached.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.2</abbrev>close()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int close(demux_t⋆ demux);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENODEV</para> -</entry><entry - align="char"> -<para>The demux was not in use.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.3</abbrev>write()</title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 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 - memory. If this is the case, memory-based filtering has to be implemented - entirely in software.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int write(demux_t⋆ demux, const char⋆ buf, size_t - count);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>const char* buf</para> -</entry><entry - align="char"> -<para>Pointer to the TS data in kernel-space memory.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t length</para> -</entry><entry - align="char"> -<para>Length of the TS data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>The command is not implemented.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.4</abbrev>allocate_ts_feed()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int allocate_ts_feed(dmx_demux_t⋆ demux, - dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_feed_t** - feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_cb callback</para> -</entry><entry - align="char"> -<para>Pointer to the callback function for passing received TS - packet</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>No more TS feeds available.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>The command is not implemented.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.5</abbrev>release_ts_feed()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in - progress on the TS feed should be stopped before calling this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int release_ts_feed(dmx_demux_t⋆ demux, - dmx_ts_feed_t⋆ feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t* demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.6</abbrev>allocate_section_feed()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int allocate_section_feed(dmx_demux_t⋆ demux, - dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_feed_t - **feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_cb - callback</para> -</entry><entry - align="char"> -<para>Pointer to the callback function for passing received - sections.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>No more section feeds available.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>The command is not implemented.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.7</abbrev>release_section_feed()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int release_section_feed(dmx_demux_t⋆ demux, - dmx_section_feed_t ⋆feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>demux_t *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_feed_t - *feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.8</abbrev>descramble_mac_address()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function runs a descrambling algorithm on the destination MAC - address field of a DVB Datagram Section, replacing the original address - with its un-encrypted version. Otherwise, the description on the function - descramble_section_payload() applies also to this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int descramble_mac_address(dmx_demux_t⋆ demux, __u8 - ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, - size_t buffer2_length, __u16 pid);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t - *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8 *buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the first byte of the section.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer1.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8* buffer2</para> -</entry><entry - align="char"> -<para>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 circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer2.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>The PID on which the section was received. Useful - for obtaining the descrambling key, e.g. from a DVB - Common Access facility.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.9</abbrev>descramble_section_payload()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function runs a descrambling algorithm on the payload of a DVB - Datagram Section, replacing the original payload with its un-encrypted - 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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int descramble_section_payload(dmx_demux_t⋆ demux, - __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, - size_t buffer2_length, __u16 pid);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t - *demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8 *buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the first byte of the section.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer1.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8 *buffer2</para> -</entry><entry - align="char"> -<para>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 circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the section data, including headers and CRC, - in buffer2.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>The PID on which the section was received. Useful - for obtaining the descrambling key, e.g. from a DVB - Common Access facility.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.10</abbrev>add_frontend()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t - ⋆frontend);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_frontend_t* - frontend</para> -</entry><entry - align="char"> -<para>Pointer to the front-end instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EEXIST</para> -</entry><entry - align="char"> -<para>A front-end with the same value of the id field already - registered.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINUSE</para> -</entry><entry - align="char"> -<para>The demux is in use.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOMEM</para> -</entry><entry - align="char"> -<para>No more front-ends can be added.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.11</abbrev>remove_frontend()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 successfully calling this function, the caller can free the memory of - the frontend struct if it was dynamically allocated before the add_frontend() - operation.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int remove_frontend(dmx_demux_t⋆ demux, - dmx_frontend_t⋆ frontend);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_frontend_t* - frontend</para> -</entry><entry - align="char"> -<para>Pointer to the front-end instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>The front-end is in use, i.e. a call to connect_frontend() - has not been followed by a call to disconnect_frontend().</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.12</abbrev>get_frontends()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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().</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t*</para> -</entry><entry - align="char"> -<para>A list of front-end interfaces, or NULL in the case of an - empty list.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.13</abbrev>connect_frontend()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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().</para> -</entry> - </row><row><entry - align="char"> -<para>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().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int connect_frontend(dmx_demux_t⋆ demux, - dmx_frontend_t⋆ frontend);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_frontend_t* - frontend</para> -</entry><entry - align="char"> -<para>Pointer to the front-end instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row><row><entry - align="char"> -<para>-EBUSY</para> -</entry><entry - align="char"> -<para>The front-end is in use.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.3.14</abbrev>disconnect_frontend()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Disconnects the demux and a front-end previously connected by a - connect_frontend() call.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int disconnect_frontend(dmx_demux_t⋆ demux);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_demux_t* - demux</para> -</entry><entry - align="char"> -<para>Pointer to the demux API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section><section -role="section"><title><abbrev role="title-mark">8.4</abbrev>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> - -<section -role="subsection"><title><abbrev role="title-mark">8.4.1</abbrev>dmx_ts_cb()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>Any TS packets that match the filter settings are copied to a circular buffer. The - filtered TS packets are delivered to the client using this callback function. The - size of the circular 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.</para> -</entry> - </row><row><entry - align="char"> -<para>When this function is called, the buffer1 parameter typically points to the - start of the first undelivered TS packet within a circular buffer. The buffer2 - buffer parameter is normally NULL, except when the received TS packets have - crossed the last address of the circular buffer and ”wrapped” to the beginning - of the buffer. In the latter case the buffer1 parameter would contain an address - within the circular buffer, while the buffer2 parameter would contain the first - address of the circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>__u8* buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the start of the filtered TS packets.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the TS data in buffer1.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8* buffer2</para> -</entry><entry - align="char"> -<para>Pointer to the tail of the filtered TS packets, or NULL.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the TS data in buffer2.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_ts_feed_t* - source</para> -</entry><entry - align="char"> -<para>Indicates which TS feed is the source of the callback.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_success_t - success</para> -</entry><entry - align="char"> -<para>Indicates if there was an error in TS reception.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>Continue filtering.</para> -</entry> - </row><row><entry - align="char"> -<para>-1</para> -</entry><entry - align="char"> -<para>Stop filtering - has the same effect as a call to - stop_filtering() on the TS Feed API.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.4.2</abbrev>dmx_section_cb()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 circular - 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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>__u8* buffer1</para> -</entry><entry - align="char"> -<para>Pointer to the start of the filtered section, e.g. within the - circular buffer of the demux driver.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer1_length</para> -</entry><entry - align="char"> -<para>Length of the filtered section data in buffer1, including - headers and CRC.</para> -</entry> - </row><row><entry - align="char"> -<para>__u8* buffer2</para> -</entry><entry - align="char"> -<para>Pointer to the tail of the filtered section data, or NULL. - Useful to handle the wrapping of a circular buffer.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t buffer2_length</para> -</entry><entry - align="char"> -<para>Length of the filtered section data in buffer2, including - headers and CRC.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_filter_t* - filter</para> -</entry><entry - align="char"> -<para>Indicates the filter that triggered the callback.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_success_t - success</para> -</entry><entry - align="char"> -<para>Indicates if there was an error in section reception.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>Continue filtering.</para> -</entry> - </row><row><entry - align="char"> -<para>-1</para> -</entry><entry - align="char"> -<para>Stop filtering - has the same effect as a call to - stop_filtering() on the Section Feed API.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section><section -role="section"><title><abbrev role="title-mark">8.5</abbrev>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> - -<section -role="subsection"><title><abbrev role="title-mark">8.5.1</abbrev>set()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>This function sets the parameters of a TS feed. Any filtering in progress on the - TS feed must be stopped before calling this function.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t - callback_length, size_t circular_buffer_size, int - descramble, struct timespec timeout);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>PID value to filter. Only the TS packets carrying the - specified PID will be passed to the API client.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t - callback_length</para> -</entry><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t - circular_buffer_size</para> -</entry><entry - align="char"> -<para>Size of the circular buffer for the filtered TS packets.</para> -</entry> - </row><row><entry - align="char"> -<para>int descramble</para> -</entry><entry - align="char"> -<para>If non-zero, descramble the filtered TS packets.</para> -</entry> - </row><row><entry - align="char"> -<para>struct timespec - timeout</para> -</entry><entry - align="char"> -<para>Maximum time to wait before delivering received TS - packets to the client.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOMEM</para> -</entry><entry - align="char"> -<para>Not enough memory for the requested buffer size.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available for TS.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.5.2</abbrev>start_filtering()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int start_filtering(dmx_ts_feed_t⋆ feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.5.3</abbrev>stop_filtering()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>Stops filtering TS packets on this TS feed.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_ts_feed_t* feed</para> -</entry><entry - align="char"> -<para>Pointer to the TS feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - </section></section><section -role="section"><title><abbrev role="title-mark">8.6</abbrev>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> - -<section -role="subsection"><title><abbrev role="title-mark">8.6.1</abbrev>set()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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, only - the payloads of private sections can be scrambled while the rest of the section - data must be sent in the clear.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t - circular_buffer_size, int descramble, int - check_crc);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>__u16 pid</para> -</entry><entry - align="char"> -<para>PID value to filter; only the TS packets carrying the - specified PID will be accepted.</para> -</entry> - </row><row><entry - align="char"> -<para>size_t - circular_buffer_size</para> -</entry><entry - align="char"> -<para>Size of the circular buffer for filtered sections.</para> -</entry> - </row><row><entry - align="char"> -<para>int descramble</para> -</entry><entry - align="char"> -<para>If non-zero, descramble any sections that are scrambled.</para> -</entry> - </row><row><entry - align="char"> -<para>int check_crc</para> -</entry><entry - align="char"> -<para>If non-zero, check the CRC values of filtered sections.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOMEM</para> -</entry><entry - align="char"> -<para>Not enough memory for the requested buffer size.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSYS</para> -</entry><entry - align="char"> -<para>No descrambling facility available for sections.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.6.2</abbrev>allocate_filter()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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 in section ?? for the format of - the section filter.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int allocate_filter(dmx_section_feed_t⋆ feed, - dmx_section_filter_t⋆⋆ filter);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_filter_t** - filter</para> -</entry><entry - align="char"> -<para>Pointer to the allocated filter.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENOSPC</para> -</entry><entry - align="char"> -<para>No filters of given type and length available.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameters.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.6.3</abbrev>release_filter()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int release_filter ( dmx_section_feed_t⋆ feed, - dmx_section_filter_t⋆ filter);</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row><row><entry - align="char"> -<para>dmx_section_filter_t* - filter</para> -</entry><entry - align="char"> -<para>I/O Pointer to the instance data of a section filter.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-ENODEV</para> -</entry><entry - align="char"> -<para>No such filter allocated.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.6.4</abbrev>start_filtering()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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().</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int start_filtering ( dmx_section_feed_t⋆ feed );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section><section -role="subsection"><title><abbrev role="title-mark">8.6.5</abbrev>stop_filtering()<indexterm role="printindex" /></title> -<para>DESCRIPTION -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>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.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>SYNOPSIS -</para> -<informaltable><tgroup cols="1"><tbody><row><entry - align="char"> -<para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>PARAMETERS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>dmx_section_feed_t* - feed</para> -</entry><entry - align="char"> -<para>Pointer to the section feed API and instance data.</para> -</entry> - </row></tbody></tgroup></informaltable> -<para>RETURNS -</para> -<informaltable><tgroup cols="2"><tbody><row><entry - align="char"> -<para>0</para> -</entry><entry - align="char"> -<para>The function was completed without errors.</para> -</entry> - </row><row><entry - align="char"> -<para>-EINVAL</para> -</entry><entry - align="char"> -<para>Bad parameter.</para> -</entry> - </row></tbody></tgroup></informaltable> - -</section></section></section><section -role="chapter"><title>Examples</title> -<para>In this section we would like to present some examples for using the DVB API. -</para> -<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged -with the driver distribution from <emphasis role="tt">http://linuxtv.org/</emphasis>. -</para> -<section -role="section"><title><abbrev role="title-mark">9.1</abbrev>Tuning</title> -<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as -the demux devices. The example is given for QPSK tuners, but can easily be adjusted for -QAM. -</para> -<programlisting> - #include <sys/ioctl.h> - #include <stdio.h> - #include <stdint.h> - #include <sys/types.h> - #include <sys/stat.h> - #include <fcntl.h> - #include <time.h> - #include <unistd.h> - - #include <linux/dvb/dmx.h> - #include <linux/dvb/frontend.h> - #include <linux/dvb/sec.h> - #include <sys/poll.h> - - #define DMX "/dev/dvb/adapter0/demux1" - #define FRONT "/dev/dvb/adapter0/frontend1" - #define SEC "/dev/dvb/adapter0/sec1" - - /⋆ routine for checking if we have a signal and other status information⋆/ - int FEReadStatus(int fd, fe_status_t ⋆stat) - { - int ans; - - if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ - perror("FE READ STATUS: "); - return -1; - } - - if (⋆stat & FE_HAS_POWER) - printf("FE HAS POWER\n"); - - if (⋆stat & FE_HAS_SIGNAL) - printf("FE HAS SIGNAL\n"); - - if (⋆stat & FE_SPECTRUM_INV) - printf("SPEKTRUM INV\n"); - - return 0; - } - - - /⋆ tune qpsk ⋆/ - /⋆ freq: frequency of transponder ⋆/ - /⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/ - /⋆ diseqc: DiSEqC address of the used LNB ⋆/ - /⋆ pol: Polarisation ⋆/ - /⋆ srate: Symbol Rate ⋆/ - /⋆ fec. FEC ⋆/ - /⋆ lnb_lof1: local frequency of lower LNB band ⋆/ - /⋆ lnb_lof2: local frequency of upper LNB band ⋆/ - /⋆ lnb_slof: switch frequency of LNB ⋆/ - - int set_qpsk_channel(int freq, int vpid, int apid, int tpid, - int diseqc, int pol, int srate, int fec, int lnb_lof1, - int lnb_lof2, int lnb_slof) - { - struct secCommand scmd; - struct secCmdSequence scmds; - struct dmx_pes_filter_params pesFilterParams; - FrontendParameters frp; - struct pollfd pfd[1]; - FrontendEvent event; - int demux1, demux2, demux3, front; - - frequency = (uint32_t) freq; - symbolrate = (uint32_t) srate; - - if((front = open(FRONT,O_RDWR)) < 0){ - perror("FRONTEND DEVICE: "); - return -1; - } - - if((sec = open(SEC,O_RDWR)) < 0){ - perror("SEC DEVICE: "); - return -1; - } - - if (demux1 < 0){ - if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux2 < 0){ - if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux3 < 0){ - if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (freq < lnb_slof) { - frp.Frequency = (freq - lnb_lof1); - scmds.continuousTone = SEC_TONE_OFF; - } else { - frp.Frequency = (freq - lnb_lof2); - scmds.continuousTone = SEC_TONE_ON; - } - frp.Inversion = INVERSION_AUTO; - if (pol) scmds.voltage = SEC_VOLTAGE_18; - else scmds.voltage = SEC_VOLTAGE_13; - - scmd.type=0; - scmd.u.diseqc.addr=0x10; - scmd.u.diseqc.cmd=0x38; - scmd.u.diseqc.numParams=1; - scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) | - (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | - (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); - - scmds.miniCommand=SEC_MINI_NONE; - scmds.numCommands=1; - scmds.commands=&scmd; - if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ - perror("SEC SEND: "); - return -1; - } - - if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ - perror("SEC SEND: "); - return -1; - } - - frp.u.qpsk.SymbolRate = srate; - frp.u.qpsk.FEC_inner = fec; - - if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ - perror("QPSK TUNE: "); - return -1; - } - - pfd[0].fd = front; - pfd[0].events = POLLIN; - - if (poll(pfd,1,3000)){ - if (pfd[0].revents & POLLIN){ - printf("Getting QPSK event\n"); - if ( ioctl(front, FE_GET_EVENT, &event) - - == -EOVERFLOW){ - perror("qpsk get event"); - return -1; - } - printf("Received "); - switch(event.type){ - case FE_UNEXPECTED_EV: - printf("unexpected event\n"); - return -1; - case FE_FAILURE_EV: - printf("failure event\n"); - return -1; - - case FE_COMPLETION_EV: - printf("completion event\n"); - } - } - } - - - pesFilterParams.pid = vpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pes_type = DMX_PES_VIDEO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_vpid"); - return -1; - } - - pesFilterParams.pid = apid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pes_type = DMX_PES_AUDIO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_apid"); - return -1; - } - - pesFilterParams.pid = tpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pes_type = DMX_PES_TELETEXT; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_tpid"); - return -1; - } - - return has_signal(fds); - } - -</programlisting> -<para>The program assumes that you are using a universal LNB and a standard DiSEqC -switch with up to 4 addresses. Of course, you could build in some more checking if -tuning was successful and maybe try to repeat the tuning process. Depending on the -external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be -necessary. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">9.2</abbrev>The DVR device</title> -<para>The following program code shows how to use the DVR device for recording. -</para> -<programlisting> - #include <sys/ioctl.h> - #include <stdio.h> - #include <stdint.h> - #include <sys/types.h> - #include <sys/stat.h> - #include <fcntl.h> - #include <time.h> - #include <unistd.h> - - #include <linux/dvb/dmx.h> - #include <linux/dvb/video.h> - #include <sys/poll.h> - #define DVR "/dev/dvb/adapter0/dvr1" - #define AUDIO "/dev/dvb/adapter0/audio1" - #define VIDEO "/dev/dvb/adapter0/video1" - - #define BUFFY (188⋆20) - #define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/ - - - /⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/ - - /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ - /⋆ vpid, apid: PIDs of video and audio channels ⋆/ - - int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) - { - struct dmx_pes_filter_params pesFilterParams; - - if (demux1 < 0){ - if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux2 < 0){ - if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - pesFilterParams.pid = vpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pes_type = DMX_PES_VIDEO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("DEMUX DEVICE"); - return -1; - } - pesFilterParams.pid = apid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pes_type = DMX_PES_AUDIO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("DEMUX DEVICE"); - return -1; - } - return 0; - } - - /⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/ - - /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ - /⋆ vpid, apid: PIDs of video and audio channels ⋆/ - int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) - { - int i; - int len; - int written; - uint8_t buf[BUFFY]; - uint64_t length; - struct pollfd pfd[1]; - int dvr, dvr_out; - - /⋆ open dvr device ⋆/ - if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ - perror("DVR DEVICE"); - return -1; - } - - /⋆ switch video and audio demuxes to dvr ⋆/ - printf ("Switching dvr on\n"); - i = switch_to_record(demux1, demux2, vpid, apid); - printf("finished: "); - - printf("Recording %2.0f MB of test file in TS format\n", - MAX_LENGTH/(1024.0⋆1024.0)); - length = 0; - - /⋆ open output file ⋆/ - if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT - |O_TRUNC, S_IRUSR|S_IWUSR - |S_IRGRP|S_IWGRP|S_IROTH| - S_IWOTH)) < 0){ - perror("Can't open file for dvr test"); - return -1; - } - - pfd[0].fd = dvr; - pfd[0].events = POLLIN; - - /⋆ poll for dvr data and write to file ⋆/ - while (length < MAX_LENGTH ) { - if (poll(pfd,1,1)){ - if (pfd[0].revents & POLLIN){ - len = read(dvr, buf, BUFFY); - if (len < 0){ - perror("recording"); - return -1; - } - if (len > 0){ - written = 0; - while (written < len) - written += - write (dvr_out, - buf, len); - length += len; - printf("written %2.0f MB\r", - length/1024./1024.); - } - } - } - } - return 0; - } - -</programlisting> - - - -</section>GNU Free Documentation License -<para>Version 1.1, March 2000 -</para> -<para>Copyright � 2000 Free Software Foundation, Inc. -59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -Everyone is permitted to copy and distribute verbatim copies of this license document, but -changing it is not allowed. -</para> -<section -role="likesection"><title>Preamble</title> -<para>The purpose of this License is to make a manual, textbook, or other written document -“free” in the sense of freedom: to assure everyone the effective freedom to copy and -redistribute it, with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way to get credit -for their work, while not being considered responsible for modifications made by -others. -</para> -<para>This License is a kind of “copyleft”, which means that derivative works of the document -must themselves be free in the same sense. It complements the GNU General Public License, -which is a copyleft license designed for free software. -</para> -<para>We have designed this License in order to use it for manuals for free software, because -free software needs free documentation: a free program should come with manuals providing -the same freedoms that the software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or whether it is published as a -printed book. We recommend this License principally for works whose purpose is instruction -or reference. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.1</abbrev>Applicability and Definitions</title> -<para>This License applies to any manual or other work that contains a notice placed by the -copyright holder saying it can be distributed under the terms of this License. The -“Document”, below, refers to any such manual or work. Any member of the public is a -licensee, and is addressed as “you”. -</para> -<para>A “Modified Version” of the Document means any work containing the Document or a -portion of it, either copied verbatim, or with modifications and/or translated into another -language. -</para> -<para>A “Secondary Section” is a named appendix or a front-matter section of the Document -that deals exclusively with the relationship of the publishers or authors of the Document to -the Document’s overall subject (or to related matters) and contains nothing that could -fall directly within that overall subject. (For example, if the Document is in part a -textbook of mathematics, a Secondary Section may not explain any mathematics.) The -relationship could be a matter of historical connection with the subject or with related -matters, or of legal, commercial, philosophical, ethical or political position regarding -them. -</para> -<para>The “Invariant Sections” are certain Secondary Sections whose titles are designated, as -being those of Invariant Sections, in the notice that says that the Document is released under -this License. -</para> -<para>The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts -or Back-Cover Texts, in the notice that says that the Document is released under this -License. -</para> -<para>A “Transparent” copy of the Document means a machine-readable copy, represented in a -format whose specification is available to the general public, whose contents can be viewed -and edited directly and straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available drawing editor, and -that is suitable for input to text formatters or for automatic translation to a variety of -formats suitable for input to text formatters. A copy made in an otherwise Transparent -file format whose markup has been designed to thwart or discourage subsequent -modification by readers is not Transparent. A copy that is not “Transparent” is called -“Opaque”. -</para> -<para>Examples of suitable formats for Transparent copies include plain ASCII without markup, -Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, -and standard-conforming simple HTML designed for human modification. Opaque formats -include PostScript, PDF, proprietary formats that can be read and edited only by proprietary -word processors, SGML or XML for which the DTD and/or processing tools are not -generally available, and the machine-generated HTML produced by some word processors -for output purposes only. -</para> -<para>The “Title Page” means, for a printed book, the title page itself, plus such following pages -as are needed to hold, legibly, the material this License requires to appear in the title page. -For works in formats which do not have any title page as such, “Title Page” means the text -near the most prominent appearance of the work’s title, preceding the beginning of the body -of the text. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.2</abbrev>Verbatim Copying</title> -<para>You may copy and distribute the Document in any medium, either commercially or -noncommercially, provided that this License, the copyright notices, and the license notice -saying this License applies to the Document are reproduced in all copies, and that you add no -other conditions whatsoever to those of this License. You may not use technical measures to -obstruct or control the reading or further copying of the copies you make or distribute. -However, you may accept compensation in exchange for copies. If you distribute -a large enough number of copies you must also follow the conditions in section -3. -</para> -<para>You may also lend copies, under the same conditions stated above, and you may publicly -display copies. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.3</abbrev>Copying in Quantity</title> -<para>If you publish printed copies of the Document numbering more than 100, and the -Document’s license notice requires Cover Texts, you must enclose the copies in covers that -carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and -Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you -as the publisher of these copies. The front cover must present the full title with all words of -the title equally prominent and visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve the title of the -Document and satisfy these conditions, can be treated as verbatim copying in other -respects. -</para> -<para>If the required texts for either cover are too voluminous to fit legibly, you should put the -first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto -adjacent pages. -</para> -<para>If you publish or distribute Opaque copies of the Document numbering more than 100, -you must either include a machine-readable Transparent copy along with each Opaque copy, -or state in or with each Opaque copy a publicly-accessible computer-network location -containing a complete Transparent copy of the Document, free of added material, -which the general network-using public has access to download anonymously at -no charge using public-standard network protocols. If you use the latter option, -you must take reasonably prudent steps, when you begin distribution of Opaque -copies in quantity, to ensure that this Transparent copy will remain thus accessible -at the stated location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that edition to the -public. -</para> -<para>It is requested, but not required, that you contact the authors of the Document well before -redistributing any large number of copies, to give them a chance to provide you with an -updated version of the Document. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.4</abbrev>Modifications</title> -<para>You may copy and distribute a Modified Version of the Document under the conditions of -sections 2 and 3 above, provided that you release the Modified Version under precisely this -License, with the Modified Version filling the role of the Document, thus licensing -distribution and modification of the Modified Version to whoever possesses a copy of it. In -addition, you must do these things in the Modified Version: -</para> - -<itemizedlist> - <listitem> -<para>Use in the Title Page (and on the covers, if any) a title distinct from that of the - Document, and from those of previous versions (which should, if there were any, - be listed in the History section of the Document). You may use the same title as - a previous version if the original publisher of that version gives permission. -</para> -</listitem> - <listitem> -<para>List on the Title Page, as authors, one or more persons or entities responsible for - authorship of the modifications in the Modified Version, together with at least - five of the principal authors of the Document (all of its principal authors, if it has - less than five). -</para> -</listitem> - <listitem> -<para>State on the Title page the name of the publisher of the Modified Version, as the - publisher. -</para> -</listitem> - <listitem> -<para>Preserve all the copyright notices of the Document. -</para> -</listitem> - <listitem> -<para>Add an appropriate copyright notice for your modifications adjacent to the other - copyright notices. -</para> -</listitem> - <listitem> -<para>Include, immediately after the copyright notices, a license notice giving the - public permission to use the Modified Version under the terms of this License, - in the form shown in the Addendum below. -</para> -</listitem> - <listitem> -<para>Preserve in that license notice the full lists of Invariant Sections and required - Cover Texts given in the Document’s license notice. -</para> -</listitem> - <listitem> -<para>Include an unaltered copy of this License. -</para> -</listitem> - <listitem> -<para>Preserve the section entitled “History”, and its title, and add to it an item stating - at least the title, year, new authors, and publisher of the Modified Version as - given on the Title Page. If there is no section entitled “History” in the Document, - create one stating the title, year, authors, and publisher of the Document as given - on its Title Page, then add an item describing the Modified Version as stated in - the previous sentence. -</para> -</listitem> - <listitem> -<para>Preserve the network location, if any, given in the Document for public access - to a Transparent copy of the Document, and likewise the network locations - given in the Document for previous versions it was based on. These may be - placed in the “History” section. You may omit a network location for a work that - was published at least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. -</para> -</listitem> - <listitem> -<para>In any section entitled “Acknowledgements” or “Dedications”, preserve the - section’s title, and preserve in the section all the substance and tone of each of - the contributor acknowledgements and/or dedications given therein. -</para> -</listitem> - <listitem> -<para>Preserve all the Invariant Sections of the Document, unaltered in their text and - in their titles. Section numbers or the equivalent are not considered part of the - section titles. -</para> -</listitem> - <listitem> -<para>Delete any section entitled “Endorsements”. Such a section may not be included - in the Modified Version. -</para> -</listitem> - <listitem> -<para>Do not retitle any existing section as “Endorsements” or to conflict in title with - any Invariant Section. -</para> -</listitem></itemizedlist> -<para>If the Modified Version includes new front-matter sections or appendices that qualify as -Secondary Sections and contain no material copied from the Document, you may at your -option designate some or all of these sections as invariant. To do this, add their titles to the list -of Invariant Sections in the Modified Version’s license notice. These titles must be distinct -from any other section titles. -</para> -<para>You may add a section entitled “Endorsements”, provided it contains nothing but -endorsements of your Modified Version by various parties – for example, statements of peer -review or that the text has been approved by an organization as the authoritative definition of -a standard. -</para> -<para>You may add a passage of up to five words as a Front-Cover Text, and a passage of up to -25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. -Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already includes a cover text -for the same cover, previously added by you or by arrangement made by the same -entity you are acting on behalf of, you may not add another; but you may replace -the old one, on explicit permission from the previous publisher that added the old -one. -</para> -<para>The author(s) and publisher(s) of the Document do not by this License give permission to -use their names for publicity for or to assert or imply endorsement of any Modified -Version. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.5</abbrev>Combining Documents</title> -<para>You may combine the Document with other documents released under this License, under -the terms defined in section 4 above for modified versions, provided that you include -in the combination all of the Invariant Sections of all of the original documents, -unmodified, and list them all as Invariant Sections of your combined work in its license -notice. -</para> -<para>The combined work need only contain one copy of this License, and multiple identical -Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections -with the same name but different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original author or publisher of -that section if known, or else a unique number. Make the same adjustment to the -section titles in the list of Invariant Sections in the license notice of the combined -work. -</para> -<para>In the combination, you must combine any sections entitled “History” in the various -original documents, forming one section entitled “History”; likewise combine any sections -entitled “Acknowledgements”, and any sections entitled “Dedications”. You must delete all -sections entitled “Endorsements.” -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.6</abbrev>Collections of Documents</title> -<para>You may make a collection consisting of the Document and other documents released -under this License, and replace the individual copies of this License in the various documents -with a single copy that is included in the collection, provided that you follow the -rules of this License for verbatim copying of each of the documents in all other -respects. -</para> -<para>You may extract a single document from such a collection, and distribute it individually -under this License, provided you insert a copy of this License into the extracted document, -and follow this License in all other respects regarding verbatim copying of that -document. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.7</abbrev>Aggregation With Independent Works</title> -<para>A compilation of the Document or its derivatives with other separate and independent -documents or works, in or on a volume of a storage or distribution medium, does not as a -whole count as a Modified Version of the Document, provided no compilation copyright is -claimed for the compilation. Such a compilation is called an “aggregate”, and this License -does not apply to the other self-contained works thus compiled with the Document, on -account of their being thus compiled, if they are not themselves derivative works of the -Document. -</para> -<para>If the Cover Text requirement of section 3 is applicable to these copies of the Document, -then if the Document is less than one quarter of the entire aggregate, the Document’s Cover -Texts may be placed on covers that surround only the Document within the aggregate. -Otherwise they must appear on covers around the whole aggregate. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.8</abbrev>Translation</title> -<para>Translation is considered a kind of modification, so you may distribute translations of the -Document under the terms of section 4. Replacing Invariant Sections with translations -requires special permission from their copyright holders, but you may include translations of -some or all Invariant Sections in addition to the original versions of these Invariant Sections. -You may include a translation of this License provided that you also include the original -English version of this License. In case of a disagreement between the translation -and the original English version of this License, the original English version will -prevail. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.9</abbrev>Termination</title> -<para>You may not copy, modify, sublicense, or distribute the Document except as expressly -provided for under this License. Any other attempt to copy, modify, sublicense or -distribute the Document is void, and will automatically terminate your rights under this -License. However, parties who have received copies, or rights, from you under this -License will not have their licenses terminated so long as such parties remain in full -compliance. -</para> - -</section><section -role="section"><title><abbrev role="title-mark">A.10</abbrev>Future Revisions of This License</title> -<para>The Free Software Foundation may publish new, revised versions of the GNU Free -Documentation License from time to time. Such new versions will be similar in spirit to the -present version, but may differ in detail to address new problems or concerns. See -http://www.gnu.org/copyleft/. -</para> -<para>Each version of the License is given a distinguishing version number. If the Document -specifies that a particular numbered version of this License ”or any later version” applies to it, -you have the option of following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the Free Software -Foundation. If the Document does not specify a version number of this License, -you may choose any version ever published (not as a draft) by the Free Software -Foundation. -</para> - -</section><section -role="likesection"><title>ADDENDUM: How to use this License for your documents</title> -<para>To use this License in a document you have written, include a copy of the License in the -document and put the following copyright and license notices just after the title -page: -</para> - -<para>Copyright � YEAR YOUR NAME. Permission is granted to copy, - distribute and/or modify this document under the terms of the GNU Free - Documentation License, Version 1.1 or any later version published by the - Free Software Foundation; with the Invariant Sections being LIST THEIR - TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover - Texts being LIST. A copy of the license is included in the section entitled - “GNU Free Documentation License”. -</para> -<para>If you have no Invariant Sections, write “with no Invariant Sections” instead -of saying which ones are invariant. If you have no Front-Cover Texts, write “no -Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise for Back-Cover -Texts. -</para> -<para>If your document contains nontrivial examples of program code, we recommend releasing -these examples in parallel under your choice of free software license, such as the GNU -General Public License, to permit their use in free software. - -</para> - - -</section></section></section></article> diff --git a/dvb-spec/sgml/dvbapi.sgml b/dvb-spec/sgml/dvbapi.sgml index e6f5674b8..6b4b96fe5 100644 --- a/dvb-spec/sgml/dvbapi.sgml +++ b/dvb-spec/sgml/dvbapi.sgml @@ -27,6 +27,7 @@ <surname>Chehab</surname> <othername role="mi">Carvalho</othername> <affiliation><address><email>mchehab@infradead.org</email></address></affiliation> +<contrib>Ported document to Docbook XML.</contrib> </author> </authorgroup> @@ -73,25 +74,30 @@ contents is the same as the original LaTex version.</revremark> <chapter id="frontend"> &sub-frontend; </chapter> -<!-- - <chapter id="devices"> -Should be broken into: -\input{demux.tex} -\input{video.tex} -\input{audio.tex} -\input{ca.tex} -\input{net.tex} -\input{kdapi.tex} - - &sub-devices; + <chapter id="demux"> + &sub-demux; + </chapter> + <chapter id="video"> + &sub-video; + </chapter> + <chapter id="audio"> + &sub-audio; + </chapter> + <chapter id="ca"> + &sub-ca; + </chapter> + <chapter id="net"> + &sub-net; + </chapter> + <chapter id="kdapi"> + &sub-kdapi; </chapter> <chapter id="examples"> &sub-examples; </chapter> - <chapter id="fdl"> + <appendix id="fdl"> &sub-fdl; - </chapter> ---> + </appendix> <!-- END OF CHAPTERS --> </book> diff --git a/dvb-spec/sgml/dvbstb.pdf b/dvb-spec/sgml/dvbstb.pdf Binary files differindex 5a4eff6cb..0fa75d90c 100644 --- a/dvb-spec/sgml/dvbstb.pdf +++ b/dvb-spec/sgml/dvbstb.pdf diff --git a/dvb-spec/sgml/examples.sgml b/dvb-spec/sgml/examples.sgml index e69de29bb..fcdea820a 100644 --- a/dvb-spec/sgml/examples.sgml +++ b/dvb-spec/sgml/examples.sgml @@ -0,0 +1,365 @@ +<title>Examples</title> +<para>In this section we would like to present some examples for using the DVB API. +</para> +<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged +with the driver distribution from <emphasis role="tt">http://linuxtv.org/</emphasis>. +</para> + +<section id="tuning"> +<title>Tuning</title> +<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as +the demux devices. The example is given for QPSK tuners, but can easily be adjusted for +QAM. +</para> +<programlisting> + #include <sys/ioctl.h> + #include <stdio.h> + #include <stdint.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <time.h> + #include <unistd.h> + + #include <linux/dvb/dmx.h> + #include <linux/dvb/frontend.h> + #include <linux/dvb/sec.h> + #include <sys/poll.h> + + #define DMX "/dev/dvb/adapter0/demux1" + #define FRONT "/dev/dvb/adapter0/frontend1" + #define SEC "/dev/dvb/adapter0/sec1" + + /⋆ routine for checking if we have a signal and other status information⋆/ + int FEReadStatus(int fd, fe_status_t ⋆stat) + { + int ans; + + if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ + perror("FE READ STATUS: "); + return -1; + } + + if (⋆stat & FE_HAS_POWER) + printf("FE HAS POWER\n"); + + if (⋆stat & FE_HAS_SIGNAL) + printf("FE HAS SIGNAL\n"); + + if (⋆stat & FE_SPECTRUM_INV) + printf("SPEKTRUM INV\n"); + + return 0; + } + + + /⋆ tune qpsk ⋆/ + /⋆ freq: frequency of transponder ⋆/ + /⋆ vpid, apid, tpid: PIDs of video, audio and teletext TS packets ⋆/ + /⋆ diseqc: DiSEqC address of the used LNB ⋆/ + /⋆ pol: Polarisation ⋆/ + /⋆ srate: Symbol Rate ⋆/ + /⋆ fec. FEC ⋆/ + /⋆ lnb_lof1: local frequency of lower LNB band ⋆/ + /⋆ lnb_lof2: local frequency of upper LNB band ⋆/ + /⋆ lnb_slof: switch frequency of LNB ⋆/ + + int set_qpsk_channel(int freq, int vpid, int apid, int tpid, + int diseqc, int pol, int srate, int fec, int lnb_lof1, + int lnb_lof2, int lnb_slof) + { + struct secCommand scmd; + struct secCmdSequence scmds; + struct dmx_pes_filter_params pesFilterParams; + FrontendParameters frp; + struct pollfd pfd[1]; + FrontendEvent event; + int demux1, demux2, demux3, front; + + frequency = (uint32_t) freq; + symbolrate = (uint32_t) srate; + + if((front = open(FRONT,O_RDWR)) < 0){ + perror("FRONTEND DEVICE: "); + return -1; + } + + if((sec = open(SEC,O_RDWR)) < 0){ + perror("SEC DEVICE: "); + return -1; + } + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux3 < 0){ + if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (freq < lnb_slof) { + frp.Frequency = (freq - lnb_lof1); + scmds.continuousTone = SEC_TONE_OFF; + } else { + frp.Frequency = (freq - lnb_lof2); + scmds.continuousTone = SEC_TONE_ON; + } + frp.Inversion = INVERSION_AUTO; + if (pol) scmds.voltage = SEC_VOLTAGE_18; + else scmds.voltage = SEC_VOLTAGE_13; + + scmd.type=0; + scmd.u.diseqc.addr=0x10; + scmd.u.diseqc.cmd=0x38; + scmd.u.diseqc.numParams=1; + scmd.u.diseqc.params[0] = 0xF0 | ((diseqc ⋆ 4) & 0x0F) | + (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | + (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); + + scmds.miniCommand=SEC_MINI_NONE; + scmds.numCommands=1; + scmds.commands=&scmd; + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + frp.u.qpsk.SymbolRate = srate; + frp.u.qpsk.FEC_inner = fec; + + if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ + perror("QPSK TUNE: "); + return -1; + } + + pfd[0].fd = front; + pfd[0].events = POLLIN; + + if (poll(pfd,1,3000)){ + if (pfd[0].revents & POLLIN){ + printf("Getting QPSK event\n"); + if ( ioctl(front, FE_GET_EVENT, &event) + + == -EOVERFLOW){ + perror("qpsk get event"); + return -1; + } + printf("Received "); + switch(event.type){ + case FE_UNEXPECTED_EV: + printf("unexpected event\n"); + return -1; + case FE_FAILURE_EV: + printf("failure event\n"); + return -1; + + case FE_COMPLETION_EV: + printf("completion event\n"); + } + } + } + + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_vpid"); + return -1; + } + + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_apid"); + return -1; + } + + pesFilterParams.pid = tpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_TELETEXT; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_tpid"); + return -1; + } + + return has_signal(fds); + } + +</programlisting> +<para>The program assumes that you are using a universal LNB and a standard DiSEqC +switch with up to 4 addresses. Of course, you could build in some more checking if +tuning was successful and maybe try to repeat the tuning process. Depending on the +external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be +necessary. +</para> +</section> + +<section id="the_dvr_device"> +<title>The DVR device</title> +<para>The following program code shows how to use the DVR device for recording. +</para> +<programlisting> + #include <sys/ioctl.h> + #include <stdio.h> + #include <stdint.h> + #include <sys/types.h> + #include <sys/stat.h> + #include <fcntl.h> + #include <time.h> + #include <unistd.h> + + #include <linux/dvb/dmx.h> + #include <linux/dvb/video.h> + #include <sys/poll.h> + #define DVR "/dev/dvb/adapter0/dvr1" + #define AUDIO "/dev/dvb/adapter0/audio1" + #define VIDEO "/dev/dvb/adapter0/video1" + + #define BUFFY (188⋆20) + #define MAX_LENGTH (1024⋆1024⋆5) /⋆ record 5MB ⋆/ + + + /⋆ switch the demuxes to recording, assuming the transponder is tuned ⋆/ + + /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ + /⋆ vpid, apid: PIDs of video and audio channels ⋆/ + + int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) + { + struct dmx_pes_filter_params pesFilterParams; + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pes_type = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pes_type = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + return 0; + } + + /⋆ start recording MAX_LENGTH , assuming the transponder is tuned ⋆/ + + /⋆ demux1, demux2: file descriptor of video and audio filters ⋆/ + /⋆ vpid, apid: PIDs of video and audio channels ⋆/ + int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) + { + int i; + int len; + int written; + uint8_t buf[BUFFY]; + uint64_t length; + struct pollfd pfd[1]; + int dvr, dvr_out; + + /⋆ open dvr device ⋆/ + if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ + perror("DVR DEVICE"); + return -1; + } + + /⋆ switch video and audio demuxes to dvr ⋆/ + printf ("Switching dvr on\n"); + i = switch_to_record(demux1, demux2, vpid, apid); + printf("finished: "); + + printf("Recording %2.0f MB of test file in TS format\n", + MAX_LENGTH/(1024.0⋆1024.0)); + length = 0; + + /⋆ open output file ⋆/ + if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT + |O_TRUNC, S_IRUSR|S_IWUSR + |S_IRGRP|S_IWGRP|S_IROTH| + S_IWOTH)) < 0){ + perror("Can't open file for dvr test"); + return -1; + } + + pfd[0].fd = dvr; + pfd[0].events = POLLIN; + + /⋆ poll for dvr data and write to file ⋆/ + while (length < MAX_LENGTH ) { + if (poll(pfd,1,1)){ + if (pfd[0].revents & POLLIN){ + len = read(dvr, buf, BUFFY); + if (len < 0){ + perror("recording"); + return -1; + } + if (len > 0){ + written = 0; + while (written < len) + written += + write (dvr_out, + buf, len); + length += len; + printf("written %2.0f MB\r", + length/1024./1024.); + } + } + } + } + return 0; + } + +</programlisting> + +</section>
\ No newline at end of file diff --git a/dvb-spec/sgml/fdl.sgml b/dvb-spec/sgml/fdl.sgml index e69de29bb..3b992d039 100644 --- a/dvb-spec/sgml/fdl.sgml +++ b/dvb-spec/sgml/fdl.sgml @@ -0,0 +1,374 @@ +<title>GNU Free Documentation License</title> +<para>Version 1.1, March 2000 +</para> +<para>Copyright © 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Everyone is permitted to copy and distribute verbatim copies of this license document, but +changing it is not allowed. +</para> +<section id="preamble"> +<title>Preamble</title> +<para>The purpose of this License is to make a manual, textbook, or other written document +“free” in the sense of freedom: to assure everyone the effective freedom to copy and +redistribute it, with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way to get credit +for their work, while not being considered responsible for modifications made by +others. +</para> +<para>This License is a kind of “copyleft”, which means that derivative works of the document +must themselves be free in the same sense. It complements the GNU General Public License, +which is a copyleft license designed for free software. +</para> +<para>We have designed this License in order to use it for manuals for free software, because +free software needs free documentation: a free program should come with manuals providing +the same freedoms that the software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or whether it is published as a +printed book. We recommend this License principally for works whose purpose is instruction +or reference. +</para> +</section> + +<section id="applicability_and_definitions"> +<title>Applicability and Definitions</title> +<para>This License applies to any manual or other work that contains a notice placed by the +copyright holder saying it can be distributed under the terms of this License. The +“Document”, below, refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. +</para> +<para>A “Modified Version” of the Document means any work containing the Document or a +portion of it, either copied verbatim, or with modifications and/or translated into another +language. +</para> +<para>A “Secondary Section” is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors of the Document to +the Document’s overall subject (or to related matters) and contains nothing that could +fall directly within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any mathematics.) The +relationship could be a matter of historical connection with the subject or with related +matters, or of legal, commercial, philosophical, ethical or political position regarding +them. +</para> +<para>The “Invariant Sections” are certain Secondary Sections whose titles are designated, as +being those of Invariant Sections, in the notice that says that the Document is released under +this License. +</para> +<para>The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts +or Back-Cover Texts, in the notice that says that the Document is released under this +License. +</para> +<para>A “Transparent” copy of the Document means a machine-readable copy, represented in a +format whose specification is available to the general public, whose contents can be viewed +and edited directly and straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available drawing editor, and +that is suitable for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise Transparent +file format whose markup has been designed to thwart or discourage subsequent +modification by readers is not Transparent. A copy that is not “Transparent” is called +“Opaque”. +</para> +<para>Examples of suitable formats for Transparent copies include plain ASCII without markup, +Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, +and standard-conforming simple HTML designed for human modification. Opaque formats +include PostScript, PDF, proprietary formats that can be read and edited only by proprietary +word processors, SGML or XML for which the DTD and/or processing tools are not +generally available, and the machine-generated HTML produced by some word processors +for output purposes only. +</para> +<para>The “Title Page” means, for a printed book, the title page itself, plus such following pages +as are needed to hold, legibly, the material this License requires to appear in the title page. +For works in formats which do not have any title page as such, “Title Page” means the text +near the most prominent appearance of the work’s title, preceding the beginning of the body +of the text. +</para> +</section> + +<section id="verbatim_copying"> +<title>Verbatim Copying</title> +<para>You may copy and distribute the Document in any medium, either commercially or +noncommercially, provided that this License, the copyright notices, and the license notice +saying this License applies to the Document are reproduced in all copies, and that you add no +other conditions whatsoever to those of this License. You may not use technical measures to +obstruct or control the reading or further copying of the copies you make or distribute. +However, you may accept compensation in exchange for copies. If you distribute +a large enough number of copies you must also follow the conditions in section +3. +</para> +<para>You may also lend copies, under the same conditions stated above, and you may publicly +display copies. +</para> +</section> + +<section id="copying_in_quantity"> +<title>Copying in Quantity</title> +<para>If you publish printed copies of the Document numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the copies in covers that +carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and +Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you +as the publisher of these copies. The front cover must present the full title with all words of +the title equally prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title of the +Document and satisfy these conditions, can be treated as verbatim copying in other +respects. +</para> +<para>If the required texts for either cover are too voluminous to fit legibly, you should put the +first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto +adjacent pages. +</para> +<para>If you publish or distribute Opaque copies of the Document numbering more than 100, +you must either include a machine-readable Transparent copy along with each Opaque copy, +or state in or with each Opaque copy a publicly-accessible computer-network location +containing a complete Transparent copy of the Document, free of added material, +which the general network-using public has access to download anonymously at +no charge using public-standard network protocols. If you use the latter option, +you must take reasonably prudent steps, when you begin distribution of Opaque +copies in quantity, to ensure that this Transparent copy will remain thus accessible +at the stated location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that edition to the +public. +</para> +<para>It is requested, but not required, that you contact the authors of the Document well before +redistributing any large number of copies, to give them a chance to provide you with an +updated version of the Document. +</para> +</section> + +<section id="modifications"> +<title>Modifications</title> +<para>You may copy and distribute a Modified Version of the Document under the conditions of +sections 2 and 3 above, provided that you release the Modified Version under precisely this +License, with the Modified Version filling the role of the Document, thus licensing +distribution and modification of the Modified Version to whoever possesses a copy of it. In +addition, you must do these things in the Modified Version: +</para> + +<itemizedlist> + <listitem> +<para>Use in the Title Page (and on the covers, if any) a title distinct from that of the + Document, and from those of previous versions (which should, if there were any, + be listed in the History section of the Document). You may use the same title as + a previous version if the original publisher of that version gives permission. +</para> +</listitem> + <listitem> +<para>List on the Title Page, as authors, one or more persons or entities responsible for + authorship of the modifications in the Modified Version, together with at least + five of the principal authors of the Document (all of its principal authors, if it has + less than five). +</para> +</listitem> + <listitem> +<para>State on the Title page the name of the publisher of the Modified Version, as the + publisher. +</para> +</listitem> + <listitem> +<para>Preserve all the copyright notices of the Document. +</para> +</listitem> + <listitem> +<para>Add an appropriate copyright notice for your modifications adjacent to the other + copyright notices. +</para> +</listitem> + <listitem> +<para>Include, immediately after the copyright notices, a license notice giving the + public permission to use the Modified Version under the terms of this License, + in the form shown in the Addendum below. +</para> +</listitem> + <listitem> +<para>Preserve in that license notice the full lists of Invariant Sections and required + Cover Texts given in the Document’s license notice. +</para> +</listitem> + <listitem> +<para>Include an unaltered copy of this License. +</para> +</listitem> + <listitem> +<para>Preserve the section entitled “History”, and its title, and add to it an item stating + at least the title, year, new authors, and publisher of the Modified Version as + given on the Title Page. If there is no section entitled “History” in the Document, + create one stating the title, year, authors, and publisher of the Document as given + on its Title Page, then add an item describing the Modified Version as stated in + the previous sentence. +</para> +</listitem> + <listitem> +<para>Preserve the network location, if any, given in the Document for public access + to a Transparent copy of the Document, and likewise the network locations + given in the Document for previous versions it was based on. These may be + placed in the “History” section. You may omit a network location for a work that + was published at least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +</para> +</listitem> + <listitem> +<para>In any section entitled “Acknowledgements” or “Dedications”, preserve the + section’s title, and preserve in the section all the substance and tone of each of + the contributor acknowledgements and/or dedications given therein. +</para> +</listitem> + <listitem> +<para>Preserve all the Invariant Sections of the Document, unaltered in their text and + in their titles. Section numbers or the equivalent are not considered part of the + section titles. +</para> +</listitem> + <listitem> +<para>Delete any section entitled “Endorsements”. Such a section may not be included + in the Modified Version. +</para> +</listitem> + <listitem> +<para>Do not retitle any existing section as “Endorsements” or to conflict in title with + any Invariant Section. +</para> +</listitem></itemizedlist> +<para>If the Modified Version includes new front-matter sections or appendices that qualify as +Secondary Sections and contain no material copied from the Document, you may at your +option designate some or all of these sections as invariant. To do this, add their titles to the list +of Invariant Sections in the Modified Version’s license notice. These titles must be distinct +from any other section titles. +</para> +<para>You may add a section entitled “Endorsements”, provided it contains nothing but +endorsements of your Modified Version by various parties – for example, statements of peer +review or that the text has been approved by an organization as the authoritative definition of +a standard. +</para> +<para>You may add a passage of up to five words as a Front-Cover Text, and a passage of up to +25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. +Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already includes a cover text +for the same cover, previously added by you or by arrangement made by the same +entity you are acting on behalf of, you may not add another; but you may replace +the old one, on explicit permission from the previous publisher that added the old +one. +</para> +<para>The author(s) and publisher(s) of the Document do not by this License give permission to +use their names for publicity for or to assert or imply endorsement of any Modified +Version. +</para> +</section> + +<section id="combining_documents"> +<title>Combining Documents</title> +<para>You may combine the Document with other documents released under this License, under +the terms defined in section 4 above for modified versions, provided that you include +in the combination all of the Invariant Sections of all of the original documents, +unmodified, and list them all as Invariant Sections of your combined work in its license +notice. +</para> +<para>The combined work need only contain one copy of this License, and multiple identical +Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections +with the same name but different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original author or publisher of +that section if known, or else a unique number. Make the same adjustment to the +section titles in the list of Invariant Sections in the license notice of the combined +work. +</para> +<para>In the combination, you must combine any sections entitled “History” in the various +original documents, forming one section entitled “History”; likewise combine any sections +entitled “Acknowledgements”, and any sections entitled “Dedications”. You must delete all +sections entitled “Endorsements.” +</para> +</section> + +<section id="collections_of_documents"> +<title>Collections of Documents</title> +<para>You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the various documents +with a single copy that is included in the collection, provided that you follow the +rules of this License for verbatim copying of each of the documents in all other +respects. +</para> +<para>You may extract a single document from such a collection, and distribute it individually +under this License, provided you insert a copy of this License into the extracted document, +and follow this License in all other respects regarding verbatim copying of that +document. +</para> +</section> + +<section id="aggregation_with_independent_works"> +<title>Aggregation With Independent Works</title> +<para>A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, does not as a +whole count as a Modified Version of the Document, provided no compilation copyright is +claimed for the compilation. Such a compilation is called an “aggregate”, and this License +does not apply to the other self-contained works thus compiled with the Document, on +account of their being thus compiled, if they are not themselves derivative works of the +Document. +</para> +<para>If the Cover Text requirement of section 3 is applicable to these copies of the Document, +then if the Document is less than one quarter of the entire aggregate, the Document’s Cover +Texts may be placed on covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. +</para> +</section> + +<section id="translation"> +<title>Translation</title> +<para>Translation is considered a kind of modification, so you may distribute translations of the +Document under the terms of section 4. Replacing Invariant Sections with translations +requires special permission from their copyright holders, but you may include translations of +some or all Invariant Sections in addition to the original versions of these Invariant Sections. +You may include a translation of this License provided that you also include the original +English version of this License. In case of a disagreement between the translation +and the original English version of this License, the original English version will +prevail. +</para> +</section> + +<section id="termination"> +<title>Termination</title> +<para>You may not copy, modify, sublicense, or distribute the Document except as expressly +provided for under this License. Any other attempt to copy, modify, sublicense or +distribute the Document is void, and will automatically terminate your rights under this +License. However, parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such parties remain in full +compliance. +</para> +</section> + +<section id="future_revisions_of_this_license"> +<title>Future Revisions of This License</title> +<para>The Free Software Foundation may publish new, revised versions of the GNU Free +Documentation License from time to time. Such new versions will be similar in spirit to the +present version, but may differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. +</para> +<para>Each version of the License is given a distinguishing version number. If the Document +specifies that a particular numbered version of this License ”or any later version” applies to it, +you have the option of following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the Free Software +Foundation. If the Document does not specify a version number of this License, +you may choose any version ever published (not as a draft) by the Free Software +Foundation. +</para> +</section> + +<section id="addendum"> +<title>ADDENDUM: How to use this License for your documents</title> +<para>To use this License in a document you have written, include a copy of the License in the +document and put the following copyright and license notices just after the title +page: +</para> + +<para>Copyright © YEAR YOUR NAME. Permission is granted to copy, + distribute and/or modify this document under the terms of the GNU Free + Documentation License, Version 1.1 or any later version published by the + Free Software Foundation; with the Invariant Sections being LIST THEIR + TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover + Texts being LIST. A copy of the license is included in the section entitled + “GNU Free Documentation License”. +</para> +<para>If you have no Invariant Sections, write “with no Invariant Sections” instead +of saying which ones are invariant. If you have no Front-Cover Texts, write “no +Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise for Back-Cover +Texts. +</para> +<para>If your document contains nontrivial examples of program code, we recommend releasing +these examples in parallel under your choice of free software license, such as the GNU +General Public License, to permit their use in free software. +</para> +</section> diff --git a/dvb-spec/sgml/intro.sgml b/dvb-spec/sgml/intro.sgml index 37d1c5055..83676c44e 100644 --- a/dvb-spec/sgml/intro.sgml +++ b/dvb-spec/sgml/intro.sgml @@ -43,17 +43,17 @@ implementation of the Linux DVB API.</para> <section id="overview"> <title>Overview</title> - <figure id="stb_components"> - <title>Components of a DVB card/STB</title> - <mediaobject> - <imageobject> - <imagedata fileref="dvbstb.pdf" format="PS" /> - </imageobject> - <imageobject> - <imagedata fileref="dvbstb.png" format="PNG" /> - </imageobject> - </mediaobject> - </figure> +<figure id="stb_components"> +<title>Components of a DVB card/STB</title> +<mediaobject> +<imageobject> +<imagedata fileref="dvbstb.pdf" format="PS" /> +</imageobject> +<imageobject> +<imagedata fileref="dvbstb.png" format="PNG" /> +</imageobject> +</mediaobject> +</figure> <para>A DVB PCI card or DVB set-top-box (STB) usually consists of the following main hardware components: </para> diff --git a/dvb-spec/sgml/kdapi.sgml b/dvb-spec/sgml/kdapi.sgml new file mode 100644 index 000000000..f0684cfbc --- /dev/null +++ b/dvb-spec/sgml/kdapi.sgml @@ -0,0 +1,2309 @@ +<title>Kernel Demux API</title> +<para>The kernel demux API defines a driver-internal interface for registering low-level, +hardware specific driver to a hardware independent demux layer. It is only of interest for +DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in +<emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>. +</para> +<para>Maintainer note: This section must be reviewed. It is probably out of date. +</para> + +<section id="kernel_demux_data_types"> +<title>Kernel Demux Data Types</title> + + +<section id="dmx_success_t"> +<title>dmx_success_t</title> + <programlisting> + typedef enum { + DMX_OK = 0, /⋆ Received Ok ⋆/ + DMX_LENGTH_ERROR, /⋆ Incorrect length ⋆/ + DMX_OVERRUN_ERROR, /⋆ Receiver ring buffer overrun ⋆/ + DMX_CRC_ERROR, /⋆ Incorrect CRC ⋆/ + DMX_FRAME_ERROR, /⋆ Frame alignment error ⋆/ + DMX_FIFO_ERROR, /⋆ Receiver FIFO overrun ⋆/ + DMX_MISSED_ERROR /⋆ Receiver missed packet ⋆/ + } dmx_success_t; +</programlisting> + +</section> +<section id="ts_filter_types"> +<title>TS filter types</title> + <programlisting> + /⋆--------------------------------------------------------------------------⋆/ + /⋆ TS packet reception ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + /⋆ TS filter type for set_type() ⋆/ + + #define TS_PACKET 1 /⋆ send TS packets (188 bytes) to callback (default) ⋆/ + #define TS_PAYLOAD_ONLY 2 /⋆ in case TS_PACKET is set, only send the TS + payload (<=184 bytes per packet) to callback ⋆/ + #define TS_DECODER 4 /⋆ send stream to built-in decoder (if present) ⋆/ +</programlisting> + +</section> +<section id="dmx_ts_pes_t"> +<title>dmx_ts_pes_t</title> +<para>The structure +</para> +<programlisting> + typedef enum + { + DMX_TS_PES_AUDIO, /⋆ also send packets to audio decoder (if it exists) ⋆/ + DMX_TS_PES_VIDEO, /⋆ ... ⋆/ + DMX_TS_PES_TELETEXT, + DMX_TS_PES_SUBTITLE, + DMX_TS_PES_PCR, + DMX_TS_PES_OTHER, + } dmx_ts_pes_t; +</programlisting> +<para>describes the PES type for filters which write to a built-in decoder. The correspond (and +should be kept identical) to the types in the demux device. +</para> +<programlisting> + struct dmx_ts_feed_s { + int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ + struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int (⋆set) (struct dmx_ts_feed_s⋆ feed, + __u16 pid, + size_t callback_length, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (⋆start_filtering) (struct dmx_ts_feed_s⋆ feed); + int (⋆stop_filtering) (struct dmx_ts_feed_s⋆ feed); + int (⋆set_type) (struct dmx_ts_feed_s⋆ feed, + int type, + dmx_ts_pes_t pes_type); + }; + + typedef struct dmx_ts_feed_s dmx_ts_feed_t; +</programlisting> + <programlisting> + /⋆--------------------------------------------------------------------------⋆/ + /⋆ PES packet reception (not supported yet) ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + typedef struct dmx_pes_filter_s { + struct dmx_pes_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + } dmx_pes_filter_t; +</programlisting> + <programlisting> + typedef struct dmx_pes_feed_s { + int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ + struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int (⋆set) (struct dmx_pes_feed_s⋆ feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (⋆start_filtering) (struct dmx_pes_feed_s⋆ feed); + int (⋆stop_filtering) (struct dmx_pes_feed_s⋆ feed); + int (⋆allocate_filter) (struct dmx_pes_feed_s⋆ feed, + dmx_pes_filter_t⋆⋆ filter); + int (⋆release_filter) (struct dmx_pes_feed_s⋆ feed, + dmx_pes_filter_t⋆ filter); + } dmx_pes_feed_t; +</programlisting> + <programlisting> + 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; /⋆ Pointer to private data of the API client ⋆/ + } dmx_section_filter_t; +</programlisting> + <programlisting> + struct dmx_section_feed_s { + int is_filtering; /⋆ Set to non-zero when filtering in progress ⋆/ + struct dmx_demux_s⋆ parent; /⋆ Back-pointer ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int (⋆set) (struct dmx_section_feed_s⋆ feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + int check_crc); + int (⋆allocate_filter) (struct dmx_section_feed_s⋆ feed, + dmx_section_filter_t⋆⋆ filter); + int (⋆release_filter) (struct dmx_section_feed_s⋆ feed, + dmx_section_filter_t⋆ filter); + int (⋆start_filtering) (struct dmx_section_feed_s⋆ feed); + int (⋆stop_filtering) (struct dmx_section_feed_s⋆ feed); + }; + typedef struct dmx_section_feed_s dmx_section_feed_t; + + /⋆--------------------------------------------------------------------------⋆/ + /⋆ Callback functions ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + typedef 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); + + typedef int (⋆dmx_section_cb) ( __u8 ⋆ buffer1, + size_t buffer1_len, + __u8 ⋆ buffer2, + size_t buffer2_len, + dmx_section_filter_t ⋆ source, + dmx_success_t success); + + typedef int (⋆dmx_pes_cb) ( __u8 ⋆ buffer1, + size_t buffer1_len, + __u8 ⋆ buffer2, + size_t buffer2_len, + dmx_pes_filter_t⋆ source, + dmx_success_t success); + + /⋆--------------------------------------------------------------------------⋆/ + /⋆ DVB Front-End ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + typedef enum { + DMX_OTHER_FE = 0, + DMX_SATELLITE_FE, + DMX_CABLE_FE, + DMX_TERRESTRIAL_FE, + DMX_LVDS_FE, + DMX_ASI_FE, /⋆ DVB-ASI interface ⋆/ + DMX_MEMORY_FE + } dmx_frontend_source_t; + + typedef struct { + /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ + char⋆ id; /⋆ Unique front-end identifier ⋆/ + char⋆ vendor; /⋆ Name of the front-end vendor ⋆/ + char⋆ model; /⋆ Name of the front-end model ⋆/ + struct list_head connectivity_list; /⋆ List of front-ends that can + be connected to a particular + demux ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + dmx_frontend_source_t source; + } dmx_frontend_t; + + /⋆--------------------------------------------------------------------------⋆/ + /⋆ MPEG-2 TS Demux ⋆/ + /⋆--------------------------------------------------------------------------⋆/ + + /⋆ + ⋆ Flags OR'ed in the capabilites field of struct dmx_demux_s. + ⋆/ + + #define DMX_TS_FILTERING 1 + #define DMX_PES_FILTERING 2 + #define DMX_SECTION_FILTERING 4 + #define DMX_MEMORY_BASED_FILTERING 8 /⋆ write() available ⋆/ + #define DMX_CRC_CHECKING 16 + #define DMX_TS_DESCRAMBLING 32 + #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 + #define DMX_MAC_ADDRESS_DESCRAMBLING 128 +</programlisting> + +</section> +<section id="demux_demux_t"> +<title>demux_demux_t</title> + <programlisting> + /⋆ + ⋆ DMX_FE_ENTRY(): Casts elements in the list of registered + ⋆ front-ends from the generic type struct list_head + ⋆ to the type ⋆ dmx_frontend_t + ⋆. + ⋆/ + + #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) + + struct dmx_demux_s { + /⋆ The following char⋆ fields point to NULL terminated strings ⋆/ + char⋆ id; /⋆ Unique demux identifier ⋆/ + char⋆ vendor; /⋆ Name of the demux vendor ⋆/ + char⋆ model; /⋆ Name of the demux model ⋆/ + __u32 capabilities; /⋆ Bitfield of capability flags ⋆/ + dmx_frontend_t⋆ frontend; /⋆ Front-end connected to the demux ⋆/ + struct list_head reg_list; /⋆ List of registered demuxes ⋆/ + void⋆ priv; /⋆ Pointer to private data of the API client ⋆/ + int users; /⋆ Number of users ⋆/ + int (⋆open) (struct dmx_demux_s⋆ demux); + int (⋆close) (struct dmx_demux_s⋆ demux); + int (⋆write) (struct dmx_demux_s⋆ demux, const char⋆ buf, size_t count); + int (⋆allocate_ts_feed) (struct dmx_demux_s⋆ demux, + dmx_ts_feed_t⋆⋆ feed, + dmx_ts_cb callback); + int (⋆release_ts_feed) (struct dmx_demux_s⋆ demux, + dmx_ts_feed_t⋆ feed); + int (⋆allocate_pes_feed) (struct dmx_demux_s⋆ demux, + dmx_pes_feed_t⋆⋆ feed, + dmx_pes_cb callback); + int (⋆release_pes_feed) (struct dmx_demux_s⋆ demux, + dmx_pes_feed_t⋆ feed); + int (⋆allocate_section_feed) (struct dmx_demux_s⋆ demux, + dmx_section_feed_t⋆⋆ feed, + dmx_section_cb callback); + int (⋆release_section_feed) (struct dmx_demux_s⋆ demux, + dmx_section_feed_t⋆ feed); + int (⋆descramble_mac_address) (struct dmx_demux_s⋆ demux, + __u8⋆ buffer1, + size_t buffer1_length, + __u8⋆ buffer2, + size_t buffer2_length, + __u16 pid); + int (⋆descramble_section_payload) (struct dmx_demux_s⋆ demux, + __u8⋆ buffer1, + size_t buffer1_length, + __u8⋆ buffer2, size_t buffer2_length, + __u16 pid); + int (⋆add_frontend) (struct dmx_demux_s⋆ demux, + dmx_frontend_t⋆ frontend); + int (⋆remove_frontend) (struct dmx_demux_s⋆ demux, + dmx_frontend_t⋆ frontend); + struct list_head⋆ (⋆get_frontends) (struct dmx_demux_s⋆ demux); + int (⋆connect_frontend) (struct dmx_demux_s⋆ demux, + dmx_frontend_t⋆ frontend); + int (⋆disconnect_frontend) (struct dmx_demux_s⋆ demux); + + + /⋆ added because js cannot keep track of these himself ⋆/ + int (⋆get_pes_pids) (struct dmx_demux_s⋆ demux, __u16 ⋆pids); + }; + typedef struct dmx_demux_s dmx_demux_t; +</programlisting> + +</section> +<section id="demux_directory"> +<title>Demux directory</title> + <programlisting> + /⋆ + ⋆ DMX_DIR_ENTRY(): Casts elements in the list of registered + ⋆ demuxes from the generic type struct list_head⋆ to the type dmx_demux_t + ⋆. + ⋆/ + + #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list) + + int dmx_register_demux (dmx_demux_t⋆ demux); + int dmx_unregister_demux (dmx_demux_t⋆ demux); + struct list_head⋆ dmx_get_demuxes (void); +</programlisting> + </section></section> +<section id="demux_directory_api"> +<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> + +<section +role="subsection"><title>dmx_register_demux()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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(),</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int dmx_register_demux ( dmx_demux_t ⋆demux )</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux structure.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EEXIST</para> +</entry><entry + align="char"> +<para>A demux with the same value of the id field already stored + in the directory.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSPC</para> +</entry><entry + align="char"> +<para>No space left in the directory.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>dmx_unregister_demux()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int dmx_unregister_demux ( dmx_demux_t ⋆demux )</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux structure which is to be + unregistered.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>The specified demux is not registered in the demux + directory.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>The specified demux is currently in use.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>dmx_get_demuxes()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>struct list_head ⋆dmx_get_demuxes ()</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>none</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>struct list_head *</para> +</entry><entry + align="char"> +<para>A list of demux interfaces, or NULL in the case of an + empty list.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section> +<section id="demux_api"> +<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 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 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> + + +<section id="kdapi_fopen"> +<title>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open ( demux_t⋆ demux );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EUSERS</para> +</entry><entry + align="char"> +<para>Maximum usage count reached.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="kdapi_fclose"> +<title>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(demux_t⋆ demux);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENODEV</para> +</entry><entry + align="char"> +<para>The demux was not in use.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="kdapi_fwrite"> +<title>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 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 + memory. If this is the case, memory-based filtering has to be implemented + entirely in software.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int write(demux_t⋆ demux, const char⋆ buf, size_t + count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>const char* buf</para> +</entry><entry + align="char"> +<para>Pointer to the TS data in kernel-space memory.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t length</para> +</entry><entry + align="char"> +<para>Length of the TS data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>The command is not implemented.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>allocate_ts_feed()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int allocate_ts_feed(dmx_demux_t⋆ demux, + dmx_ts_feed_t⋆⋆ feed, dmx_ts_cb callback);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_feed_t** + feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_cb callback</para> +</entry><entry + align="char"> +<para>Pointer to the callback function for passing received TS + packet</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>No more TS feeds available.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>The command is not implemented.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>release_ts_feed()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in + progress on the TS feed should be stopped before calling this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int release_ts_feed(dmx_demux_t⋆ demux, + dmx_ts_feed_t⋆ feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t* demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>allocate_section_feed()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int allocate_section_feed(dmx_demux_t⋆ demux, + dmx_section_feed_t ⋆⋆feed, dmx_section_cb callback);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_feed_t + **feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_cb + callback</para> +</entry><entry + align="char"> +<para>Pointer to the callback function for passing received + sections.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>No more section feeds available.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>The command is not implemented.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>release_section_feed()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int release_section_feed(dmx_demux_t⋆ demux, + dmx_section_feed_t ⋆feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>demux_t *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_feed_t + *feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>descramble_mac_address()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function runs a descrambling algorithm on the destination MAC + address field of a DVB Datagram Section, replacing the original address + with its un-encrypted version. Otherwise, the description on the function + descramble_section_payload() applies also to this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int descramble_mac_address(dmx_demux_t⋆ demux, __u8 + ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, + size_t buffer2_length, __u16 pid);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t + *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8 *buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the first byte of the section.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer1.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8* buffer2</para> +</entry><entry + align="char"> +<para>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 circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer2.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>The PID on which the section was received. Useful + for obtaining the descrambling key, e.g. from a DVB + Common Access facility.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>descramble_section_payload()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function runs a descrambling algorithm on the payload of a DVB + Datagram Section, replacing the original payload with its un-encrypted + 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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int descramble_section_payload(dmx_demux_t⋆ demux, + __u8 ⋆buffer1, size_t buffer1_length, __u8 ⋆buffer2, + size_t buffer2_length, __u16 pid);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t + *demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8 *buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the first byte of the section.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer1.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8 *buffer2</para> +</entry><entry + align="char"> +<para>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 circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the section data, including headers and CRC, + in buffer2.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>The PID on which the section was received. Useful + for obtaining the descrambling key, e.g. from a DVB + Common Access facility.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>add_frontend()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int add_frontend(dmx_demux_t ⋆demux, dmx_frontend_t + ⋆frontend);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_frontend_t* + frontend</para> +</entry><entry + align="char"> +<para>Pointer to the front-end instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EEXIST</para> +</entry><entry + align="char"> +<para>A front-end with the same value of the id field already + registered.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINUSE</para> +</entry><entry + align="char"> +<para>The demux is in use.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOMEM</para> +</entry><entry + align="char"> +<para>No more front-ends can be added.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>remove_frontend()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 successfully calling this function, the caller can free the memory of + the frontend struct if it was dynamically allocated before the add_frontend() + operation.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int remove_frontend(dmx_demux_t⋆ demux, + dmx_frontend_t⋆ frontend);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_frontend_t* + frontend</para> +</entry><entry + align="char"> +<para>Pointer to the front-end instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>The front-end is in use, i.e. a call to connect_frontend() + has not been followed by a call to disconnect_frontend().</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>get_frontends()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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().</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>struct list_head⋆ get_frontends(dmx_demux_t⋆ demux);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t*</para> +</entry><entry + align="char"> +<para>A list of front-end interfaces, or NULL in the case of an + empty list.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>connect_frontend()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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().</para> +</entry> + </row><row><entry + align="char"> +<para>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().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int connect_frontend(dmx_demux_t⋆ demux, + dmx_frontend_t⋆ frontend);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_frontend_t* + frontend</para> +</entry><entry + align="char"> +<para>Pointer to the front-end instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row><row><entry + align="char"> +<para>-EBUSY</para> +</entry><entry + align="char"> +<para>The front-end is in use.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>disconnect_frontend()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Disconnects the demux and a front-end previously connected by a + connect_frontend() call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int disconnect_frontend(dmx_demux_t⋆ demux);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_demux_t* + demux</para> +</entry><entry + align="char"> +<para>Pointer to the demux API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section> +<section id="demux_callback_api"> +<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> + +<section +role="subsection"><title>dmx_ts_cb()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>Any TS packets that match the filter settings are copied to a circular buffer. The + filtered TS packets are delivered to the client using this callback function. The + size of the circular 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.</para> +</entry> + </row><row><entry + align="char"> +<para>When this function is called, the buffer1 parameter typically points to the + start of the first undelivered TS packet within a circular buffer. The buffer2 + buffer parameter is normally NULL, except when the received TS packets have + crossed the last address of the circular buffer and ”wrapped” to the beginning + of the buffer. In the latter case the buffer1 parameter would contain an address + within the circular buffer, while the buffer2 parameter would contain the first + address of the circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>__u8* buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the start of the filtered TS packets.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the TS data in buffer1.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8* buffer2</para> +</entry><entry + align="char"> +<para>Pointer to the tail of the filtered TS packets, or NULL.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the TS data in buffer2.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_ts_feed_t* + source</para> +</entry><entry + align="char"> +<para>Indicates which TS feed is the source of the callback.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_success_t + success</para> +</entry><entry + align="char"> +<para>Indicates if there was an error in TS reception.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>Continue filtering.</para> +</entry> + </row><row><entry + align="char"> +<para>-1</para> +</entry><entry + align="char"> +<para>Stop filtering - has the same effect as a call to + stop_filtering() on the TS Feed API.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>dmx_section_cb()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 circular + 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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>__u8* buffer1</para> +</entry><entry + align="char"> +<para>Pointer to the start of the filtered section, e.g. within the + circular buffer of the demux driver.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer1_length</para> +</entry><entry + align="char"> +<para>Length of the filtered section data in buffer1, including + headers and CRC.</para> +</entry> + </row><row><entry + align="char"> +<para>__u8* buffer2</para> +</entry><entry + align="char"> +<para>Pointer to the tail of the filtered section data, or NULL. + Useful to handle the wrapping of a circular buffer.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t buffer2_length</para> +</entry><entry + align="char"> +<para>Length of the filtered section data in buffer2, including + headers and CRC.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_filter_t* + filter</para> +</entry><entry + align="char"> +<para>Indicates the filter that triggered the callback.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_success_t + success</para> +</entry><entry + align="char"> +<para>Indicates if there was an error in section reception.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>Continue filtering.</para> +</entry> + </row><row><entry + align="char"> +<para>-1</para> +</entry><entry + align="char"> +<para>Stop filtering - has the same effect as a call to + stop_filtering() on the Section Feed API.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section> +<section id="ts_feed_api"> +<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> + +<section +role="subsection"><title>set()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This function sets the parameters of a TS feed. Any filtering in progress on the + TS feed must be stopped before calling this function.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int set ( dmx_ts_feed_t⋆ feed, __u16 pid, size_t + callback_length, size_t circular_buffer_size, int + descramble, struct timespec timeout);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>PID value to filter. Only the TS packets carrying the + specified PID will be passed to the API client.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t + callback_length</para> +</entry><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t + circular_buffer_size</para> +</entry><entry + align="char"> +<para>Size of the circular buffer for the filtered TS packets.</para> +</entry> + </row><row><entry + align="char"> +<para>int descramble</para> +</entry><entry + align="char"> +<para>If non-zero, descramble the filtered TS packets.</para> +</entry> + </row><row><entry + align="char"> +<para>struct timespec + timeout</para> +</entry><entry + align="char"> +<para>Maximum time to wait before delivering received TS + packets to the client.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOMEM</para> +</entry><entry + align="char"> +<para>Not enough memory for the requested buffer size.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available for TS.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>start_filtering()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int start_filtering(dmx_ts_feed_t⋆ feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>stop_filtering()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>Stops filtering TS packets on this TS feed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int stop_filtering(dmx_ts_feed_t⋆ feed);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_ts_feed_t* feed</para> +</entry><entry + align="char"> +<para>Pointer to the TS feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section> +<section id="section_feed_api"> +<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> + +</section> +<section id="kdapi_set"> +<title>set()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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, only + the payloads of private sections can be scrambled while the rest of the section + data must be sent in the clear.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int set(dmx_section_feed_t⋆ feed, __u16 pid, size_t + circular_buffer_size, int descramble, int + check_crc);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 pid</para> +</entry><entry + align="char"> +<para>PID value to filter; only the TS packets carrying the + specified PID will be accepted.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t + circular_buffer_size</para> +</entry><entry + align="char"> +<para>Size of the circular buffer for filtered sections.</para> +</entry> + </row><row><entry + align="char"> +<para>int descramble</para> +</entry><entry + align="char"> +<para>If non-zero, descramble any sections that are scrambled.</para> +</entry> + </row><row><entry + align="char"> +<para>int check_crc</para> +</entry><entry + align="char"> +<para>If non-zero, check the CRC values of filtered sections.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOMEM</para> +</entry><entry + align="char"> +<para>Not enough memory for the requested buffer size.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSYS</para> +</entry><entry + align="char"> +<para>No descrambling facility available for sections.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameters.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>allocate_filter()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 in section ?? for the format of + the section filter.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int allocate_filter(dmx_section_feed_t⋆ feed, + dmx_section_filter_t⋆⋆ filter);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_filter_t** + filter</para> +</entry><entry + align="char"> +<para>Pointer to the allocated filter.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENOSPC</para> +</entry><entry + align="char"> +<para>No filters of given type and length available.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameters.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>release_filter()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int release_filter ( dmx_section_feed_t⋆ feed, + dmx_section_filter_t⋆ filter);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_section_filter_t* + filter</para> +</entry><entry + align="char"> +<para>I/O Pointer to the instance data of a section filter.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-ENODEV</para> +</entry><entry + align="char"> +<para>No such filter allocated.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>start_filtering()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int start_filtering ( dmx_section_feed_t⋆ feed );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>stop_filtering()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int stop_filtering ( dmx_section_feed_t⋆ feed );</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>dmx_section_feed_t* + feed</para> +</entry><entry + align="char"> +<para>Pointer to the section feed API and instance data.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>RETURNS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>0</para> +</entry><entry + align="char"> +<para>The function was completed without errors.</para> +</entry> + </row><row><entry + align="char"> +<para>-EINVAL</para> +</entry><entry + align="char"> +<para>Bad parameter.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section>
\ No newline at end of file diff --git a/dvb-spec/sgml/net.sgml b/dvb-spec/sgml/net.sgml new file mode 100644 index 000000000..77557ae2a --- /dev/null +++ b/dvb-spec/sgml/net.sgml @@ -0,0 +1,12 @@ +<title>DVB Network API</title> +<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets +received via DVB into the Linux network protocol stack, e.g. for internet via satellite +applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and +and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your +application. +</para> +<section id="dvb_net_types"> +<title>DVB Net Data Types</title> +<para>To be written… +</para> +</section>
\ No newline at end of file diff --git a/dvb-spec/sgml/video.sgml b/dvb-spec/sgml/video.sgml new file mode 100644 index 000000000..5e35abcdf --- /dev/null +++ b/dvb-spec/sgml/video.sgml @@ -0,0 +1,1971 @@ +<title>DVB Video Device</title> +<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It +can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and +ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your +application. +</para> +<para>Note that the DVB video device only controls decoding of the MPEG video stream, not +its presentation on the TV or computer screen. On PCs this is typically handled by an +associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output +windows. +</para> +<para>Some DVB cards don’t have their own MPEG decoder, which results in the omission of +the audio and video device as well as the video4linux device. +</para> +<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only +supported on some MPEG decoders made for DVD playback. +</para> +<section id="video_types"> +<title>Video Data Types</title> + +<section id="video_format_t"> +<title>video_format_t</title> +<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by +</para> +<programlisting> + typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9 + } video_format_t; +</programlisting> +<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio +the output hardware (e.g. TV) has. It is also used in the data structures video_status +(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by +VIDEO_GET_EVENT (??) which report about the display format of the current video +stream. +</para> +</section> + +<section id="video_display_format_t"> +<title>video_display_format_t</title> +<para>In case the display format of the video stream and of the display hardware differ the +application has to specify how to handle the cropping of the picture. This can be done using +the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts +</para> +<programlisting> + typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT + } video_display_format_t; +</programlisting> +<para>as argument. +</para> +</section> + +<section id="video_stream_source"> +<title>video stream source</title> +<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take +the following values, depending on whether we are replaying from an internal (demuxer) or +external (user write) source. +</para> +<programlisting> + typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY + } video_stream_source_t; +</programlisting> +<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the +DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY +is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system +call. +</para> +</section> + +<section id="video_play_state"> +<title>video play state</title> +<para>The following values can be returned by the VIDEO_GET_STATUS call representing the +state of video playback. +</para> +<programlisting> + typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED + } video_play_state_t; +</programlisting> +</section> + +<section id="video_event"> +<title>struct video_event</title> +<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT +call. +</para> +<programlisting> + struct video_event { + int32_t type; + time_t timestamp; + union { + video_format_t video_format; + } u; + }; +</programlisting> +</section> + +<section id="video_status"> +<title>struct video_status</title> +<para>The VIDEO_GET_STATUS call returns the following structure informing about various +states of the playback operation. +</para> +<programlisting> + struct video_status { + boolean video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; + }; +</programlisting> +<para>If video_blank is set video will be blanked out if the channel is changed or if playback is +stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is +currently frozen, stopped, or being played back. The stream_source corresponds to the seleted +source for the video stream. It can come either from the demultiplexer or from memory. +The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently +played video stream. Finally, display_format corresponds to the selected cropping +mode in case the source video format is not the same as the format of the output +device. +</para> +</section> + +<section id="video_still_picture"> +<title>struct video_still_picture</title> +<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the +following structure. +</para> +<programlisting> + /⋆ pointer to and size of a single iframe in memory ⋆/ + struct video_still_picture { + char ⋆iFrame; + int32_t size; + }; +</programlisting> +</section> + +<section id="video_caps"> +<title>video capabilities</title> +<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following +bits set according to the hardwares capabilities. +</para> +<programlisting> + /⋆ bit definitions for capabilities: ⋆/ + /⋆ can the hardware decode MPEG1 and/or MPEG2? ⋆/ + #define VIDEO_CAP_MPEG1 1 + #define VIDEO_CAP_MPEG2 2 + /⋆ can you send a system and/or program stream to video device? + (you still have to open the video and the audio device but only + send the stream to the video device) ⋆/ + #define VIDEO_CAP_SYS 4 + #define VIDEO_CAP_PROG 8 + /⋆ can the driver also handle SPU, NAVI and CSS encoded data? + (CSS API is not present yet) ⋆/ + #define VIDEO_CAP_SPU 16 + #define VIDEO_CAP_NAVI 32 + #define VIDEO_CAP_CSS 64 +</programlisting> +</section> + +<section id="video_system"> +<title>video system</title> +<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The +following system types can be set: +</para> +<programlisting> + typedef enum { + VIDEO_SYSTEM_PAL, + VIDEO_SYSTEM_NTSC, + VIDEO_SYSTEM_PALN, + VIDEO_SYSTEM_PALNc, + VIDEO_SYSTEM_PALM, + VIDEO_SYSTEM_NTSC60, + VIDEO_SYSTEM_PAL60, + VIDEO_SYSTEM_PALM60 + } video_system_t; +</programlisting> +</section> + +<section id="video_highlight"> +<title>struct video_highlight</title> +<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The +call expects the following format for that information: +</para> +<programlisting> + typedef + struct video_highlight { + boolean active; /⋆ 1=show highlight, 0=hide highlight ⋆/ + uint8_t contrast1; /⋆ 7- 4 Pattern pixel contrast ⋆/ + /⋆ 3- 0 Background pixel contrast ⋆/ + uint8_t contrast2; /⋆ 7- 4 Emphasis pixel-2 contrast ⋆/ + /⋆ 3- 0 Emphasis pixel-1 contrast ⋆/ + uint8_t color1; /⋆ 7- 4 Pattern pixel color ⋆/ + /⋆ 3- 0 Background pixel color ⋆/ + uint8_t color2; /⋆ 7- 4 Emphasis pixel-2 color ⋆/ + /⋆ 3- 0 Emphasis pixel-1 color ⋆/ + uint32_t ypos; /⋆ 23-22 auto action mode ⋆/ + /⋆ 21-12 start y ⋆/ + /⋆ 9- 0 end y ⋆/ + uint32_t xpos; /⋆ 23-22 button color number ⋆/ + /⋆ 21-12 start x ⋆/ + /⋆ 9- 0 end x ⋆/ + } video_highlight_t; +</programlisting> + +</section> +<section id="video_spu"> +<title>video SPU</title> +<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the +following format: +</para> +<programlisting> + typedef + struct video_spu { + boolean active; + int stream_id; + } video_spu_t; +</programlisting> + +</section> +<section id="video_spu_palette"> +<title>video SPU palette</title> +<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: +</para> +<programlisting> + typedef + struct video_spu_palette{ + int length; + uint8_t ⋆palette; + } video_spu_palette_t; +</programlisting> + +</section> +<section id="video_navi_pack"> +<title>video NAVI pack</title> +<para>In order to get the navigational data the following structure has to be passed to the ioctl +VIDEO_GET_NAVI: +</para> +<programlisting> + typedef + struct video_navi_pack{ + int length; /⋆ 0 ... 1024 ⋆/ + uint8_t data[1024]; + } video_navi_pack_t; +</programlisting> +</section> + + +<section id="video_attributes"> +<title>video attributes</title> +<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: +</para> +<programlisting> + typedef uint16_t video_attributes_t; + /⋆ bits: descr. ⋆/ + /⋆ 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) ⋆/ + /⋆ 13-12 TV system (0=525/60, 1=625/50) ⋆/ + /⋆ 11-10 Aspect ratio (0=4:3, 3=16:9) ⋆/ + /⋆ 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca ⋆/ + /⋆ 7 line 21-1 data present in GOP (1=yes, 0=no) ⋆/ + /⋆ 6 line 21-2 data present in GOP (1=yes, 0=no) ⋆/ + /⋆ 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 ⋆/ + /⋆ 2 source letterboxed (1=yes, 0=no) ⋆/ + /⋆ 0 film/camera mode (0=camera, 1=film (625/50 only)) ⋆/ +</programlisting> +</section></section> + + +<section id="video_function_calls"> +<title>Video Function Calls</title> + + +<section id="video_fopen"> +<title>open()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) + for subsequent use.</para> +<para>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 attempts to open the device in this mode will fail, and an + error-code 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.</para> +</entry> + </row></tbody></tgroup></informaltable> + +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int open(const char ⋆deviceName, int flags);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>const char + *deviceName</para> +</entry><entry + align="char"> +<para>Name of specific video device.</para> +</entry> + </row><row><entry + align="char"> +<para>int flags</para> +</entry><entry + align="char"> +<para>A bit-wise OR of the following flags:</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDONLY read-only access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_RDWR read/write access</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>O_NONBLOCK open in non-blocking mode</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>(blocking mode is the default)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>ENODEV</para> +</entry><entry + align="char"> +<para>Device driver not loaded/available.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EBUSY</para> +</entry><entry + align="char"> +<para>Device or resource busy.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid argument.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="video_fclose"> +<title>close()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call closes a previously opened video device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int close(int fd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section> +<section id="video_fwrite"> +<title>write()</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected + in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in + PES format, unless the capability allows other formats. 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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>size_t write(int fd, const void ⋆buf, size_t count);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>void *buf</para> +</entry><entry + align="char"> +<para>Pointer to the buffer containing the PES data.</para> +</entry> + </row><row><entry + align="char"> +<para>size_t count</para> +</entry><entry + align="char"> +<para>Size of buf.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>ENOMEM</para> +</entry><entry + align="char"> +<para>Attempted to write more data than the internal buffer can + hold.</para> +</entry> + </row><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_STOP</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_STOP, boolean + mode);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_STOP for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>Boolean mode</para> +</entry><entry + align="char"> +<para>Indicates how the screen shall be handled.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>TRUE: Blank screen when stop.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE: Show last decoded frame.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_PLAY</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to start playing a video stream from the + selected source.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_PLAY);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_PLAY for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_FREEZE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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 the 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_CONTINUE or VIDEO_PLAY is performed.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_FREEZE);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_FREEZE for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_CONTINUE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call restarts decoding and playing processes of the video stream + which was played before a call to VIDEO_FREEZE was made.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_CONTINUE for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SELECT_SOURCE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call informs the video device which source shall be used for the input + data. The possible sources are demux or memory. If memory is selected, the + data is fed to the video device through the write command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE, + video_stream_source_t source);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SELECT_SOURCE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_stream_source_t + source</para> +</entry><entry + align="char"> +<para>Indicates which source shall be used for the Video stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_BLANK</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to blank out the picture.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean + mode);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_BLANK for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>boolean mode</para> +</entry><entry + align="char"> +<para>TRUE: Blank screen when stop.</para> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>FALSE: Show last decoded frame.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal input parameter</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_GET_STATUS</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to return the current status of the device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct + video_status ⋆status);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_STATUS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct video_status + *status</para> +</entry><entry + align="char"> +<para>Returns the current status of the Video Device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error, possibly in the communication with the + DVB subsystem.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>status points to invalid address</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_GET_EVENT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call returns an event of type video_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. Read-only + permissions are sufficient for this ioctl call.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct + video_event ⋆ev);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_EVENT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct video_event + *ev</para> +</entry><entry + align="char"> +<para>Points to the location where the event, if any, is to be + stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>ev points to invalid address</para> +</entry> + </row><row><entry + align="char"> +<para>EWOULDBLOCK</para> +</entry><entry + align="char"> +<para>There is no event pending, and the device is in + non-blocking mode.</para> +</entry> + </row><row><entry + align="char"> +<para>EOVERFLOW</para> +</entry><entry + align="char"> +</entry> + </row><row><entry + align="char"> +</entry><entry + align="char"> +<para>Overflow in event queue - one or more events were lost.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to select the video format to be applied + by the MPEG chip on the video.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = + VIDEO_SET_DISPLAY_FORMAT, video_display_format_t + format);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_DISPLAY_FORMAT for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_display_format_t + format</para> +</entry><entry + align="char"> +<para>Selects the video format to be used.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal parameter format.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_STILLPICTURE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_STILLPICTURE, + struct video_still_picture ⋆sp);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_STILLPICTURE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct + video_still_picture + *sp</para> +</entry><entry + align="char"> +<para>Pointer to a location where an I-frame and size is stored.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>sp points to an invalid iframe.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_FAST_FORWARD</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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_MEMORY is selected.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int + nFrames);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_FAST_FORWARD for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int nFrames</para> +</entry><entry + align="char"> +<para>The number of frames to skip.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal parameter format.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SLOWMOTION</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>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.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int + nFrames);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SLOWMOTION for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int nFrames</para> +</entry><entry + align="char"> +<para>The number of times to repeat each frame.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EPERM</para> +</entry><entry + align="char"> +<para>Mode VIDEO_SOURCE_MEMORY not selected.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Illegal parameter format.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_GET_CAPABILITIES</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the video device about its decoding capabilities. On success + it returns and integer which has bits set according to the defines in section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, + unsigned int ⋆cap);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_CAPABILITIES for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned int *cap</para> +</entry><entry + align="char"> +<para>Pointer to a location where to store the capability + information.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>cap points to an invalid iframe.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_ID</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl selects which sub-stream is to be decoded if a program or system + stream is sent to the video device.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = VIDEO_SET_ID, int + id);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_ID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int id</para> +</entry><entry + align="char"> +<para>video sub-stream id</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINTERNAL</para> +</entry><entry + align="char"> +<para>Internal error.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>Invalid sub-stream id.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_CLEAR_BUFFER</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_CLEAR_BUFFER for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_STREAMTYPE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl tells the driver which kind of stream to expect being written to it. If + this call is not used the default of video PES is used. Some drivers might not + support this call and always expect PES.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, + int type);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_STREAMTYPE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>int type</para> +</entry><entry + align="char"> +<para>stream type</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>type is not a valid or supported stream type.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_FORMAT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the screen format (aspect ratio) of the connected output device + (TV) so that the output of the decoder can be adjusted accordingly.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_FORMAT, + video_format_t format);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_FORMAT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_format_t + format</para> +</entry><entry + align="char"> +<para>video format of TV as defined in section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>format is not a valid video format.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_SYSTEM</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the television output format. The format (see section ??) may + vary from the color format of the displayed MPEG stream. If the hardware is + not able to display the requested format the call will return an error.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM , + video_system_t system);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_FORMAT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_system_t + system</para> +</entry><entry + align="char"> +<para>video system of TV output.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>system is not a valid or supported video system.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_HIGHLIGHT</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT + ,video_highlight_t ⋆vhilite)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_highlight_t + *vhilite</para> +</entry><entry + align="char"> +<para>SPU Highlight information according to section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor.</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid highlight setting.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_SPU</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can + only be used, if the driver is able to handle a DVD stream.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_SPU , + video_spu_t ⋆spu)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_SPU for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_spu_t *spu</para> +</entry><entry + align="char"> +<para>SPU decoding (de)activation and subid setting according + to section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid spu setting or driver cannot handle + SPU.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_SPU_PALETTE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl sets the SPU color palette.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE + ,video_spu_palette_t ⋆palette )</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_spu_palette_t + *palette</para> +</entry><entry + align="char"> +<para>SPU palette according to section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid palette or driver doesn’t handle SPU.</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_GET_NAVI</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl returns navigational information from the DVD stream. This is + especially needed if an encoded stream has to be decoded by the hardware.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_GET_NAVI , + video_navi_pack_t ⋆navipack)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_NAVI for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_navi_pack_t + *navipack</para> +</entry><entry + align="char"> +<para>PCI or DSI pack (private stream 2) according to section + ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EFAULT</para> +</entry><entry + align="char"> +<para>driver is not able to return navigational information</para> +</entry> + </row></tbody></tgroup></informaltable> + +</section><section +role="subsection"><title>VIDEO_SET_ATTRIBUTES</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is intended for DVD playback and allows you to set certain + information about the stream. Some hardware may not need this information, + but the call also tells the hardware to prepare for DVD playback.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE + ,video_attributes_t vattr)</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_attributes_t + vattr</para> +</entry><entry + align="char"> +<para>video attributes according to section ??.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>ERRORS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>EBADF</para> +</entry><entry + align="char"> +<para>fd is not a valid open file descriptor</para> +</entry> + </row><row><entry + align="char"> +<para>EINVAL</para> +</entry><entry + align="char"> +<para>input is not a valid attribute setting.</para> +</entry> + </row></tbody></tgroup></informaltable> + </section></section>
\ No newline at end of file |