diff options
Diffstat (limited to 'Documentation/DocBook/dvb')
| -rw-r--r-- | Documentation/DocBook/dvb/.gitignore | 1 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/audio.xml | 1473 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/ca.xml | 221 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/demux.xml | 973 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/dvbapi.xml | 87 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/dvbstb.pdf | bin | 0 -> 1881 bytes | |||
| -rw-r--r-- | Documentation/DocBook/dvb/dvbstb.png | bin | 0 -> 22655 bytes | |||
| -rw-r--r-- | Documentation/DocBook/dvb/examples.xml | 365 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/frontend.xml | 1766 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/intro.xml | 191 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/isdbt.xml | 314 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/kdapi.xml | 2309 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/net.xml | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/dvb/video.xml | 1971 |
14 files changed, 9683 insertions, 0 deletions
diff --git a/Documentation/DocBook/dvb/.gitignore b/Documentation/DocBook/dvb/.gitignore new file mode 100644 index 000000000000..d7ec32eafac9 --- /dev/null +++ b/Documentation/DocBook/dvb/.gitignore @@ -0,0 +1 @@ +!*.xml diff --git a/Documentation/DocBook/dvb/audio.xml b/Documentation/DocBook/dvb/audio.xml new file mode 100644 index 000000000000..eeb96b8a0864 --- /dev/null +++ b/Documentation/DocBook/dvb/audio.xml @@ -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/Documentation/DocBook/dvb/ca.xml b/Documentation/DocBook/dvb/ca.xml new file mode 100644 index 000000000000..b1f1d2fad654 --- /dev/null +++ b/Documentation/DocBook/dvb/ca.xml @@ -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> diff --git a/Documentation/DocBook/dvb/demux.xml b/Documentation/DocBook/dvb/demux.xml new file mode 100644 index 000000000000..1b8c4e9835b9 --- /dev/null +++ b/Documentation/DocBook/dvb/demux.xml @@ -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> diff --git a/Documentation/DocBook/dvb/dvbapi.xml b/Documentation/DocBook/dvb/dvbapi.xml new file mode 100644 index 000000000000..4fc5b23470a3 --- /dev/null +++ b/Documentation/DocBook/dvb/dvbapi.xml @@ -0,0 +1,87 @@ +<partinfo> +<authorgroup> +<author> +<firstname>Ralph</firstname> +<surname>Metzler</surname> +<othername role="mi">J. K.</othername> +<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> +</author> +<author> +<firstname>Marcus</firstname> +<surname>Metzler</surname> +<othername role="mi">O. C.</othername> +<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation> +</author> +<author> +<firstname>Mauro</firstname> +<surname>Chehab</surname> +<othername role="mi">Carvalho</othername> +<affiliation><address><email>mchehab@redhat.com</email></address></affiliation> +<contrib>Ported document to Docbook XML.</contrib> +</author> +</authorgroup> +<copyright> + <year>2002</year> + <year>2003</year> + <year>2009</year> + <holder>Convergence GmbH</holder> +</copyright> + +<revhistory> +<!-- Put document revisions here, newest first. --> +<revision> +<revnumber>2.0.1</revnumber> +<date>2009-09-16</date> +<authorinitials>mcc</authorinitials> +<revremark> +Added ISDB-T test originally written by Patrick Boettcher +</revremark> +</revision> +<revision> +<revnumber>2.0.0</revnumber> +<date>2009-09-06</date> +<authorinitials>mcc</authorinitials> +<revremark>Conversion from LaTex to DocBook XML. The + contents is the same as the original LaTex version.</revremark> +</revision> +<revision> +<revnumber>1.0.0</revnumber> +<date>2003-07-24</date> +<authorinitials>rjkm</authorinitials> +<revremark>Initial revision on LaTEX.</revremark> +</revision> +</revhistory> +</partinfo> + + +<title>LINUX DVB API</title> +<subtitle>Version 3</subtitle> +<!-- ADD THE CHAPTERS HERE --> + <chapter id="dvb_introdution"> + &sub-intro; + </chapter> + <chapter id="dvb_frontend"> + &sub-frontend; + </chapter> + <chapter id="dvb_demux"> + &sub-demux; + </chapter> + <chapter id="dvb_video"> + &sub-video; + </chapter> + <chapter id="dvb_audio"> + &sub-audio; + </chapter> + <chapter id="dvb_ca"> + &sub-ca; + </chapter> + <chapter id="dvb_net"> + &sub-net; + </chapter> + <chapter id="dvb_kdapi"> + &sub-kdapi; + </chapter> + <chapter id="dvb_examples"> + &sub-examples; + </chapter> +<!-- END OF CHAPTERS --> diff --git a/Documentation/DocBook/dvb/dvbstb.pdf b/Documentation/DocBook/dvb/dvbstb.pdf Binary files differnew file mode 100644 index 000000000000..0fa75d90c3eb --- /dev/null +++ b/Documentation/DocBook/dvb/dvbstb.pdf diff --git a/Documentation/DocBook/dvb/dvbstb.png b/Documentation/DocBook/dvb/dvbstb.png Binary files differnew file mode 100644 index 000000000000..9b8f372e7afd --- /dev/null +++ b/Documentation/DocBook/dvb/dvbstb.png diff --git a/Documentation/DocBook/dvb/examples.xml b/Documentation/DocBook/dvb/examples.xml new file mode 100644 index 000000000000..f037e568eb6e --- /dev/null +++ b/Documentation/DocBook/dvb/examples.xml @@ -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 <ulink url="http://linuxtv.org/hg/dvb-apps" />. +</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> diff --git a/Documentation/DocBook/dvb/frontend.xml b/Documentation/DocBook/dvb/frontend.xml new file mode 100644 index 000000000000..9d89a7b94fd5 --- /dev/null +++ b/Documentation/DocBook/dvb/frontend.xml @@ -0,0 +1,1766 @@ +<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 +<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</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 id="frontend_types"> +<title>Frontend Data Types</title> + +<section id="frontend_type"> +<title>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 id="frontend_caps"> +<title>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 id="frontend_info"> +<title>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 id="frontend_diseqc"> +<title>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>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 id="frontend_diseqc_slave_reply"> +<title>diseqc slave reply</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 id="frontend_sec_tone"> +<title>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 id="frontend_sec_burst"> +<title>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> + +<para></para> +</section> + +<section id="frontend_status"> +<title>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 id="frontend_params"> +<title>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 an +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 <constant>QPSKParameters</constant> 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 <constant>QAMParameters</constant> 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 <constant>OFDMParamters</constant> 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 <constant>Frequency</constant> 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 +(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by +itself. +</para> +<para>The possible values for the <constant>FEC_inner</constant> 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 id="frontend_events"> +<title>frontend events</title> + <programlisting> + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; +</programlisting> + </section> +</section> + + +<section id="frontend_fcalls"> +<title>Frontend Function Calls</title> + +<section id="frontend_f_open"> +<title>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> +<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>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="frontend_f_close"> +<title>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 id="frontend_read_status"> +<title>FE_READ_STATUS</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 id="frontend_read_ber"> +<title>FE_READ_BER</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 id="frontend_read_snr"> +<title>FE_READ_SNR</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 id="frontend_read_signal_strength"> +<title>FE_READ_SIGNAL_STRENGTH</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 id="frontend_read_ub"> +<title>FE_READ_UNCORRECTED_BLOCKS</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 id="frontend_set_fe"> +<title>FE_SET_FRONTEND</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 id="frontend_get_fe"> +<title>FE_GET_FRONTEND</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 id="frontend_get_event"> +<title>FE_GET_EVENT</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 id="frontend_get_info"> +<title>FE_GET_INFO</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 id="frontend_diseqc_reset_overload"> +<title>FE_DISEQC_RESET_OVERLOAD</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 id="frontend_diseqc_send_master_cmd"> +<title>FE_DISEQC_SEND_MASTER_CMD</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 id="frontend_diseqc_recv_slave_reply"> +<title>FE_DISEQC_RECV_SLAVE_REPLY</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 id="frontend_diseqc_send_burst"> +<title>FE_DISEQC_SEND_BURST</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 id="frontend_set_tone"> +<title>FE_SET_TONE</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 id="fe_set_voltage"> +<title>FE_SET_VOLTAGE</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 id="frontend_enable_high_lnb_volt"> +<title>FE_ENABLE_HIGH_LNB_VOLTAGE</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> +&sub-isdbt; diff --git a/Documentation/DocBook/dvb/intro.xml b/Documentation/DocBook/dvb/intro.xml new file mode 100644 index 000000000000..0dc83f672ea2 --- /dev/null +++ b/Documentation/DocBook/dvb/intro.xml @@ -0,0 +1,191 @@ +<title>Introduction</title> + +<section id="requisites"> +<title>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 +<ulink url="http://www.dvb.org" /> and/or +<ulink url="http://www.etsi.org" />.</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 id="history"> +<title>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 +<ulink url="http://www.linuxtv.org/" /> 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 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> + +<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><xref linkend="stb_components" /> 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 id="dvb_devices"> +<title>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 id="include_files"> +<title>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> + diff --git a/Documentation/DocBook/dvb/isdbt.xml b/Documentation/DocBook/dvb/isdbt.xml new file mode 100644 index 000000000000..92855222fccb --- /dev/null +++ b/Documentation/DocBook/dvb/isdbt.xml @@ -0,0 +1,314 @@ +<section id="isdbt"> + <title>ISDB-T frontend</title> + <para>This section describes shortly what are the possible parameters in the Linux + DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb + demodulator:</para> + + <para>This ISDB-T/ISDB-Tsb API extension should reflect all information + needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible + that some very sophisticated devices won't need certain parameters to + tune.</para> + + <para>The information given here should help application writers to know how + to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para> + + <para>The details given here about ISDB-T and ISDB-Tsb are just enough to + basically show the dependencies between the needed parameter values, + but surely some information is left out. For more detailed information + see the following documents:</para> + + <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial + Television Broadcasting" and</para> + <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial + Television Broadcasting".</para> + + <para>In order to read this document one has to have some knowledge the + channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to + the reader that an ISDB-T channel consists of 13 segments, that it can + have up to 3 layer sharing those segments, and things like that.</para> + + <para>Parameters used by ISDB-T and ISDB-Tsb.</para> + + <section id="isdbt-parms"> + <title>Parameters that are common with DVB-T and ATSC</title> + + <section id="isdbt-freq"> + <title><constant>DTV_FREQUENCY</constant></title> + + <para>Central frequency of the channel.</para> + + <para>For ISDB-T the channels are usally transmitted with an offset of 143kHz. E.g. a + valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of + the channel which is 6MHz.</para> + + <para>As in ISDB-Tsb the channel consists of only one or three segments the + frequency step is 429kHz, 3*429 respectively. As for ISDB-T the + central frequency of the channel is expected.</para> + </section> + + <section id="isdbt-bw"> + <title><constant>DTV_BANDWIDTH_HZ</constant> (optional)</title> + + <para>Possible values:</para> + + <para>For ISDB-T it should be always 6000000Hz (6MHz)</para> + <para>For ISDB-Tsb it can vary depending on the number of connected segments</para> + + <para>Note: Hardware specific values might be given here, but standard + applications should not bother to set a value to this field as + standard demods are ignoring it anyway.</para> + + <para>Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from + other parameters (DTV_ISDBT_SB_SEGMENT_IDX, + DTV_ISDBT_SB_SEGMENT_COUNT).</para> + </section> + + <section id="isdbt-delivery-sys"> + <title><constant>DTV_DELIVERY_SYSTEM</constant></title> + + <para>Possible values: <constant>SYS_ISDBT</constant></para> + </section> + + <section id="isdbt-tx-mode"> + <title><constant>DTV_TRANSMISSION_MODE</constant></title> + + <para>ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called + 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para> + + <para>Possible values: <constant>TRANSMISSION_MODE_2K</constant>, <constant>TRANSMISSION_MODE_8K</constant>, + <constant>TRANSMISSION_MODE_AUTO</constant>, <constant>TRANSMISSION_MODE_4K</constant></para> + + <para>If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the + hardware will try to find the correct FFT-size (if capable) and will + use TMCC to fill in the missing parameters.</para> + + <para><constant>TRANSMISSION_MODE_4K</constant> is added at the same time as the other new parameters.</para> + </section> + + <section id="isdbt-guard-interval"> + <title><constant>DTV_GUARD_INTERVAL</constant></title> + + <para>Possible values: <constant>GUARD_INTERVAL_1_32</constant>, <constant>GUARD_INTERVAL_1_16</constant>, <constant>GUARD_INTERVAL_1_8</constant>, + <constant>GUARD_INTERVAL_1_4</constant>, <constant>GUARD_INTERVAL_AUTO</constant></para> + + <para>If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will + try to find the correct guard interval (if capable) and will use TMCC to fill + in the missing parameters.</para> + </section> + </section> + <section id="isdbt-new-parms"> + <title>ISDB-T only parameters</title> + + <section id="isdbt-part-rec"> + <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title> + + <para><constant>If DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether + the channel is in partial reception mode or not.</para> + + <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and + <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para> + + <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1' + <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel + is consisting of one segment and layer or three segments and two layers.</para> + + <para>Possible values: 0, 1, -1 (AUTO)</para> + </section> + + <section id="isdbt-sound-bcast"> + <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title> + + <para>This field represents whether the other DTV_ISDBT_*-parameters are + referring to an ISDB-T and an ISDB-Tsb channel. (See also + <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para> + + <para>Possible values: 0, 1, -1 (AUTO)</para> + </section> + + <section id="isdbt-sb-ch-id"> + <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title> + + <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> + + <para>(Note of the author: This might not be the correct description of the + <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical + background needed to program a device)</para> + + <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a + set of connected ISDB-Tsb channels. In this set of channels every + channel can be received independently. The number of connected + ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum + bandwidth available.</para> + + <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The + broadcaster has several possibilities to put those channels in the + air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8 + segments from position 1-8 to 5-13 or anything in between.</para> + + <para>The underlying layer of segments are subchannels: each segment is + consisting of several subchannels with a predefined IDs. A sub-channel + is used to help the demodulator to synchronize on the channel.</para> + + <para>An ISDB-T channel is always centered over all sub-channels. As for + the example above, in ISDB-Tsb it is no longer as simple as that.</para> + + <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the + sub-channel ID of the segment to be demodulated.</para> + + <para>Possible values: 0 .. 41, -1 (AUTO)</para> + </section> + + <section id="isdbt-sb-seg-idx"> + + <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title> + + <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> + + <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be + demodulated for an ISDB-Tsb channel where several of them are + transmitted in the connected manner.</para> + + <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para> + + <para>Note: This value cannot be determined by an automatic channel search.</para> + </section> + + <section id="isdbt-sb-seg-cnt"> + <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title> + + <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para> + + <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb + channels.</para> + + <para>Possible values: 1 .. 13</para> + + <para>Note: This value cannot be determined by an automatic channel search.</para> + </section> + + <section id="isdb-hierq-layers"> + <title>Hierarchical layers</title> + + <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in + ISDB-T hierarchical layers can be decoded simultaneously. For that + reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para> + + <para>ISDB-T has 3 hierarchical layers which each can use a part of the + available segments. The total number of segments over all layers has + to 13 in ISDB-T.</para> + + <section id="isdbt-layer-ena"> + <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title> + + <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling + layers in the decoding process. Setting all bits of + <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be + demodulated. This is the default.</para> + + <para>If the channel is in the partial reception mode + (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded + independently of the other 12 segments. In that mode layer A has to + have a <constant>SEGMENT_COUNT</constant> of 1.</para> + + <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb + according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled + accordingly.</para> + + <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para> + + <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para> + <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para> + <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para> + <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para> + </section> + + <section id="isdbt-layer-fec"> + <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title> + + <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para> + </section> + + <section id="isdbt-layer-mod"> + <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title> + + <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para> + + <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant> + and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para> + </section> + + <section id="isdbt-layer-seg-cnt"> + <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title> + + <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para> + + <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and + <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para> + + <informaltable id="isdbt-layer_seg-cnt-table"> + <tgroup cols="6"> + + <tbody> + <row> + <entry>PR</entry> + <entry>SB</entry> + <entry>Layer A width</entry> + <entry>Layer B width</entry> + <entry>Layer C width</entry> + <entry>total width</entry> + </row> + + <row> + <entry>0</entry> + <entry>0</entry> + <entry>1 .. 13</entry> + <entry>1 .. 13</entry> + <entry>1 .. 13</entry> + <entry>13</entry> + </row> + + <row> + <entry>1</entry> + <entry>0</entry> + <entry>1</entry> + <entry>1 .. 13</entry> + <entry>1 .. 13</entry> + <entry>13</entry> + </row> + + <row> + <entry>0</entry> + <entry>1</entry> + <entry>1</entry> + <entry>0</entry> + <entry>0</entry> + <entry>1</entry> + </row> + + <row> + <entry>1</entry> + <entry>1</entry> + <entry>1</entry> + <entry>2</entry> + <entry>0</entry> + <entry>13</entry> + </row> + </tbody> + + </tgroup> + </informaltable> + + </section> + + <section id="isdbt_layer_t_interl"> + <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title> + + <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para> + + <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values + here are referring to what can be found in the TMCC-structure - + independent of the mode.</para> + </section> + </section> + </section> +</section> diff --git a/Documentation/DocBook/dvb/kdapi.xml b/Documentation/DocBook/dvb/kdapi.xml new file mode 100644 index 000000000000..6c67481eaa4b --- /dev/null +++ b/Documentation/DocBook/dvb/kdapi.xml @@ -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> diff --git a/Documentation/DocBook/dvb/net.xml b/Documentation/DocBook/dvb/net.xml new file mode 100644 index 000000000000..94e388d94c0d --- /dev/null +++ b/Documentation/DocBook/dvb/net.xml @@ -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> diff --git a/Documentation/DocBook/dvb/video.xml b/Documentation/DocBook/dvb/video.xml new file mode 100644 index 000000000000..7bb287e67c8e --- /dev/null +++ b/Documentation/DocBook/dvb/video.xml @@ -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> |
