From 38d73cf52c0df17ed6f3c7c505e2ab06b04e3b2f Mon Sep 17 00:00:00 2001 From: cvs Date: Wed, 18 Oct 2000 20:20:47 -0200 Subject: added HTML documentation of new API --- dvb-spec/API/dvb_api.xml | 233 +++++++ dvb-spec/API/dvb_api/audio.h | 69 ++ dvb-spec/API/dvb_api/audio.xml | 571 +++++++++++++++++ dvb-spec/API/dvb_api/demux.h | 295 +++++++++ dvb-spec/API/dvb_api/demux.xml | 568 +++++++++++++++++ dvb-spec/API/dvb_api/demux_mod.xml | 1215 ++++++++++++++++++++++++++++++++++++ dvb-spec/API/dvb_api/dmx.h | 130 ++++ dvb-spec/API/dvb_api/frontend.h | 96 +++ dvb-spec/API/dvb_api/frontend.xml | 843 +++++++++++++++++++++++++ dvb-spec/API/dvb_api/sec.h | 116 ++++ dvb-spec/API/dvb_api/sec.xml | 430 +++++++++++++ dvb-spec/API/dvb_api/video.h | 95 +++ dvb-spec/API/dvb_api/video.xml | 666 ++++++++++++++++++++ 13 files changed, 5327 insertions(+) create mode 100644 dvb-spec/API/dvb_api.xml create mode 100644 dvb-spec/API/dvb_api/audio.h create mode 100644 dvb-spec/API/dvb_api/audio.xml create mode 100644 dvb-spec/API/dvb_api/demux.h create mode 100644 dvb-spec/API/dvb_api/demux.xml create mode 100644 dvb-spec/API/dvb_api/demux_mod.xml create mode 100644 dvb-spec/API/dvb_api/dmx.h create mode 100644 dvb-spec/API/dvb_api/frontend.h create mode 100644 dvb-spec/API/dvb_api/frontend.xml create mode 100644 dvb-spec/API/dvb_api/sec.h create mode 100644 dvb-spec/API/dvb_api/sec.xml create mode 100644 dvb-spec/API/dvb_api/video.h create mode 100644 dvb-spec/API/dvb_api/video.xml (limited to 'dvb-spec/API') diff --git a/dvb-spec/API/dvb_api.xml b/dvb-spec/API/dvb_api.xml new file mode 100644 index 000000000..bd2302551 --- /dev/null +++ b/dvb-spec/API/dvb_api.xml @@ -0,0 +1,233 @@ + + + linuxtv.org|Linux DVB API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

Linux DVB API

 + +

+ Part of the DVB API builds upon the + Video4Linux + (V4L) API. + The Siemens DVB card uses the SAA7146 as PCI bridge. A generic SAA7146 Linux driver for this + chip implements the basic V4L interface. +

+ +

+ An older version of the API included the DVB specific calls + into the V4L interface. This turned out to be very cumbersome to + program. Since we also hoped to arrive at a common standard for all + Linux platforms, especially those in embedded consumer devices, we + were happy to find + Nokia + as a partner in this effort. + They will be using the same API in their upcoming + + Media Terminal. +

+ +

+ In the new version of the API only display and grabbing of the + already decompressed images is handled through the V4L device. + All other DVB features like tuning, filtering and playback/recording + of the compressed data stream are accessed through separate devices. +

+ +

+ DVB devices + +

+ There are currently 5 DVB devices: Video, Audio, Frontend, SEC and Demux. + The APIs of those devices are described in the documents below. + They contain links to the include files and to detailed descriptions + of all commands (the latter are still under construction). +

+ +

+ DVB Video API +

+ +

+ DVB Audio API +

+ +

+ DVB Frontend API +

+ +

+ DVB SEC API +

+ +

+ DVB Demux API +

+ +

+ + +

+ DVB Demux Kernel Module + +

+ The demux device accesses the actual demux hardware through a + demux kernel module. + This way other kernel modules (e.g. a generic DVB network device) + and not only the demux device can access the demux hardware. +

+ +

+ DVB Demux Kernel Module API +

+ +

+ + +

+ First implementations of the API for the Siemens DVB card will be made + available in the download section during September 2000. +

+ +
+ + diff --git a/dvb-spec/API/dvb_api/audio.h b/dvb-spec/API/dvb_api/audio.h new file mode 100644 index 000000000..8a98f2f98 --- /dev/null +++ b/dvb-spec/API/dvb_api/audio.h @@ -0,0 +1,69 @@ +/* + * audio.h + * + * Copyright (C) 2000 Ralph Metzler + * & Marcus Metzler + for convergence integrated media GmbH + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + */ + +#ifndef _OST_AUDIO_H_ +#define _OST_AUDIO_H_ + +#define boolean int +#define true 1 +#define false 0 + +typedef enum { + AUDIO_SOURCE_DEMUX, /* Select the demux as the main source */ + AUDIO_SOURCE_MEMORY /* Select internal memory as the main source */ +} audioStreamSource_t; + +typedef enum { + AUDIO_STOPPED, /* Device is stopped */ + AUDIO_PLAYING, /* Device is currently playing */ + AUDIO_PAUSED /* Device is paused */ +} audioPlayState_t; + +typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, +} audioChannelSelect_t; + +struct audioStatus { + boolean AVSyncState; + boolean muteState; + audioPlayState_t playState; + audioStreamSource_t streamSource; + audioChannelSelect_t channelSelect; + boolean bypassMode; +}; + + +#define AUDIO_STOP _IOW('o',1,void) +#define AUDIO_PLAY _IOW('o',2,void) +#define AUDIO_PAUSE _IOW('o',3,void) +#define AUDIO_CONTINUE _IOW('o',4,void) +#define AUDIO_SELECT_SOURCE _IOW('o',5,audioStreamSource_t) +#define AUDIO_SET_MUTE _IOW('o',6,boolean) +#define AUDIO_SET_AV_SYNC _IOW('o',7,boolean) +#define AUDIO_SET_BYPASS_MODE _IOW('o',8,boolean) +#define AUDIO_CHANNEL_SELECT _IOW('o',9,audioChannelSelect_t) +#define AUDIO_GET_STATUS _IOR('o',10,struct audioStatus *) + +#endif /* _OST_AUDIO_H_ */ diff --git a/dvb-spec/API/dvb_api/audio.xml b/dvb-spec/API/dvb_api/audio.xml new file mode 100644 index 000000000..4d6f31575 --- /dev/null +++ b/dvb-spec/API/dvb_api/audio.xml @@ -0,0 +1,571 @@ + + + linuxtv.org|DVB Audio API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

DVB Audio API

 + +

+ The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. + It can be accessed through /dev/ost/audio. +

+ +

+ The function calls defined in the include file + audio.h are described in detail below: +

+

+ Audio API IO control calls + + +

+

+
+int open(const char *deviceName, int flags);
+
+    DESCRIPTION
+    
+	This system call opens a named audio device (e.g. /dev/ost/audio) for subsequent
+        use. When an open() call has succeeded, the device will be ready for use.
+        The significance of blocking or non-blocking mode is described in the 
+	documentation for functions where there is a difference. It does not affect 
+	the semantics of the open() call itself. A device opened in blocking mode can
+	later be put into non-blocking mode (and vice versa) using the F_SETFL command
+	of the fcntl system call.  This is a standard system call, documented in the 
+	Linux manual page for fcntl.
+        Only one user can open the Audio  Device in O_RDWR mode. All other attempts to
+        open the device in this mode will fail, and an errorcode will be returned.
+        If the Audio Device is opened in O_RDONLY mode, the only ioctl call that can 
+	be used is AUDIO_GET_STATUS. All other call will return with an error code.
+
+
+    PARAMETERS
+
+	const char *deviceName		Name of specific audio device.
+
+	int flags           		A bit-wise OR of the following flags:
+                                        
+					O_RDONLY read-only access
+
+                                        O_RDWR read/write access
+
+                                        O_NONBLOCK open in non-blocking mode
+                                                   (blocking mode is the default)
+
+    RETURNS
+
+	ENODEV                          Device driver not loaded/available.
+
+	EINTERNAL			Internal error
+
+        EBUSY                           Device or resource busy.
+
+        EINVAL                          Invalid argument.
+
+
+
+
+

+ +

+

+
+int close(int fd);
+
+    DESCRIPTION
+	
+	This system call closes a previously opened audio device
+
+    PARAMETERS
+	
+	int fd			File descriptor returned by a previous call to open().
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+
+size_t write(int fd, const void *buf, size_t count);
+
+    DESCRIPTION
+
+	This system call can only be used if AUDIO_SOURCE_MEMORY is selected in the 
+	ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in PES format.
+        If O_NONBLOCK is not specified the function will block until buffer space is
+	available. The amount of data to be transferred is implied by count.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	void *buf		Pointer to the buffer containing the PES data.
+
+	size_t count		Size of buf.
+
+    RETURNS
+
+	EPERM			Mode VIDEO_SOURCE_INTERNAL not selected.
+
+	ENOMEM			Attempted to write more data than the internal
+                                buffer can hold.
+
+	EBADF			fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_STOP);
+
+    DESCRIPTION
+
+	This ioctl call asks the Audio Device to stop playing the current stream.
+
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request             Equals AUDIO_STOP for this command.
+
+    RETURNS
+
+	EBADF                   fd is not a valid open file descriptor
+
+	EINTERNAL		Internal error
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_PLAY);
+
+    DESCRIPTION
+
+	This ioctl call asks the Audio Device to start playing an audio stream from the
+        selected source.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_PLAY for this command.
+
+    RETURNS
+	
+        EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL               Internal error
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_PAUSE);
+
+    DESCRIPTION
+
+	This ioctl call suspends the audio stream being played. Decoding and playing are
+	paused. It is then possible to restart again decoding and playing process of the
+        audio stream using AUDIO_CONTINUE command.
+        If  AUDIO_SOURCE_MEMORY is selected in the ioctl call AUDIO_SELECT_SOURCE, the
+        DVB-subsystem will not decode (consume) any more data until the ioctl  call
+        AUDIO_CONTINUE or AUDIO_PLAY is performed.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_PAUSE for this command.
+
+    RETURNS
+           
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_CONTINUE);
+
+    DESCRIPTION
+
+	This ioctl call restarts decoding and playing processes of the audio stream,
+	 which was played before, a call to AUDIO_PAUSE was made.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_CONTINUE for this command.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL               Internal error, possibly in the communication
+                                with the DVB subsystem.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audioStreamSource_t source);
+
+    DESCRIPTION
+
+	This ioctl call informs the audio device which source shall be used for the 
+	input data. The possible sources are demux or memory. If AUDIO_SOURCE_MEMORY 
+	is selected, the data is fed to the Audio Device through the write command.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_SELECT_SOURCE for this command.
+
+	audioStreamSource_t source	Indicates the source that shall be used for the
+             			        Audio stream.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state);
+
+    DESCRIPTION
+    
+	This ioctl call asks the audio device to mute the stream that is currently being
+        played.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_SET_MUTE for this command.
+
+	boolean state		Indicates if audio device shall mute or not.
+                                TRUE     Audio Mute
+                                FALSE   Audio Unmute
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error,
+
+        EINVAL                  Illegal input parameter.
+
+
+

+ +

+

+int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state);
+
+    DESCRIPTION
+
+	This ioctl call asks the Audio Device to turn ON or OFF A/V synchronisation.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_AV_SYNC for this command.
+
+	boolean state		Tells the DVB subsystem if A/V synchronisation shall be ON or OFF.
+                                TRUE    AV-sync ON
+                                FALSE  AV-sync OFF
+
+    RETURNS
+
+    	EBADF			fd is not a valid open file descriptor.
+        
+	EINTERNAL		Internal error
+
+	EINVAL                                  Illegal input parameter.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode);
+
+    DESCRIPTION
+
+	This ioctl call asks the Audio Device to bypass the Audio decoder and forward
+	the stream without decoding. This mode shall be used if streams that can't be
+	handled by the DVB system shall be decoded. Dolby DigitalTM streams are 
+	automatically forwarded by the DVB subsystem.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_SET_BYPASS_MODE for this command.
+
+	boolean mode		Enables or disables the decoding of the current
+                                Audio stream in the DVB subsystem.
+                                TRUE    Bypass is disabled
+                                FALSE  Bypass is enabled
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+        
+	EINTERNAL               Internal error
+
+        EINVAL                  Illegal pointer mode.
+
+
+
+

+ +

+

+int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audioChannelSelect_t)
+
+    DESCRIPTION
+    
+	This ioctl call asks the Audio Device to select the requested channel if possible.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals AUDIO_CHANNEL_SELECT for this command.
+
+	audioChannelSelect_t ch Select the output format of the audio (Mono, stereo)
+
+    RETURNS
+	
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+        EINVAL			Illegal pointer ch.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audioStatus *status)
+
+    DESCRIPTION
+
+	This ioctl call asks the Audio Device to return the current state of the Audio
+	Device.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+        int request		Equals AUDIO_GET_STATUS for this command.
+
+        struct audioStatus *status 	Returns the current state of Audio Device
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+        EFAULT			status points to invalid address
+
+
+
+
+

+ +

+
+ + diff --git a/dvb-spec/API/dvb_api/demux.h b/dvb-spec/API/dvb_api/demux.h new file mode 100644 index 000000000..62cbf0a58 --- /dev/null +++ b/dvb-spec/API/dvb_api/demux.h @@ -0,0 +1,295 @@ +/* * demux.h * * Copyright (c) 2000 Nokia Research Center + * Tampere, FINLAND + * + * Project: + * Universal Broadcast Access + * + * Contains: + * Type definitions of a Linux kernel-level API for filtering MPEG-2 TS + * packets and MPEG-2 sections. Support for PES packet filtering will be + * added later. + * + * History: + * 12.01.2000/JPL File created - Initial version. + * 18.02.2000/JPL Minor corrections. + * 21.02.2000/JPL DMX_NAME_SIZE and dmx_in_use() removed, typos fixed, + * some names changed. + * 23.02.2000/JPL Added a parameter indicating the callback source in + * the callback functions. + * 10.03.2000/JPL Added the macros DMX_DIR_ENTRY() and DMX_FE_ENTRY(). + * 15.03.2000/JPL Added the capabilities field to dmx_demux_t. + * 22.03.2000/JPL Corrected the callback parameter in the + * allocate_x_feed() functions. + * 03.04.2000/JPL Added support for optional resource conflict resolution + * and scarce resource handling. + * 05.04.2000/JPL Changed the dmx_resolve_conflict() to use resource + * type as a parameter. + * 12.04.2000/JPL Added a second buffer parameter for dmx_x_callback() + * functions to better handle buffer wrapping. + * 26.04.2000/JPL Added functions for section-level descrambling. + * 03.09.2000/JPL Removed support for conflict resolution and scarce + * resource handling. Otherwise only minor changes to + * data structures and function prototypes. + * + * + * Author: + * Juha-Pekka Luoma (JPL) + * Nokia Research Center + * + * Notes: + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + */ +/* $Id$ */ + +#ifndef __DEMUX_H +#define __DEMUX_H + +#ifndef __KERNEL__ +#define __KERNEL__ +#endif + +#include /* __u8, __u16, ... */ +#include /* list_entry(), struct list_head */ +#include /* struct timespec */ +#include /* Function return values */ + +/*--------------------------------------------------------------------------*/ +/* Common definitions */ +/*--------------------------------------------------------------------------*/ + +/* + * DMX_MAX_FILTER_SIZE: Maximum length (in bytes) of a section/PES filter. + */ + +#ifndef DMX_MAX_FILTER_SIZE +#define DMX_MAX_FILTER_SIZE 16 +#endif +/* + * dmx_success_t: Success codes for the Demux Callback API. + */ + +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; + +/*--------------------------------------------------------------------------*/ +/* TS packet reception */ +/*--------------------------------------------------------------------------*/ + +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); +}; +typedef struct dmx_ts_feed_s dmx_ts_feed_t; + +/*--------------------------------------------------------------------------*/ +/* PES packet reception (not supported yet) */ +/*--------------------------------------------------------------------------*/ + +typedef void dmx_pes_feed_t; +typedef void dmx_pes_filter_t; + +/*--------------------------------------------------------------------------*/ +/* Section reception */ +/*--------------------------------------------------------------------------*/ + +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; + +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 buffer_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_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_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 + +/* + * Demux resource type identifier. +*/ + +/* + * 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 capabilites; /* 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 (*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); +}; +typedef struct dmx_demux_s dmx_demux_t; + +/*--------------------------------------------------------------------------*/ +/* Demux directory */ +/*--------------------------------------------------------------------------*/ + +/* + * 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); + +#endif /* #ifndef __DEMUX_H */ + diff --git a/dvb-spec/API/dvb_api/demux.xml b/dvb-spec/API/dvb_api/demux.xml new file mode 100644 index 000000000..b15824d0b --- /dev/null +++ b/dvb-spec/API/dvb_api/demux.xml @@ -0,0 +1,568 @@ + + + linuxtv.org|DVB Demux API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

DVB Demux API

 + +

+ The DVB demux device lets you set TS, PID and section filters in the DVB + device. This is internally accomplished through calls to the + demux kernel module. + The demux device can be accessed through /dev/ost/demux. +

+ +

+ The function calls defined in the include file + dmx.h are described in detail below: +

+ +

+ Demux API IO control calls + +

+

+
+int open(const char *deviceName, int flags);
+ 
+    DESCRIPTION
+ 
+	This system call, used with a device name of /dev/ost/demuxn, where n 
+	denotes the specific demux device to be opened, allocates a new filter 
+	and returns a handle which can be used for subsequent control of that 
+	filter. This call has to be made for each filter to be used, i.e. every
+	returned file descriptor is a reference to a single filter.
+        /dev/ost/dvrn is a logical device to be used for retrieving Transport 
+	Streams for digital video recording. n identifies the physical demux 
+	device that provides the actual DVR functionlaity. When reading from  
+	this device a transport stream containing the packets from all PES
+	filters set in the corresponfing demux device (/dev/osst/demuxn)             	having the output set to DMX_OUT_TS_TAP.  A recorded Transport Stream 
+	is replayed by writing to this device.
+	This device can only be opened in read-write mode.
+        The significance of blocking or non-blocking mode is described in the
+	documentation for functions where there is a difference. It does not 
+	affect the semantics of the open() call itself. A device opened in 
+	blocking mode can later be put into non-blocking mode
+        (and vice versa) using the F_SETFL command of the fcntl system call.
+
+ 
+    PARAMETERS
+
+	const char *deviceName	     I Name of the demux device, which should be
+	                               /dev/ost/demuxn where  n denotes the
+                                       specific demux device to be opened, or the
+                                       name of a logical DVR device, /dev/ost/dvrn.
+
+	int flags                    I A bit-wise OR of the following flags:
+                                       O_RDWR read/write access.
+                                       O_NONBLOCK open in non-blocking mode
+                                                 (blocking mode is the default).
+
+    RETURNS
+    
+	ENODEV				Device driver not loaded/available.
+
+        EINVAL 	                        Invalid argument.
+
+        EMFILE                          "Too many open files", i.e. no more filters available.
+
+        ENOMEM                          The driver failed to allocate enough memory.
+
+
+
+
+

+ +

+

+
+int close(int fd);
+
+    DESCRIPTION
+
+	This system call deactivates and deallocates a filter that was previously
+	allocated via the open() call.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+
+size_t read(int fd, void *buf, size_t count);
+
+    DESCRIPTION
+
+	This system call returns filtered data, which might be section or PES 
+	data. The filtered data is transferred from the driver's internal circular
+	buffer to buf. The maximum amount of data to be transferred is implied by
+	count.
+
+        When returning section data the driver always tries to return a complete 
+	single section (even though buf would provide buffer space for more data).
+	If the size of the buffer is smaller than the section as much as possible
+	will be returned, and the remaining data will be provided in subsequent 
+	calls.
+        The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
+	sized sections) by default. The size of this buffer may be changed by 
+	using the DMX_SET_BUFFER_SIZE function. If the buffer is not large enough,
+	or if the read operations are not performed fast enough, this may result 
+	in a buffer overflow error. In this case EBUFFEROVERFLOW will be returned,
+	and the circular buffer will be emptied.
+        This call is blocking if there is no data to return, i.e. the process 
+	will be put to sleep waiting for data, unless the O_NONBLOCK flag is 
+	specified.
+        Note that in order to be able to read, the filtering process has to be
+	started by defining either a section or a PES filter by means of the 
+	ioctl functions, and then starting the filtering process via the DMX_START
+	ioctl function or by setting the DMX_IMMEDIATE_START flag.
+        If the reading is done from a logical DVR demux device, the data will 
+	constitute a Transport Stream including the packets from all PES filters
+	in the corresponding demux device /dev/ost/demuxn having the output set 
+	to DMX_OUT_TS_TAP.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+	void *buf             O Pointer to the buffer to be used for returned filtered data.
+
+	size_t count          I Size of buf.
+
+    RETURNS
+
+	EWOULDBLOCK		No data to return and O_NONBLOCK was specified.
+
+        EBADF                   fd is not a valid open file descriptor
+
+        ECRC                    Last section had a CRC error ­ no data
+	                        returned. The buffer is flushed.
+
+        EBUFFEROVERFLOW         The filtered data was not read from the buffer in
+                                due time, resulting in non-read data being lost.
+                                The buffer is flushed.
+
+        ETIMEDOUT               The section was not loaded within the stated
+                                timeout period. See ioctl DMX_SET_FILTER for
+                                how to set a timeout.
+
+        EFAULT                  The driver failed to write to the callers buffer
+				due to an invalid *buf pointer.
+
+
+
+
+

+ +

+

+
+ssize_t write(int fd, const void *buf, size_t count);
+
+    DESCRIPTION
+
+	This system call is only provided by the logical device /dev/ost/dvrn, 
+	where n identifies the physical demux device that provides the actual 
+	DVR  functionality.  It is used for replay of a digitally recorded 
+	Transport Stream. Matching filters have to be defined in the 
+	corresponding physical demux device, /dev/ost/demuxn.
+	The amount of data to be transferred is implied by count.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+	void *buf             I Pointer to the buffer containing the Transport Stream.
+
+        size_t count          I Size of buf.
+
+    RETURNS
+
+	EWOULDBLOCK             No data was written. This might happen if
+                                O_NONBLOCK was specified and there is no more
+                                buffer space available (if O_NONBLOCK is not
+                                specified the function will block until buffer 
+				space is available).
+
+	EBUSY                   This error code indicates that there are
+                                conflicting requests. The corresponding demux
+                                device is setup to receive data from the front-
+                                end. Make sure that these filters are stopped
+                                and that the filters with input set to DMX_IN_DVR
+                                are started.
+
+	EBADF                   fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = DMX_START);
+
+    DESCRIPTION
+
+	This ioctl call is used to start the actual filtering operation 
+	defined via the ioctl  calls DMX_SET_FILTER or DMX_SET_PES_FILTER.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+	int request           I Equals DMX_START for this command.
+
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor
+
+        EINVAL                  Invalid argument, i.e. no filtering parameters
+                                provided via the DMX_SET_FILTER or
+                                DMX_SET_PES_FILTER functions.
+
+        EBUSY                   This error code indicates that there are
+                                conflicting requests. There are active filters
+                                filtering data from another input source. Make
+                                sure that these filters are stopped before starting
+                                this filter.
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = DMX_STOP);
+
+    DESCRIPTION
+
+	This  ioctl call is used to stop the actual filtering operation defined 
+	via the ioctl  calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
+	the DMX_START command.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals DMX_STOP for this command.
+ 
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor
+
+
+

+ +

+

+
+int ioctl( int fd, int request = DMX_SET_FILTER, struct dmxSctFilterParams *params);
+
+    DESCRIPTION
+
+	This ioctl call sets up a filter according to the filter and mask 
+	parameters provided. A timeout may be defined stating number of seconds 
+	to wait for a section to be loaded. A value of 0 means that no timeout 
+	should be applied. Finally there is a flag field where it is possible to
+	state whether a section should be CRC-checked, whether the filter should
+        be a "one-shot" filter, i.e. if the filtering operation should be stopped
+	after the first section is received, and whether the filtering operation 
+	should be started immediately (without waiting for a DMX_START ioctl call).
+        If a filter was previously set-up, this filter will be cancelled, and the
+	receive buffer will be flushed.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals DMX_SET_FILTER for this command.
+
+        struct                I Pointer to structure containing filter
+
+        dmxSctFilterParams      parameters.
+               *params
+
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor
+
+        EINVAL                  Invalid argument.
+
+
+

+ +

+

+
+int ioctl( int fd, int request = DMX_SET_PES_FILTER, struct dmxPesFilterParams *params);
+
+    DESCRIPTION
+
+	This ioctl call sets up a PES filter according to the parameters provided.
+	By a PES filter is meant a filter that is based just on the packet 
+	identifier (PID), i.e. no PES header or payload filtering capability is 
+	supported.
+        The transport stream destination for the filtered output may be set. Also
+	the PES type may be stated in order to be able to e.g. direct a video 
+	stream directly to the video decoder. Finally there is a flag field where
+	it is possible to state whether the filtering operation should be started
+	immediately (without waiting for a DMX_START ioctl call).
+        If a filter was previously set-up, this filter will be cancelled, and the
+	receive buffer will be flushed.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+	int request           I Equals DMX_SET_PES_FILTER for this command.
+
+        struct                I Pointer to structure containing filter
+
+        dmxPesFilterParams      parameters.
+               *params
+
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor
+
+        EINVAL                  Invalid argument.
+
+        EBUSY                   This error code indicates that there are
+                                conflicting requests. There are active filters
+                                filtering data from another input source. Make
+                                sure that these filters are stopped before starting
+                                this filter.
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = DMX_SET_BUFFER_SIZE, unsigned long size);
+
+    DESCRIPTION
+
+	This ioctl call is used to set the size of the circular buffer used
+	for filtered data. The default size is two maximum sized sections, i.e. 
+	if this function is not called a buffer size of 2 * 4096 bytes will be
+	used.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals DMX_SET_BUFFER_SIZE for this command.
+
+        unsigned long size    I Size of circular buffer.
+
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor.
+
+        ENOMEM                  The driver was not able to allocate a buffer of the requested size.
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = DMX_GET_EVENT, struct dmxEvent *ev);
+
+    DESCRIPTION
+
+	This  ioctl call returns an event if available. If an event is not 
+	available, the behavior depends on whether the device is in blocking or 
+	non-blocking mode.  In the latter case, the call fails immediately with
+	errno set to EWOULDBLOCK. In the former case, the call blocks until an
+	event becomes available.
+        The standard Linux poll() and/or select() system calls can be used with
+	the device file descriptor to watch for new events.  For select(), the 
+	file descriptor should be included in the exceptfds argument, and for 
+	poll(), POLLPRI should be specified as the wake-up condition.
+        Only the latest event for each filter is saved.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+	int request           I Equals DMX_SET_BUFFER_SIZE for this command.
+
+        struct dmxEvent *ev   O Pointer to the location where the event is to be stored.
+
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor.
+        
+	EFAULT                  ev points to an invalid address.
+
+	EWOULDBLOCK             There is no event pending, and the device is in non-blocking mode.
+
+
+
+
+

+

+ +
+ + diff --git a/dvb-spec/API/dvb_api/demux_mod.xml b/dvb-spec/API/dvb_api/demux_mod.xml new file mode 100644 index 000000000..c36467977 --- /dev/null +++ b/dvb-spec/API/dvb_api/demux_mod.xml @@ -0,0 +1,1215 @@ + + + linuxtv.org|DVB Demux Kernel API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

DVB Demux Kernel API

 + +

+ The demux kernel API gives access to the demuxer of the DVB hardware + to other kernel modules which implement devices like the + demux device or generic DVB network devices. +

+ +

+ The function calls defined in the include file + demux.h are described in detail below: +

+ +

+ Demux Directory API + +

+ 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. +

+

+ All demux drivers in the directory implement the abstract interface dmx_demux_t. +

+ +

+

+int dmx_register_demux ( dmx_demux_t* demux )
+
+    Description
+
+	This function makes a demux driver interface available to the Linux kernel. 
+	It is usually called by the init_module() function of the kernel module that
+	contains the demux driver. The caller of this function is responsible for 
+	allocating dynamic or static memory for the demux structure and for initializing
+	its fields before calling this function. 
+	The memory allocated for the demux structure must not be freed before calling
+        dmx_unregister_demux(),
+
+    Returns
+    
+	0				The command was successfully performed.
+
+        -EEXIST                         A demux with the same value of the id field
+                                        already stored in the directory.
+
+        -ENOSPC                         No space left in the directory.
+
+
+
+
+

+

+

+
+int dmx_unregister_demux ( dmx_demux_t* demux )
+
+    Parameters
+
+	dmx_demux_t* demux	    I/O Pointer to the demux API and instance variables.
+
+    Description
+
+	This function is called to indicate that the given demux interface is no longer
+	available. The caller of this function is responsible for freeing the memory of
+	the demux structure, if it was dynamically allocated before calling 
+	dmx_register_demux().
+	The cleanup_module() function of the kernel module that contains the demux 
+	driver should call this function. Note that this function fails if the demux 
+	is currently in use, i.e., release_demux() has not been called for the 
+	interface.
+
+    Returns
+
+	0				The command was successfully performed.
+
+        -ENODEV                         No such demux registered.
+
+        -EBUSY                          Demux is currently in use.
+
+
+
+
+

+

+

+
+struct list_head* dmx_get_demuxes ()
+
+    Description
+
+	Provides the caller with the list of registered demux interfaces, using the 
+	standard list structure defined in the include file linux/list.h. 
+	The include file demux.h defines the macro DMX_DIR_ENTRY() for converting an 
+	element of the generic type struct list_head* to the type dmx_demux_t*.
+        The caller must not free the memory of any of the elements obtained via this
+	function call.
+
+    Returns
+
+	A list of demux interfaces, or NULL in the case of an empty list.
+
+
+
+
+

+

+ + +

+Demux API +

+ 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. +

+

+ Each demux receives its TS input from a DVB front-end or from the memory, as + set via the demux API. In a system with more than one front-end, the API can + be used to select one of the DVB front-ends as a TS source for a demux, unless + this is fixed in the HW platform. The demux API only controls front-ends + regarding their connections with demuxes; the APIs used to set the other + front-end parameters, such as tuning, are not defined in this document. +

+

+ The functions that implement the abstract interface demux_t should be defined + static or module private and registered to the Demux Directory for external + access. It is not necessary to implement every function in the demux_t struct, + however (for example, a demux interface might support Section filtering, but + not TS or PES filtering). The API client is expected to check the value of any + function pointer before calling the function: the value of NULL means "function + not available". +

+

+ 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. +

+

+ 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. +

+

+

+
+int open ( demux_t* demux )
+
+
+    Parameters
+    
+	demux_t* demux		      I Pointer to the demux API and instance data.
+
+    Description
+
+	This function reserves the demux for use by the caller and, if necessary, 
+	initializes the demux. When the demux is no longer needed, the function close()
+	should be called.
+        It should be possible for multiple clients to access the demux at the same time.
+	Thus, the function implementation should increment the demux usage count when 
+	open() is called and decrement it when close() is called.
+
+    Returns
+
+	0				The command was successfully performed.
+
+        -EUSERS                         Maximum usage count reached.
+
+        -EINVAL                         Bad parameter.
+
+
+
+
+

+

+

+
+int close ( demux_t* demux )
+
+    Parameters
+
+	demux_t* demux		      I Pointer to the demux API and instance data.
+
+    Description
+
+	The function is called to indicate that the API client does not need to use 
+	the demux anymore. As a result of this function, the demux usage count is 
+	decremented by one.
+        When the usage count drops to zero, any demux resources can be released.
+
+    Returns
+
+	0				The command was successfully performed.
+
+        -ENODEV                         The demux was not in use.
+
+        -EINVAL                         Bad parameter.
+
+
+
+
+

+

+

+
+int write ( demux_t* demux, const char* buf, size_t count)    
+
+    Parameters
+
+	demux_t* demux		    I/O Pointer to the demux API and instance data.
+
+        const char* buf               I Pointer to the TS data in kernel-space memory.
+
+        size_t length                 I Length of the TS data.
+
+
+
+    Description
+
+	This function provides the demux driver with a memory buffer containing TS 
+	packets. Instead of receiving TS packets from the DVB front-end, the demux 
+	driver software will read packets from the memory. Any clients of this demux 
+	with active TS, PES or Section filters will receive filtered data via the Demux
+	callback API (see 0). The function returns when all the data in the buffer has
+	been consumed by the demux.
+	Demux hardware typically cannot read TS from the memory. If this is the case,
+        memory-based filtering has to be implemented entirely in software.
+
+    Returns
+
+	0				The command was successfully performed.
+
+        -ENOSYS                         The command is not implemented.
+
+        -EINVAL                         Bad parameter.
+
+
+
+
+

+

+

+
+int allocate_ts_feed ( dmx_demux_t* demux, dmx_ts_feed_t** feed, dmx_ts_cb callback )
+
+    Parameters
+
+	demux_t* demux		    I/O Pointer to the demux API and instance data.
+
+        dmx_ts_feed_t** feed          O Pointer to the TS feed API and instance data.
+
+        dmx_ts_cb callback            I Pointer to the callback function for
+                                        passing received TS packet
+
+    Description
+
+	Allocates a new TS feed, which is used to filter the TS packets carrying a 
+	certain PID.
+        The TS feed normally corresponds to a hardware PID filter on the demux chip.
+
+    Returns
+
+	0				The command was successfully performed.
+
+        -EBUSY                          No more TS feeds available.
+ 
+	-ENOSYS                         The command is not implemented.
+
+        -EINVAL                         Bad parameters.
+
+
+
+
+

+

+

+int release_ts_feed ( dmx_demux_t* demux, dmx_ts_feed_t* feed)
+
+    Parameters
+
+             dmx_demux_t* demux                        I/O Pointer to the demux API and
+                                                             instance data.
+             dmx_ts_feed_t* feed                       I     Pointer to the TS feed API and
+                                                             instance data.
+
+            Function Detailed Description
+            Releases the resources allocated with allocate_ts_feed(). Any filtering in progress
+            on the TS feed should be stopped before calling this function.
+
+            Function Returns
+             0                                         The command was successfully performed.
+             -EINVAL                                   Bad parameters.
+
+
+

+

+

+allocate_pes_feed()
+
+            TBD
+
+
+
+
+

+

+

+release_pes_feed()
+
+            TBD
+
+
+
+
+

+

+

+int allocate_section_feed ( dmx_demux_t* demux,
+             dmx_section_feed_t** 
+                                                                            feed,
+                                                dmx_section_cb callback )
+
+            Function Parameters
+             demux_t* demux                            I/O Pointer to the demux API and
+                                                             instance data.
+             dmx_section_feed_t** feed                 O     Pointer to the section feed API and
+
+                                                                instance data.
+             dmx_section_cb callback                  I         Pointer to the callback function for
+                                                                passing received sections
+
+            Function Detailed Description
+            Allocates a new section feed, i.e. a demux resource for filtering and receiving sections.
+            On platforms with hardware support for section filtering, a section feed is directly
+            mapped to the demux HW. On other platforms, TS packets are first PID filtered in
+            hardware and a hardware section filter then emulated in software.
+            The caller obtains an API pointer of type dmx_section_feed_t as an out parameter.
+            Using this API the caller can set filtering parameters and start receiving sections.
+
+            Function Returns
+             0                                        The command was successfully performed.
+             -EBUSY                                   No more section feeds available.
+             -ENOSYS                                  The command is not implemented.
+             -EINVAL                                  Bad parameters.
+
+
+

+

+

+
+int release_section_feed ( dmx_demux_t* demux,
+             dmx_section_feed_t* 
+                                                                          feed 
+                                                                                  )
+            Function Parameters
+             dmx_demux_t* demux                            I/O Pointer to the demux API and
+                                                                  instance data.
+             dmx_section_feed_t* feed                      I      Pointer to the section feed API and
+                                                                  instance data.
+
+            Function Detailed Description
+            Releases the resources allocated with allocate_section_feed(), including allocated
+            filters. Any filtering in progress on the section feed should be stopped before calling
+            this function.
+
+            Function Returns
+             0                                        The command was successfully performed.
+             -EINVAL                                  Bad parameters.
+
+
+
+

+

+

+
+int descramble_mac_address ( dmx_demux_t* demux,
+             __u8* 
+                                                            buffer1,
+             size_t 
+                                                             buffer1_length,
+                                                   __u8* buffer2,
+             size_t 
+                                                             buffer2_length,
+                                                   __u16 pid )
+            Function Parameters
+             dmx_demux_t* demux                             I/O Pointer to the demux API and
+                                                                   instance data.
+             __u8* buffer1                                  I      Pointer to the first byte of the
+                                                                   section.
+             size_t buffer1_length                          I      Length of the section data,
+                                                                   including headers and CRC, in
+                                                                   buffer1.
+             __u8* buffer2                                  I      Pointer to the tail of the section
+                                                                   data, or NULL. The pointer has a
+                                                                   non-NULL value if the section wraps
+                                                                   past the end of a cyclic buffer.
+             size_t buffer2_length                          I      Length of the section data,
+                                                                   including headers and CRC, in
+                                                                   buffer2
+             __u16 pid                                      I      The PID on which the section was
+                                                                   received. Useful for obtaining the
+                                                                   descrambling key, e.g. from a DVB
+                                                                   Common Access facility.
+
+            Function Detailed Description
+            This function runs a descrambling algorithm on the destination MAC address field of a
+            DVB Datagram Section, replacing the original address with its unencrypted version.
+            Otherwise, the description on the function descramble_section_payload() applies
+            also to this function.
+
+            Function Returns
+             0                                         The command was successfully performed.
+             -ENOSYS                                   No descrambling facility available.
+             -EINVAL                                   Bad parameters.
+
+
+
+
+
+

+

+

+
+int descramble_section_payload (           dmx_demux_t* demux,
+             __u8* 
+                                                                  buffer1,
+             size_t 
+                                                                   buffer1_length,
+                                                       __u8* buffer2,
+             size_t 
+                                                                   buffer2_length,
+                                                       __u16 pid )
+            Function Parameters
+             dmx_demux_t* demux                            I/O Pointer to the demux API and
+                                                                  instance data.
+             __u8* buffer1                                 I/O Pointer to the first byte of the
+                                                                  section.
+             size_t buffer1_length                         I      Length of the section data,
+                                                                  including headers and CRC, in
+                                                                  buffer1.
+             __u8* buffer2                                 I      Pointer to the tail of the section
+                                                                  data, or NULL. The pointer has a
+                                                                  non-NULL value if the section wraps
+                                                                  past the end of a cyclic buffer.
+             size_t buffer2_length                         I      Length of the section data,
+                                                                  including headers and CRC, in
+                                                                  buffer2
+             __u16 pid                                     I      The PID on which the section was
+                                                                  received. Useful for obtaining the
+                                                                  descrambling key, e.g. from a DVB
+                                                                  Common Access facility.
+
+            Function Detailed Description
+            This function runs a descrambling algorithm on the payload of a DVB Datagram
+            Section, replacing the original payload with its unencrypted version. The function will
+            be called from the demux API implementation; the API client need not call this function
+            directly.
+            Section-level scrambling algorithms are currently standardized only for DVB-RCC
+            (return channel over 2-directional cable TV network) systems. For all other DVB
+            networks, encryption schemes are likely to be proprietary to each data broadcaster.
+            Thus, it is expected that this function pointer will have the value of NULL (i.e., function
+            not available) in most demux API implementations. Nevertheless, it should be possible
+            to use the function pointer as a hook for dynamically adding a "plug-in" descrambling
+            facility to a demux driver.
+
+
+            While this function is not needed with hardware-based section descrambling, the
+            descramble_section_payload function pointer can be used to override the default
+            hardware-based descrambling algorithm: if the function pointer has a non-NULL value,
+            the corresponding function should be used instead of any descrambling hardware.
+
+            Function Returns
+             0                                           The command was successfully performed.
+             -ENOSYS                                     No descrambling facility available.
+             -EINVAL                                     Bad parameters.
+
+
+
+

+

+

+
+int add_frontend ( dmx_demux_t* demux,
+             dmx_frontend_t* 
+                                                          frontend);
+
+            Function Parameters
+             dmx_demux_t* demux                        I/O Pointer to the demux API and instance
+                                                             data.
+             dmx_frontend_t* frontend                  I/O Pointer to the front-end instance data.
+
+            Function Detailed Description
+            Registers a connectivity between a demux and a front-end, i.e., indicates that the
+            demux can be connected via a call to connect_frontend() to use the given front-end
+            as a TS source. The client of this function has to allocate dynamic or static memory for
+            the frontend structure and initialize its fields  before calling this function.
+            This function is normally called during the driver initialization. The caller must not free
+            the memory of the frontend struct before successfully calling remove_frontend().
+
+            Function Returns
+             0                                      The command was successfully performed.
+             -EEXIST                                A front-end with the same value of the id field
+                                                    already registered.
+             -EINUSE                                The demux is in use.
+             -ENOMEM                                No more front-ends can be added.
+             -EINVAL                                Bad parameters.
+
+
+

+

+

+
+int remove_frontend ( dmx_demux_t* demux,
+                                         dmx_frontend_t* frontend )
+            Function Parameters
+             dmx_demux_t* demux                   I/O       Pointer to the demux API and instance
+                                                            data.
+             dmx_frontend_t* frontend             I/O       Pointer to the front-end instance data.
+
+            Function Detailed Description
+            Indicates that the given front-end, registered by a call to add_frontend(), can no
+            longer be connected as a TS source by this demux. The function should be called
+            when a front-end driver or a demux driver is removed from the system. If the front-end
+            is in use, the function fails with the return value of ­EBUSY.
+            After succesfully calling this function, the caller can free the memory of the frontend
+            struct if it was dynamically allocated before the add_frontend() operation.
+
+            Function Returns
+             0                                     The command was successfully performed.
+             -EINVAL                               Bad parameters.
+             -EBUSY                                The front-end is in use, i.e. a call to
+                                                   connect_frontend() has not been followed by
+                                                   a call to disconnect_frontend().
+
+
+
+

+

+

+
+struct list_head* get_frontends ( dmx_demux_t* demux )
+            Function Parameters
+             dmx_demux_t* demux                             I    Pointer to the demux API and
+                                                                 instance data.
+
+            Function Detailed Description
+            Provides the APIs of the front-ends that have been registered for this demux. Any of
+            the front-ends obtained with this call can be used as a parameter for
+            connect_frontend().
+
+
+            The include file demux.h contains the macro DMX_FE_ENTRY() for converting an
+            element of the generic type struct list_head* to the type dmx_frontend_t*.
+            The caller must not free the memory of any of the elements obtained via this function
+            call.
+
+            Function Returns
+            A list of front-end interfaces, or NULL in the case of an empty list.
+
+
+

+

+

+
+int connect_frontend ( dmx_demux_t* demux,
+                                           dmx_frontend_t* frontend )
+            Function Parameters
+             dmx_demux_t* demux                   I/O       Pointer to the demux API and instance
+                                                            data.
+             dmx_frontend_t* frontend             I/O       Pointer to the front-end instance data.
+
+            Function Detailed Description
+            Connects the TS output of the front-end to the input of the demux. A demux can only
+            be connected to a front-end registered to the demux with the function
+            add_frontend().
+            It may or may not be possible to connect multiple demuxes to the same front-end,
+            depending on the capabilities of the HW platform. When not used, the front-end should
+            be released by calling disconnect_frontend().
+
+            Function Returns
+             0                                     The command was successfully performed.
+             -EINVAL                               Bad parameters.
+             -EBUSY                                The front-end is in use.
+
+
+

+

+

+
+int disconnect_frontend ( dmx_demux_t* demux )
+
+
+            Function Parameters
+             dmx_demux_t* demux               I/O Pointer to the demux API and instance data.
+
+            Function Detailed Description
+            Disconnects the demux and a front-end previously connected by a
+            connect_frontend() call.
+
+            Function Returns
+             0                                        The command was successfully performed.
+             -EINVAL                                  Bad parameters.
+
+
+
+

+

+ +

+Demux Callback API +

+ 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. +

+

+ 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. +

+

+ 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. + +

+

+

+int dmx_ts_cb ( __u8* buffer1, size_t buffer1_length, 
+		__u8* buffer2, size_t buffer2_length,
+                dmx_ts_feed_t* source, dmx_success_t success )
+
+    Parameters
+
+	__u8* buffer1		      I Pointer to the start of the filtered TS packets.
+
+        size_t buffer1_length         I Length of the TS data in buffer1.
+
+        __u8* buffer2                 I Pointer to the tail of the filtered TS packets, or NULL.
+
+        size_t buffer2_length         I Length of the TS data in buffer2.
+
+        dmx_ts_feed_t* source         I Indicates which TS feed is the source of the callback.
+
+        dmx_success_t success         I Indicates if there was an error in TS reception.
+
+    Description
+
+	This function, provided by the client of the demux API, is called from the 
+	demux code. The function is only called when filtering on this TS feed has 
+	been enabled using the start_filtering() function. If conflict resolution 
+	is used (see Error! Reference source not found.), no callbacks are made to 
+	clients that have been put "on hold" regarding a TS Feed resource.
+        Any TS packets that match the filter settings are copied to a cyclic buffer. 
+	The filtered TS packets are delivered to the client using this callback 
+	function. The size of the cyclic buffer is controlled by the 
+	circular_buffer_size parameter of the set() function in the TS Feed API. It is
+	expected that the buffer1 and buffer2 callback parameters point to addresses 
+	within the circular buffer, but other implementations are also
+        possible. Note that the called party should not try to free the memory the
+	buffer1 and buffer2 parameters point to.
+        When this function is called, the buffer1 parameter typically points to the
+	start of the first undelivered TS packet within a cyclic buffer. The buffer2 
+	buffer parameter is normally NULL, except when the received TS packets have
+	crossed the last address of the cyclic buffer and "wrapped" to the beginning
+	of the buffer. In the latter case the buffer1 parameter would contain an 
+	address within the cyclic buffer, while the buffer2 parameter would contain 
+	the first address of the cyclic buffer.
+        The number of bytes delivered with this function (i.e. buffer1_length  +
+        buffer2_length) is usually equal to the value of callback_length parameter given
+        in the set() function, with one exception: if a timeout occurs before receiving
+        callback_length bytes of TS data, any undelivered packets are immediately
+        delivered to the client by calling this function. The timeout duration is 
+	controlled by the set() function in the TS Feed API.
+        If a TS packet is received with errors that could not be fixed by the TS-level
+	forward error correction (FEC), the Transport_error_indicator flag of the TS 
+	packet header should be set. The TS packet should not be discarded, as the 
+	error can possibly be corrected by a higher layer protocol.
+        If the called party is slow in processing the callback, it is possible that 
+	the circular buffer eventually fills up. If this happens, the demux driver 
+	should discard any TS packets received while the buffer is full. The error 
+	should be indicated to the client on the next callback by setting the success
+	parameter to the value of DMX_OVERRUN_ERROR.
+
+    Returns
+
+	0				Continue filtering.
+
+       -1                               Stop filtering - has the same effect as a call
+                                        to stop_filtering() on the TS Feed API.
+
+
+
+
+

+

+

+
+dmx_pes_cb()
+
+	TBD
+
+
+

+

+

+
+int dmx_section_cb ( __u8* buffer1,
+             size_t 
+                                                   buffer1_length,
+             __u8* 
+                                               buffer2,
+                                 size_t buffer2_length,
+             dmx_section_filter_t* 
+                                                                      source,
+                                       dmx_success_t success )
+
+            Function Parameters
+             __u8* buffer1                    I       Pointer to the start of the filtered section, e.g.
+                                                      within the cyclic buffer of the demux driver.
+             size_t buffer1_length            I       Length of the filtered section data in buffer1,
+                                                      including headers and CRC.
+             __u8* buffer2                            Pointer to the tail of the filtered section data, or
+                                                      NULL. Useful to handle the wrapping of a cyclic
+                                                      buffer.
+             size_t buffer2_length                    Length of the filtered section data in buffer2,
+                                                      including headers and CRC.
+             dmx_section_filter_t*            I       Indicates the filter that triggered the callback.
+             filter
+             dmx_success_t success            I       Indicates if there was an error in section
+                                                      reception.
+
+            Function Detailed Description
+            This function, provided by the client of the demux API, is called from the demux code.
+            The function is only called when filtering of sections has been enabled using the
+            function start_filtering() of the section feed API.
+            When the demux driver has received a complete section that matches at least one
+            section filter, the client is notified via this callback function. Normally this function is
+            called for each received section; however, it is also possible to deliver multiple sections
+            with one callback, for example when the system load is high.
+            If an error occurs while receiving a section, this function should be called with the
+            corresponding error type set in the success field, whether or not there is data to
+            deliver.
+            The Section Feed implementation should maintain a cyclic buffer for received sections.
+            However, this is not necessary if the Section Feed API is implemented as a client of
+
+
+            the TS Feed API, because the TS Feed implementation then buffers the
+            received data.
+            The size of the circular buffer can be configured using the set() function in the
+            Section Feed API. If there is no room in the circular buffer when a new section is
+            received, the section must be discarded. If this happens, the value of the success
+            parameter should be DMX_OVERRUN_ERROR on the next callback.
+
+            Function Returns
+             0                                         Continue filtering.
+             -1                                        Stop filtering - has the same effect as a call
+                                                       to stop_filtering() on the Section Feed
+                                                       API.
+
+
+

+ +

+ +

+TS Feed API +

+ 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. +

+

+ 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. +

+

+

+
+int set ( dmx_ts_feed_t* feed,
+             __u16 
+                                    pid,
+                           size_t callback_length,
+             size_t 
+                                     cyclic_buffer_size,
+             int 
+                               descramble,
+                           struct timespec timeout)
+
+    Parameters
+
+             dmx_ts_feed_t* feed                       I/O Pointer to the TS feed API and
+                                                               instance data.
+             __u16 pid                                 I       PID value to filter. Only the TS
+                                                               packets carrying the specified PID will
+                                                               be passed to the API client.
+             size_t callback_length                    I       Number of bytes to deliver with each
+                                                               call to the dmx_ts_cb() callback
+                                                               function. The value of this
+                                                               parameter should be a multiple of
+                                                               188.
+
+             size_t cyclic_buffer_size                    I     Size of the cyclic buffer for the filtered
+                                                                TS packets.
+             int descramble                               I     If non-zero, descramble the filtered
+                                                                TS packets.
+             struct timespec timeout                      I     Maximum time to wait before
+                                                                delivering received TS packets to the
+                                                                client.
+
+            Function Detailed Description
+            This function sets the parameters of a TS feed. Any filtering in progress on the TS feed
+            must be stopped before calling this function.
+
+            Function Returns
+             0                                            The command was successfully performed.
+             -ENOMEM                                      Not enough memory for the requested
+                                                          buffer size.
+             -ENOSYS                                      No descrambling facility available for TS
+                                                          packets.
+             -EINVAL                                      Bad parameters.
+
+
+

+

+

+
+int start_filtering ( dmx_ts_feed_t* feed )
+
+    Parameters
+ 
+             dmx_ts_feed_t* feed                    I Pointer to the TS feed API and instance data.
+
+            Function Detailed Description
+            Starts filtering TS packets on this TS feed, according to its settings. The PID value to
+            filter can be set by the API client. All matching TS packets are delivered
+            asynchronously to the client, using the callback function registered with
+            allocate_ts_feed().
+
+            Function Returns
+             0                                        The command was successfully performed.
+             -EINVAL                                  Bad parameters.
+
+
+
+

+

+

+
+int stop_filtering ( dmx_ts_feed_t* feed )
+
+    Parameters
+
+	dmx_ts_feed_t* feed	    I/O Pointer to the TS feed API and instance data.
+
+    Description
+
+	Stops filtering TS packets on this TS feed.
+
+    Returns
+
+	0				The command was successfully performed.
+
+        -EINVAL                         Bad parameters.
+
+
+
+
+

+

+ +

+PES Feed API +

+ TBD +

+

+ +

+Section Feed API +

+ 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. +

+

+ 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. +

+ +

+

+
+int set ( dmx_section_feed_t* feed, __u16 pid, size_t circular_buffer_size, 
+	  int descramble, int check_crc )
+
+    Parameters
+
+	dmx_section_feed_t* feed                  I/O Pointer to the section feed API and
+                                                                instance data.
+             __u16 pid                                I         PID value to filter; only the TS packets
+                                                                carrying the specified PID will be
+                                                                accepted.
+             size_t circular_buffer_size              I         Size of the cyclic buffer for filtered
+                                                                sections.
+             int descramble                           I         If non-zero, descramble any sections
+                                                                that are scrambled.
+             int check_crc                            I         If non-zero, check  the CRC values of
+                                                                filtered sections.
+
+            Function Detailed Description
+            This function sets the parameters of a section feed. Any filtering in progress on the
+            section feed must be stopped before calling this function.
+            If descrambling is enabled, the payload_scrambling_control and
+            address_scrambling_control fields of received DVB datagram sections should be
+            observed. If either one is non-zero, the section should be descrambled either in
+            hardware or using the functions descramble_mac_address() and
+            descramble_section_payload() of the demux API. Note that according to the
+            MPEG-2 Systems specification [3], only the payloads of private sections can be
+            scrambled while the rest of the section data must be sent in the clear.
+
+            Function Returns
+             0                                     The command was successfully performed.
+             -ENOMEM                               Not enough memory available for the requested
+                                                   buffer size.
+             -ENOSYS                               No descrambling facility available for sections.
+             -EINVAL                               Bad parameters.
+
+
+

+

+

+
+int allocate_filter(dmx_section_feed_t* feed, dmx_section_filter_t** filter)
+
+    Parameters
+             dmx_section_feed_t* feed                      I/O Pointer to the section feed API and
+                                                                 instance data.
+             dmx_section_filter_t** filter                 O     Pointer to the allocated filter.
+
+
+            Function Detailed Description
+            This function is used to allocate a section filter on the demux. It should only be called
+            when no filtering is in progress on this section feed. If a filter cannot be allocated, the
+            function fails with -ENOSPC. See below for the format of the section filter struct provided
+            as an out parameter:
+                   typedef struct {
+                           __u8 filter_value [DMX_MAX_FILTER_SIZE];
+                           __u8 filter_mask [DMX_MAX_FILTER_SIZE];
+                            struct dmx_section_feed_s* parent;  /* Back-pointer */
+                           void* priv; /* Private data of the client */
+                   } dmx_section_filter_t;
+
+            The bitfields filter_mask and filter_value should only be modified when no
+            filtering is in progress on this section feed. filter_mask controls which bits of
+            filter_value are compared with the section headers/payload. On a binary value of 1
+            in filter_mask, the corresponding bits are compared. The filter only accepts sections
+            that are equal to filter_value in all the tested bit positions. Any changes to the
+            values of filter_mask and filter_value are guaranteed to take effect only when
+            the start_filtering()  function is called next time. The parent pointer in the struct
+            is initialized by the API implementation to the value of the feed parameter. The priv
+            pointer is not used by the API implementation, and can thus be freely utilized by the
+            caller of this function. Any data pointed to by the priv pointer is available to the
+            recipient of the dmx_section_cb() function call.
+            While the maximum section filter length (DMX_MAX_FILTER_SIZE) is currently set at 16
+            bytes, hardware filters of that size are not available on all platforms. Therefore, section
+            filtering will often take place first in hardware, followed by filtering in software for the
+            header bytes that were not covered by a hardware filter. The filter_mask field can be
+            checked to determine how many bytes of the section filter are actually used, and if the
+            hardware filter will suffice. Additionally, software-only section filters can optionally be
+            allocated to clients when all hardware section filters are in use.
+            Note that on most demux hardware it is not possible to filter on the section_length field
+            of the section header ­ thus this field is ignored, even though it is included in
+            filter_value and filter_mask fields.
+
+            Function Returns
+             0                                          The command was successfully performed.
+             -ENOSPC                                    No filters of given type and length available.
+             -EINVAL                                    Bad parameters.
+
+
+

+

+

+int release_filter ( dmx_section_feed_t* feed, dmx_section_filter_t* filter)
+
+    Parameters
+             dmx_section_feed_t* feed I/O Pointer to the section feed API and instance
+                                                       data.
+             dmx_section_filter_t*              I/O Pointer to the instance data of a section filter.
+             filter
+
+            Function Detailed Description
+            This function releases all the resources of a previously allocated section filter. The
+            function should not be called while filtering is in progress on this section feed. After
+            calling this function, the caller should not try to dereference the filter pointer.
+
+            Function Returns
+             0                                        The command was successfully performed.
+             -ENODEV                                  No such filter allocated.
+             -EINVAL                                  Bad parameters.
+
+
+

+

+

+int start_filtering ( dmx_section_feed_t* feed )
+
+    Parameters
+             dmx_section_feed_t* feed                     I/O Pointer to the section feed API and
+                                                                instance data.
+
+            Function Detailed Description
+            Starts filtering sections on this section feed, according to its settings. Sections are first
+            filtered based on their PID and then matched with the section filters allocated for this
+            feed. If the section matches the PID filter and at least one section filter, it is delivered
+            to the API client. The section is delivered asynchronously using the callback function
+            registered with allocate_section_feed().
+
+            Function Returns
+             0                                            The command was successfully performed.
+             -EINVAL                                      Bad parameters.
+
+
+

+

+

+int stop_filtering ( dmx_section_feed_t* feed )
+
+    Parameters
+
+	dmx_section_feed_t* feed	    I/O Pointer to the section feed API and instance data.
+
+    Description
+
+	Stops filtering sections on this section feed. Note that any changes to the 
+	filtering parameters (filter_value, filter_mask, etc.) should only be made 
+	when filtering is stopped.
+
+    Returns
+
+	0					The command was successfully performed.
+
+        -EINVAL                                 Bad parameters.
+
+
+
+
+

+

+
+ + diff --git a/dvb-spec/API/dvb_api/dmx.h b/dvb-spec/API/dvb_api/dmx.h new file mode 100644 index 000000000..e12056514 --- /dev/null +++ b/dvb-spec/API/dvb_api/dmx.h @@ -0,0 +1,130 @@ +/* + * dmx.h + * + * Copyright (C) 2000 Marcus Metzler + * & Ralph Metzler + for convergence integrated media GmbH + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + */ + +#ifndef _OST_DMX_H_ +#define _OST_DMX_H_ + +/* pid_t conflicts with linux/include/linux/types.h !!!*/ + +typedef uint16_t dvb_pid_t; + +#define DMX_FILTER_SIZE 16 + +typedef enum +{ + DMX_OUT_DECODER, /* Streaming directly to decoder. */ + DMX_OUT_TAP, /* Output going to a memory buffer */ + /* (to be retrieved via the read command).*/ + DMX_OUT_TS_TAP /* Output multiplexed into a new TS */ + /* (to be retrieved by reading from the */ + /* logical DVR device). */ +} dmxOutput_t; + + +typedef enum +{ + DMX_IN_FRONTEND, /* Input from a front-end device. */ + DMX_IN_DVR /* Input from the logical DVR device. */ +} dmxInput_t; + + +typedef enum +{ + DMX_PES_AUDIO, + DMX_PES_VIDEO, + DMX_PES_TELETEXT, + DMX_PES_SUBTITLE, + DMX_PES_PCR, + DMX_PES_OTHER +} dmxPesType_t; + + +typedef enum +{ + DMX_SCRAMBLING_EV, + DMX_FRONTEND_EV +} dmxEvent_t; + + +typedef enum +{ + DMX_SCRAMBLING_OFF, + DMX_SCRAMBLING_ON +} dmxScramblingStatus_t; + + +typedef struct dmxFilter +{ + uint8_t filter[DMX_FILTER_SIZE]; + uint8_t mask[DMX_FILTER_SIZE]; +} dmxFilter_t; + +struct dmxFrontEnd +{ + //TBD tbd; +}; + +struct dmxSctFilterParams +{ + dvb_pid_t pid; + dmxFilter_t filter; + uint32_t timeout; + uint32_t flags; +#define DMX_CHECK_CRC 1 +#define DMX_ONESHOT 2 +#define DMX_IMMEDIATE_START 4 +}; + + +struct dmxPesFilterParams +{ + dvb_pid_t pid; + dmxInput_t input; + dmxOutput_t output; + dmxPesType_t pesType; + uint32_t flags; +}; + + +struct dmxEvent +{ + dmxEvent_t event; + time_t timeStamp; + union + { + dmxScramblingStatus_t scrambling; + //TBD; + } u; +}; + + +#define DMX_START _IOW('o',41,void) +#define DMX_STOP _IOW('o',42,void) +#define DMX_SET_FILTER _IOW('o',43,struct dmxSctFilterParams *) +#define DMX_SET_PES_FILTER _IOW('o',44,struct dmxPesFilterParams *) +#define DMX_SET_BUFFER_SIZE _IOW('o',45,unsigned long) +#define DMX_GET_EVENT _IOR('o',46,struct dmxEvent *) + + + +#endif /*_OST_DMX_H_*/ diff --git a/dvb-spec/API/dvb_api/frontend.h b/dvb-spec/API/dvb_api/frontend.h new file mode 100644 index 000000000..534a97175 --- /dev/null +++ b/dvb-spec/API/dvb_api/frontend.h @@ -0,0 +1,96 @@ +/* + * frontend.h + * + * Copyright (C) 2000 Marcus Metzler + * & Ralph Metzler + for convergence integrated media GmbH + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + */ + +#ifndef _OST_FRONTEND_H_ +#define _OST_FRONTEND_H_ + +typedef uint32_t feStatus; + +#define FE_HAS_POWER 1 +#define FE_HAS_SIGNAL 2 +#define QPSK_SPECTRUM_INV 4 + +struct qpskParameters { + uint32_t iFrequency; + uint32_t SymbolRate; + uint8_t FEC_inner; +}; + + +struct qpskEvent { + int32_t type; + time_t timestamp; + union { + struct { + feStatus previousStatus; + feStatus currentStatus; + } unexpectedEvent; + struct qpskParameters completionEvent; + feStatus failureEvent; + } u; +}; + + +struct qpskRegister { + uint8_t chipId; + uint8_t address; + uint8_t value; +}; + + +struct qpskFrontendInfo { + uint32_t minFrequency; + uint32_t maxFrequency; + uint32_t maxSymbolRate; + uint32_t minSymbolRate; + uint32_t hwType; + uint32_t hwVersion; +}; + +typedef enum { + OST_POWER_ON, + OST_POWER_STANDBY, + OST_POWER_SUSPEND, + OST_POWER_OFF +} powerState_t; + + +#define OST_SELFTEST _IOWR('o',61,void) +#define OST_SET_POWER_STATE _IOW('o',62,uint32_t) +#define OST_GET_POWER_STATE _IOR('o',63,uint32_t *) +#define FE_READ_STATUS _IOR('o',64,feStatus *) +#define FE_READ_BER _IOW('o',65,uint32_t *) +#define FE_READ_SIGNAL_STRENGTH _IOR('o',66,int32_t *) +#define FE_READ_SNR _IOR('o',67,int32_t *) +#define FE_READ_UNCORRECTED_BLOCKS _IOW('o',68,uint32_t *) +#define FE_GET_NEXT_FREQUENCY _IOW('o',69,uint32_t *) +#define FE_GET_NEXT_SYMBOL_RATE _IOW('o',70,uint32_t *) + +#define QPSK_TUNE _IOW('o',71,struct qpskParameters *) +#define QPSK_GET_EVENT _IOR('o',72,struct qpskEvent *) +#define QPSK_FE_INFO _IOR('o',73,struct qpskFrontendInfo *) +#define QPSK_WRITE_REGISTER _IOW('o',74,struct qpskRegister *) +#define QPSK_READ_REGISTER _IOR('o',75,struct qpskRegister *) + +#endif /*_OST_FRONTEND_H_*/ + diff --git a/dvb-spec/API/dvb_api/frontend.xml b/dvb-spec/API/dvb_api/frontend.xml new file mode 100644 index 000000000..1cd1b0fbd --- /dev/null +++ b/dvb-spec/API/dvb_api/frontend.xml @@ -0,0 +1,843 @@ + + + linuxtv.org|DVB Frontend API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

DVB Frontend API

 + +

+ The DVB frontend device controls the frontend of the DVB hardware, e.g. + tuning, symbol rate, error correction, ... + It is accessed through /dev/ost/qpskfe. +

+ +

+ The function calls defined in the include file + frontend.h are described in detail below: +

+ +

+ Frontend API IO control calls + + +

+

+
+int open(const char *deviceName, int flags);
+
+    DESCRIPTION
+
+	This system call opens a named front-end device (e.g. /dev/qpskfe) for 
+	subsequent use. The device can be opened in read-only mode, which only allows
+	monitoring of device status and statistics, or read/write mode, which allows 
+	any kind of use (e.g. performing tuning operations.)
+
+	In a system with multiple front-ends, it is usually the case that multiple
+	devices cannot be open in read/write mode simultaneously.  As long as a 
+	front-end device is opened in read/write mode, other open() calls in 
+	read/write mode will either fail or block, depending on whether 
+	non-blocking or blocking mode was specified.
+        A front-end device opened in blocking mode can later be put into non-blocking
+	mode (and vice versa) using the F_SETFL command of the fcntl system call.
+	This is a standard system call, documented in the Linux manual page for fcntl.
+        When an open() call has succeeded, the device will be ready for use in the 
+	specified mode. This implies that the corresponding hardware is powered up, 
+	and that other front-ends may have been powered down to make that possible.
+
+    PARAMETERS
+
+	const char *deviceName	      I Name of specific front-end device.  In the
+                                        current implementation, /dev/qpskfe is the
+                                        only one available (QPSK satellite front-end.)
+
+	int flags	              I A bit-wise OR of the following flags:
+                                        O_RDONLY read-only access
+                                        O_RDWR read/write  access
+                                        O_NONBLOCK open in non-blocking mode
+                                                       (blocking mode is the default)
+    RETURNS
+
+	ENODEV				Device driver not loaded/available.
+
+        EBUSY				Device or resource busy.
+
+	EINVAL				Invalid argument.
+
+
+
+
+

+ +

+

+
+int close(int fd);
+
+    DESCRIPTION
+
+	This system call closes a previously opened front-end device.  After closing a 
+	front-end device, its corresponding hardware might be powered down 
+	automatically, but only when this is needed to open another front-end device.
+	To affect an unconditional power down, it should be done explicitly using 
+	the OST_SET_POWER_STATE ioctl.
+
+    PARAMETERS
+
+	int fd                I File descriptor returned by a previous call to open().
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = OST_SELFTEST);
+
+    DESCRIPTION
+
+  	This ioctl call initiates an automatic self-test of the front-end hardware.  
+	This call requires read/write access to the device.
+
+    PARAMETERS
+
+	int fd                I File descriptor returned by a previous call to open().
+
+	int request	      I Equals OST_SELFTEST for this command.
+
+    RETURNS
+	
+	0                       Success
+
+	-1			Failure
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = OST_SET_POWER_STATE, uint32_t state);
+
+    DESCRIPTION
+
+	This ioctl call, implemented in many OST device drivers, enables direct 
+	control over the power state of the hardware device, which may be on, off, 
+	standby, or suspend.  The latter two are low-power modes, which disable all 
+	functionality of the device until turned on again. In contrast to the off 
+	state, however, the standby and suspend states resume operation in the same
+	state as when the device was active.  The only difference between the standby
+	and suspend states is a different tradeoff between resume time and power 
+	consumption ­ power consumption may be lower in the suspend state at the
+        cost of a longer resume time.
+
+        A device that implements this call does not necessarily support two low-power
+	modes. If it only support one low-power state, or none at all, the 
+	OST_SET_POWER_STATE operation for the missing states will still succeed, but 
+	it will be mapped to an existing state as per this table:
+
+        number of low-power	requested state		resulting state
+        states supported
+
+            1                      standby                  suspend
+
+            1                      suspend                  suspend
+
+            0                      standby                    on
+
+            0                      suspend                    on
+
+        For other cases where a required state is missing, an error code will be
+	returned.  This can happen if a device does not support the power-off state, 
+	but nevertheless implements this ioctl operation for control of low-power 
+	states.
+        When opening a device in read/write mode, the driver ensures that the 
+	corresponding hardware device is turned on initially.  If the device is 
+	later turned off or put in suspend mode, it has to be explicitly turned on 
+	again.
+
+        This call requires read/write access to the device.  (Note that the power 
+	management driver can affect the power state of devices without using this 
+	ioctl operation, so having exclusive read/write access to a device does not 
+	imply total control over the power state.)
+
+    PARAMETERS
+    
+	int fd		      I File descriptor returned by a previous call to open().
+
+	int request	      I Equals OST_SET_POWER_STATE for this command.
+
+	uint32_t state        I Requested power state.  One of:
+
+                                OST_POWER_ON:		turn power on
+                                OST_POWER_STANDBY:      set device in standby mode
+                                OST_POWER_SUSPEND:      set device in suspend mode
+                                OST_POWER_OFF:          turn power off
+
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EINVAL                  illegal state, or not available on this device
+
+        EPERM                   permission denied (needs read/write access)
+
+        ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = OST_GET_POWER_STATE, uint32_t *state);
+
+    DESCRIPTION
+
+	This ioctl call, implemented in many OST device drivers, obtains the power
+	state of the hardware device, which may be on, off, standby, or suspend.
+        A device that implements this call does not necessarily support all four states.
+	If there is only one low-power state, the suspend state will be returned for 
+	that state.  If there is no low-power state, the on state will be reported 
+	standby and suspend states will be equivalent to the on state.
+        For this command, read-only access to the device is sufficient.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+	int request	      I Equals OST_GET_POWER_STATE for this command.
+
+        uint32_t *state	      O Pointer to a variable where the power state is
+                                to be stored.  Possible values are:
+                                OST_POWER_ON                      power is on
+                                OST_POWER_STANDBY                 device in 
+                                                                  standby mode
+                                OST_POWER_SUSPEND:                device in 
+                                                                  suspend mode
+                                OST_POWER_OFF:                    power is off
+
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+        
+	EINVAL                  illegal state, or not available on this device
+
+        EFAULT                  state points to invalid address
+
+        EPERM                   permission denied (needs read/write access)
+
+	ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = QPSK_READ_STATUS, feStatus *status);
+
+    DESCRIPTION
+
+	This ioctl call returns status information about the front-end.
+	This call only requires read-only access to the device.
+
+    PARAMETERS
+
+	int fd                   I File descriptor returned by a previous call to open().
+
+        int request              I Equals FE_READ_STATUS for this command.
+
+        struct feStatus *status  O Points to the location where the front-end
+                                   status word is to be stored.
+
+    RETURNS
+
+	EBADF                      fd is not a valid open file descriptor
+
+        EFAULT                     status points to invalid address
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = FE_READ_BER, uint32_t *ber);
+
+    DESCRIPTION
+
+	This ioctl call returns the bit error rate for the signal currently 
+	received/demodulated by the front-end. For this command, read-only access 
+	to the device is sufficient.
+
+    FUNCTION PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request	      I Equals FE_READ_BER for this command.
+
+        uint32_t *ber         O The bit error rate, as a multiple of 10-9, is stored into *ber.
+
+                                Example: a value of 2500 corresponds to a bit error 
+					 rate of 2.5 10-6, or 1 error in 400000 bits.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EFAULT			ber points to invalid address
+
+        ENOSIGNAL               There is no signal, thus no meaningful bit error
+                                rate.  Also returned if the front-end is not turned on.
+
+        ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = FE_READ_SIGNAL_STRENGTH, int32_t *strength);
+
+    DESCRIPTION
+
+	This ioctl call returns the signal strength value for the signal currently 
+	received by the front-end. For this command, read-only access to the device 
+	is sufficient.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals  FE_READ_SIGNAL_STRENGTH for this
+                                                     command.
+        int32_t *strength     O The signal strength value, as a multiple of 10^-6 dBm,
+				is stored into *strength.  
+				Example: a value of ­12,500,000 corresponds to a signal
+                                         strength value of ­12.5 dBm.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  strength points to invalid address
+ 
+        ENOSIGNAL               There is no signal, thus no meaningful signal
+                                strength value.  Also returned if front-end is not
+                                turned on.
+
+        ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = FE_READ_SNR, int32_t *snr);
+
+    DESCRIPTION
+
+	This ioctl call returns the signal-to-noise ratio for the signal currently 
+	received by the front-end. For this command, read-only access to the device
+	is sufficient.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request	      I Equals FE_READ_SNR for this command.
+
+        int32_t *snr	      O The signal-to-noise ratio, as a multiple of
+                                10^-6 dB, is stored into *snr.
+
+                                Example: a value of 12,300,000 corresponds
+                                         to a signal-to-noise ratio of 12.3 dB.
+
+    RETURNS
+    
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  snr points to invalid address
+
+        ENOSIGNAL               No stable signal, thus no meaningful signal-to-
+                                noise ratio.  Also returned if front-end is not
+                                turned on.
+
+        ENOSYS                  Function not available for this device.
+
+

+ +

+

+int ioctl( int fd, int request = FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks);
+
+
+    DESCRIPTION
+
+	This ioctl call returns the number of uncorrected blocks detected by the device
+	driver during its lifetime.  For meaningful measurements, the increment in 
+	block count during a specific time interval should be calculated2.  For this 
+	command, read-only access to the device is sufficient.
+        
+	2 Note that the counter will wrap to zero after its maximum count has 
+	  been reached (232-1).
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request	      I Equals FE_READ_UNCORRECTED_BLOCKS for this command.
+
+        uint32_t *ublocks     O The total number of uncorrected blocks seen
+                                by the driver so far.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  ublocks points to invalid address
+
+        ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = FE_GET_NEXT_FREQUENCY, uint32_t *freq);
+
+    DESCRIPTION
+
+	When scanning a frequency range, it is desirable to use a scanning step size 
+	that is as large as possible, yet small enough to be able to lock to any signal 
+	within the range.
+        This  ioctl operation does just that ­ it increments a given frequency by a 
+	step size suitable for efficient3 scanning.
+        The step size used by this function may be a quite complex function of the given
+        frequency, hardware capabilities, and parameter settings of the device.  Thus, a
+        returned result is only valid for the current state of the device.
+        For this command, read-only access to the device is sufficient.
+                                                        
+        3 Note that scanning may still be excruciatingly slow on some hardware, for 
+	  other reasons than a non-optimal scanning step size.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals  FE_GET_NEXT_FREQUENCY for this command.
+
+        uint32_t *freq      I/O Input: a given frequency
+                                Output:  the frequency corresponding to
+	                                 the next higher frequency setting.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  freq points to invalid address
+
+        EINVAL                  maximum frequency reached
+
+        ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl( int fd, int request = FE_GET_NEXT_SYMBOL_RATE, uint32_t *symbolRate);
+
+    DESCRIPTION
+
+	When scanning a range of symbol rates (e.g. for "blind acquisition") it is 
+	desirable to use a scanning step size that is as large as possible, yet 
+	small enough to detect any valid signal within the range.  This ioctl 
+	operation does just that ­ it increments a given symbol rate by a step size
+	suitable for efficient4 scanning.
+        The step size used by this function may be a quite complex function of the given
+        symbol rate, hardware capabilities, and parameter settings of the device.  
+	Thus, a returned result is only valid for the current state of the device.
+        For this command, read-only access to the device is sufficient.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals  FE_GET_NEXT_SYMBOL_RATE for this command.
+
+        uint32_t *symbolRate  I/O Input:  a given symbol rate                                                             Output: the symbol rate corresponding to the next
+	                                  higher symbol rate setting.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  symbolRate points to invalid address
+
+        EINVAL                  maximum symbol rate reached
+
+        ENOSYS                  Function not available for this device.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = QPSK_TUNE, struct qpskParameters *p);
+
+    DESCRIPTION
+
+	This ioctl call starts a tuning operation using specified parameters.  
+	The result of this call will be successful if the parameters were valid and 
+	the tuning could be initiated.
+        The result of the tuning operation in itself, however, will arrive 
+	asynchronously as an event (see documentation for QPSK_GET_EVENT and qpskEvent.)
+        If a new QPSK_TUNE operation is initiated before the previous one was completed,
+	the previous operation will be aborted in favor of the new one.
+        This command requires read/write access to the device.
+
+    PARAMETERS
+
+	int fd			 File descriptor returned by a previous call to open(). 
+
+	int request		 Equals QPSK_TUNE for this command.
+
+	struct qpskParameters *p Points to parameters for tuning operation.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+        EFAULT                  p points to invalid address
+        EINVAL                  parameter value(s) not valid
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = QPSK_GET_EVENT, struct qpskEvent *ev);
+
+    DESCRIPTION
+    
+	This ioctl call returns an event of type qpskEvent if available. If an event
+	is not available, the behavior depends on whether the device is in blocking 
+	or non-blocking mode.  In the latter case, the call fails immediately with 
+	errno set to EWOULDBLOCK. In the former case, the call blocks until an event
+	becomes available.
+        The standard Linux poll() and/or select() system calls can be used with the 
+	device file descriptor to watch for new events.  For select(), the file 
+	descriptor should be included in the exceptfds argument, and for poll(), 
+	POLLPRI should be specified as the wake-up condition.
+        Since the event queue allocated is rather small (room for 8 events), the queue
+	must be serviced regularly to avoid overflow.   If an overflow happens, the 
+	oldest event is discarded from the queue, and an error (EBUFFEROVERFLOW) occurs 
+	the next time the queue is read. After reporting the error condition in this 
+	fashion, subsequent QPSK_GET_EVENT calls will return events from the queue as
+	usual.
+        For the sake of implementation simplicity, this command requires read/write 
+	access to the device.
+
+    PARAMETERS
+              
+	int fd			File descriptor returned by a previous call to open().
+
+        int request           I Equals QPSK_GET_EVENT for this command.
+
+        struct qpskEvent *ev  O Points to the location where the event, if any, is to be stored.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  ev points to invalid address
+
+        EWOULDBLOCK             There is no event pending, and the device is in
+                                non-blocking mode.
+
+        EBUFFEROVERFLOW         Overflow in event queue - one or more events were lost.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = QPSK_FE_INFO, struct qpskFrontendInfo *info);
+
+    DESCRIPTION
+
+	This ioctl call returns information about the front-end.
+	This call only requires read-only access to the device.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals QPSK_FE_INFO for this command.
+
+        struct qpskFrontendInfo *info   O Points to the location where the front-end
+                                          information is to be stored.
+
+    RETURNS
+    
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  info points to invalid address
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = QPSK_WRITE_REGISTER, struct qpskRegister *reg);
+
+    DESCRIPTION
+ 
+	This ioctl call is intended for hardware-specific diagnostics.  It writes 
+	an 8-bit value at an 8-bit address of a register in a chip identified by an 
+	8-bit index.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals  QPSK_WRITE_REGISTER for this command.
+
+        struct qpskRegister *reg    I Specifies a value that should be written
+                                      into a specified register in a specified chip.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  reg points to and invalid address
+
+        EINVAL                  Register specification invalid.
+
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = QPSK_READ_REGISTER, struct qpskRegister *reg);
+
+    DESCRIPTION
+
+	This ioctl call is intended for hardware-specific diagnostics.  
+	It reads an 8-bit value at an 8-bit address of a register in a chip 
+	identified by an 8-bit index.
+
+    PARAMETERS
+
+	int fd		    I File descriptor returned by a previous call to open().
+
+        int request         I Equals QPSK_READ_REGISTER for this command.
+
+        struct qpskRegister *reg   I/O I:  specifies a register in a specified
+                                           chip from which a value should be read.
+
+                                       O:  the value is read into the
+                                           qpskRegister structure.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor
+
+        EFAULT                  reg points to and invalid address
+
+        EINVAL                  Register specification invalid.
+
+
+
+
+

+ +

+ +
+ + diff --git a/dvb-spec/API/dvb_api/sec.h b/dvb-spec/API/dvb_api/sec.h new file mode 100644 index 000000000..f6eda5a0a --- /dev/null +++ b/dvb-spec/API/dvb_api/sec.h @@ -0,0 +1,116 @@ +/* + * sec.h + * + * Copyright (C) 2000 Ralph Metzler + * & Marcus Metzler + for convergence integrated media GmbH + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + */ + +#ifndef _OST_SEC_H_ +#define _OST_SEC_H_ + +#define SEC_MAX_DISEQC_PARAMS 3 + +struct secDiseqcCmd { + uint8_t addr; + uint8_t cmd; + uint8_t numParams; + uint8_t params[SEC_MAX_DISEQC_PARAMS]; +}; + +typedef uint32_t secVoltage; + +enum { + SEC_VOLTAGE_OFF, + SEC_VOLTAGE_LT, + SEC_VOLTAGE_13, + SEC_VOLTAGE_13_5, + SEC_VOLTAGE_18, + SEC_VOLTAGE_18_5 +}; + + +typedef uint32_t secToneMode; + +typedef enum { + SEC_TONE_ON, + SEC_TONE_OFF +} secToneMode_t; + + +typedef uint32_t secMiniCmd; + +typedef enum { + SEC_MINI_NONE, + SEC_MINI_A, + SEC_MINI_B +} secMiniCmd_t; + +struct secStatus { + int32_t busMode; + secVoltage selVolt; + secToneMode contTone; +}; + +enum { + SEC_BUS_IDLE, + SEC_BUS_BUSY, + SEC_BUS_OFF, + SEC_BUS_OVERLOAD +}; + +struct secCommand { + int32_t type; + union { + struct secDiseqcCmd diseqc; + uint8_t vsec; + uint32_t pause; + } u; +}; + +struct secCmdSequence { + secVoltage voltage; + secMiniCmd miniCommand; + secToneMode continuousTone; + + uint32_t numCommands; + struct secCommand* commands; +}; + +enum { + SEC_CMDTYPE_DISEQC, + SEC_CMDTYPE_VSEC, + SEC_CMDTYPE_PAUSE +}; + + +#define SEC_GET_STATUS _IOR('o',91,struct secStatus *) +#define SEC_RESET_OVERLOAD _IOW('o',92,void) +#define SEC_SEND_SEQUENCE _IOW('o',93,struct secCmdSequence *) +#define SEC_SET_TONE _IOW('o',94,secToneMode) +#define SEC_SET_VOLTAGE _IOW('o',95,secVoltage) + +typedef enum { + SEC_DISEQC_SENT, + SEC_VSEC_SENT, + SEC_PAUSE_COMPLETE, + SEC_CALLBACK_ERROR +} secCallback_t; + + +#endif /*_OST_SEC_H_*/ diff --git a/dvb-spec/API/dvb_api/sec.xml b/dvb-spec/API/dvb_api/sec.xml new file mode 100644 index 000000000..22062d4a9 --- /dev/null +++ b/dvb-spec/API/dvb_api/sec.xml @@ -0,0 +1,430 @@ + + + linuxtv.org|DVB SEC API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

DVB SEC API

 + +

+ The DVB SEC device controls the Satellite Equipment Control of + the DVB hardware, i.e. DiSEqC and V-SEC. + It is accessed through /dev/ost/sec. +

+ +

+ The function calls defined in the include file + sec.h aredescribed in detail below: +

+ +

+ SEC API IO control calls + + +

+

+
+int open(const char *deviceName, int flags);
+
+    DESCRIPTION
+
+	This system call opens a named SEC device for subsequent use.
+        If the device is opened in read-only mode, only status and statistics 
+	monitoring is allowed. If the device is opened in read/write mode, all
+	types of operations can be performed.
+	Any number of applications can have simultaneous access to the device.
+
+    PARAMETERS
+
+	const char *deviceName	I Name of the SEC device.
+
+        int flags		I Valid values are:
+                                  O_RDONLY             read-only access
+                                  O_RDWR               read/write access
+
+	The optional flag O_NONBLOCK is not supported. If O_NONBLOCK is set, 
+	open() and most other subsequent calls to the device will return ­1 and 
+	set errno to EWOULDBLOCK.
+	The communication with the peripheral devices is sequential by nature, 
+	so it is probably preferable to use the device in synchronous mode. 
+	This is the motivation for not going through the extra effort of 
+	implementing asynchronous operation of the device.
+
+    RETURNS
+
+	ENODEV			Device not loaded/available
+        EFAULT                  deviceName does not refer to a valid memory area.
+        EINVAL                  Invalid argument
+
+
+
+
+

+ +

+

+
+int close(int fd);
+
+    DESCRIPTION
+
+	This system call closes a previously opened SEC device.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+    RETURNS
+    
+	EBADF			fd is not a valid file descriptor.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = SEC_GET_STATUS, struct secStatus* status);
+
+    DESCRIPTION
+
+	This call gets the status of the device.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals SEC_GET_STATUS for this command.
+
+        struct secStatus* status   O The status of the device.
+
+    RETURNS
+
+	ENODEV			Device driver not loaded/available
+
+        EFAULT                  status is an invalid pointer
+
+        EBUSY                   Device or resource busy
+
+        EINVAL                  Invalid argument
+
+        EPERM                   File not opened with read permissions
+
+        EINTERNAL               Internal error in the device driver
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = SEC_RESET_OVERLOAD);
+
+    DESCRIPTION
+
+	If the bus has been automatically powered off due to power overload, this
+	ioctl call restores the power to the bus. The call requires read/write 
+	access to the device.
+        This call has no effect if the device is manually powered off.
+
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals SEC_RESET_OVERLOAD for this command.
+
+    RETURNS
+
+	EBADF                   fd is not a valid file descriptor.
+
+        EPERM                   Permission denied (needs read/write access)
+
+        EINTERNAL               Internal error in the device driver
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = SEC_SEND_SEQUENCE, struct secCmdSequence *seq);
+
+    DESCRIPTION
+
+	This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC 
+	commands. The first version of the SEC device does not support V-SEC 
+	signalling and it aborts the operation with an error code if a V-SEC 
+	command is detected in the input data.
+
+        !  The call will fail with errno set to EBUSOVERLOAD if the bus is 
+	   overloaded. If the bus is overloaded, SEC_RESET_OVERLOAD can be 
+           called and the operation can be retried.
+
+        !  If seq.numCommands equals 0 and seq.miniCommand equals SEC_MINI_NONE,
+	   the bus voltage will be switched and the continuous 22kHz tone 
+	   generation enabled/disabled immediately.
+ 
+        This operation is atomic. If several processes calls this ioctl 
+	simultaneously, the operations will be serialised so a complete sequence
+	is sent at a time.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals  SEC_SEND_SEQUENCE for this command.
+
+        struct secCmdSequence *seq    I Pointer to the command sequence to be transmitted.
+
+    RETURNS
+    
+	EBADF			Fd is not a valid file descriptor.
+        
+	EFAULT                  Seq points to an invalid address.
+        
+        EINVAL                  The data structure referred to by seq is invalid in
+                                some way.
+
+        EPERM                   Permission denied (needs read/write access)
+
+        EINTERNAL               Internal error in the device driver
+
+
+        EBUSMODE                The device is not prepared for transmission 
+				(e.g. it might be manually powered off).
+
+        EBUSOVERLOAD                  Bus overload has occurred.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = SEC_SET_TONE, secToneMode tone);
+
+    DESCRIPTION
+
+	This call is used to set the generation of the continuous 22kHz tone. 
+	The possibility to just change the tone mode is already provided by 
+	ioctl SEC_SEND_SEQUENCE, but SEC_SET_TONE is an easier to use interface.
+        To keep the transmission of a command sequence (see section 4.4.5 ) as 
+	an atomic operation, SEC_SET_TONE will block if a transmission is in 
+	progress. This call requires read/write permissions.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals SEC_SET_TONE for this command.
+
+        secToneMode tone      I The requested tone generation mode (on/off).
+
+    RETURNS
+
+	ENODEV			Device driver not loaded/available
+
+        EBUSY                   Device or resource busy
+
+        EINVAL                  Invalid argument
+
+        EPERM                   File not opened with read permissions
+
+        EINTERNAL               Internal error in the device driver
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = SEC_SET_VOLTAGE, secVoltage voltage);
+
+    DESCRIPTION
+    
+	This call is used to set the bus voltage. The possibility to just change
+	the bus voltage is already provided by ioctl SEC_SEND_SEQUENCE, but 
+	SEC_SET_VOLTAGE is an easier to use interface.
+        To keep the transmission of a command sequence (see section 4.4.5 ) as
+	an atomic operation, SEC_SET_VOLTAGE will block if a transmission is in 
+	progress.
+	This call requires read/write permissions.
+
+    PARAMETERS
+
+	int fd		      I File descriptor returned by a previous call to open().
+
+        int request           I Equals SEC_SET_VOLTAGE for this command.
+
+        secVoltage voltage    I The requested bus voltage.
+
+    RETURNS
+
+	ENODEV			Device driver not loaded/available
+        
+	EBUSY                   Device or resource busy
+        
+	EINVAL                  Invalid argument
+        
+	EPERM                   File not opened with read permissions
+
+	EINTERNAL               Internal error in the device driver
+
+
+
+
+

+

+
+ + diff --git a/dvb-spec/API/dvb_api/video.h b/dvb-spec/API/dvb_api/video.h new file mode 100644 index 000000000..de5ac2b19 --- /dev/null +++ b/dvb-spec/API/dvb_api/video.h @@ -0,0 +1,95 @@ +/* + * video.h + * + * Copyright (C) 2000 Marcus Metzler + * & Ralph Metzler + for convergence integrated media GmbH + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * + */ + +#ifndef _OST_VIDEO_H_ +#define _OST_VIDEO_H_ + +#define boolean int +#define true 1 +#define false 0 + +typedef enum { + VIDEO_FORMAT_4_3, /* Select 4:3 format */ + VIDEO_FORMAT_16_9 /* Select 16:9 format. */ +} videoFormat_t; + + +typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT +} videoDisplayFormat_t; + + +typedef enum { + VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ + VIDEO_SOURCE_MEMORY /* If this source is selected, the stream + comes from the user through the write + system call */ +} videoStreamSource_t; + +typedef enum { + VIDEO_STOPPED, /* Video is stopped */ + VIDEO_PLAYING, /* Video is currently playing */ + VIDEO_FREEZED /* Video is freezed */ +} videoPlayState_t; + + +struct videoEvent { + int32_t type; + time_t timestamp; + + union { + videoFormat_t videoFormat; + } u; +}; + + +struct videoStatus { + boolean videoBlank; + videoPlayState_t playState; + videoStreamSource_t streamSource; + videoFormat_t videoFormat; + videoDisplayFormat_t displayFormat; +}; + + +struct videoDisplayStillPicture { + char *iFrame; + int32_t size; +}; + +#define VIDEO_STOP _IOW('o', 21, boolean) +#define VIDEO_PLAY _IOW('o', 22, void) +#define VIDEO_FREEZE _IOW('o', 23, void) +#define VIDEO_CONTINUE _IOW('o', 24, void) +#define VIDEO_SELECT_SOURCE _IOW('o', 25, videoStreamSource_t) +#define VIDEO_SET_BLANK _IOW('o', 26, boolean) +#define VIDEO_GET_STATUS _IOR('o', 27, struct videoStatus *) +#define VIDEO_GET_EVENT _IOR('o', 28, struct videoEvent *) +#define VIDEO_SET_DIPLAY_FORMAT _IOW('o', 29, videoDisplayFormat_t) +#define VIDEO_STILLPICTURE _IOW('o', 30, struct videoDisplayStillPicture *) +#define VIDEO_FAST_FORWRD _IOW('o', 31, int) +#define VIDEO_SLOWMOTION _IOW('o', 32, int) + +#endif /*_OST_VIDEO_H_*/ diff --git a/dvb-spec/API/dvb_api/video.xml b/dvb-spec/API/dvb_api/video.xml new file mode 100644 index 000000000..18ff9aa28 --- /dev/null +++ b/dvb-spec/API/dvb_api/video.xml @@ -0,0 +1,666 @@ + + + linuxtv.org|DVB Video API
  + +
 
+   +
+  convergence.de +
+  cryptolabs.org
+  directfb.org +
+  linuxtv.org +
+   +
+  linuxtv
+  projects
+  developer
  +  DVB
   + +  API
  +  DVD
  +  Mbone
  +  CVS
+  download
+  contact
 +   +

DVB Video API

 + +

+ The DVB video device controls the MPEG2 video decoder of the DVB hardware. + It can be accessed through /dev/ost/audio. +

+ +

+ The include file video.h describes the data + types and lists all i/o calls. + A complete explanation of all calls can be found below: +

+ + +

+ Video API IO control calls + + +

+

+
+int open(const char *deviceName, int flags);
+
+    FUNCTION
+
+	This system call opens a named video device (e.g. /dev/ost/video) for subsequent
+        use.
+        When an open() call has succeeded, the device will be ready for use.
+        The significance of blocking or non-blocking mode is described in the documentation
+        for functions where there is a difference. It does not affect the semantics of the
+        open() call itself. A device opened in blocking mode can later be put into non-
+        blocking mode (and vice versa) using the F_SETFL command of the fcntl system
+        call.  This is a standard system call, documented in the Linux manual page for fcntl.
+        Only one user can open the Video Device in O_RDWR mode. All other attemts to
+        open the device in this mode will fail, and an errorcode will be returned.
+        If the Video Device is opened in O_RDONLY mode, the only ioctl call that can be used
+        is VIDEO_GET_STATUS. All other call will return an error code.
+
+
+    PARAMETERS
+
+	const char *deviceName	Name of specific video device.  In the current
+                      		implementation,  /dev/ost/video is the only
+                                one available.
+	int flags               A bit-wise OR of the following flags:
+
+                                O_RDONLY read-only access
+
+                                O_RDWR read/write access
+
+                                O_NONBLOCK open in non-blocking mode 
+				           (blocking mode is the default)
+    RETURNS
+    
+	ENODEV                  Device driver not loaded/available.
+
+        EINTERNAL               Internal error, possibly in the communication
+                                with the DVB subsystem.
+
+        EBUSY                   Device or resource busy.
+
+        EINVAL                  Invalid argument.
+
+
+
+

+ +

+

+
+int close(int fd);
+
+    DESCRIPTION
+
+	This system call closes a previously opened video device
+
+    PARAMETERS
+
+        int fd			File descriptor returned by a previous call to open().
+
+    RETURNS
+    
+	EBADF                                   fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+size_t write(int fd, const void *buf, size_t count);
+
+    DESCRIPTION
+    
+	This system call is only provided if VIDEO_SOURCE_MEMORY is selected in the 
+	ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in PES format.
+        If O_NONBLOCK is not specified the function will block until buffer space 
+	is available. The amount of data to be transferred is implied by count.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+        void *buf		Pointer to the buffer containing the PES data.
+
+	size_t count		Size of buf.
+
+    RETURNS
+
+	EPERM                   Mode VIDEO_SOURCE_MEMORY not selected.
+        
+	ENOMEM			Attempted to write more data than the internal buffer can hold.
+
+	EBADF			fd is not a valid open file descriptor
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_STOP, boolean mode); 
+
+    FUNCTION
+	
+	This ioctl call asks the Video Device to stop playing the current stream.
+	Depending on the input parameter, the screen can be blanked out or
+	displaying the last decoded frame.
+
+    PARAMETERS
+
+	int fd 		File descriptor returned by a previous call to open(). 
+
+	int request 	Equals VIDEO_STOP for this command. 
+
+	Boolean mode 	Indicates how the screen shall be handled. 
+
+			TRUE: Blank screen when stop. 
+			FALSE: Show last decoded frame.
+
+    RETURNS
+
+	EBADF 		fd is not a valid open file descriptor 
+
+	EINTERNAL 	Internal error, possibly in the communication with 
+			the DVB subsystem.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_PLAY); 
+
+    FUNCTION 
+	
+	This ioctl call asks the Video Device to start playing a video stream 
+	from the selected source.
+
+    PARAMETERS
+
+	int fd 		File descriptor returned by a previous call to open(). 
+
+	int request 	Equals VIDEO_PLAY for this command.
+
+
+    RETURNS
+
+	EBADF 		fd is not a valid open file descriptor 
+
+	EINTERNAL 	Internal error, possibly in the communication with 
+			the DVB subsystem.
+
+
+
+
+

+ + +

+

+int ioctl(int fd, int request = VIDEO_FREEZE); 
+
+    FUNCTION 
+
+	This ioctl call suspends the live video stream being played. 
+	Decoding and playing are frozen. It is then possible to restart 
+	the decoding and playing process of the video stream using 
+	VIDEO_CONTINUE command. If VIDEO_SOURCE_MEMORY is selected in the
+	ioctl call VIDEO_SELECT_SOURCE, the DVB-subsystem will not decode 
+	any more data until the ioctl call VIDEO_FREEZE or VIDEO_PLAY is 
+	performed.
+
+    PARAMETERS 
+	
+	int fd 		File descriptor returned by a previous call to open(). 
+
+	int request 	Equals VIDEO_FREEZE for this command. 
+
+    RETURNS 
+
+	EBADF 		fd is not a valid open file descriptor. 
+
+	EINTERNAL 	Internal error, possibly in the communication with
+			the DVB subsystem.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_CONTINUE); 
+
+    FUNCTION 
+
+	This ioctl call restarts decoding and playing processes of the video
+	stream which was played before a call to VIDEO_FREEZE was made.
+
+    PARAMETERS 
+
+	int fd 		File descriptor returned by a previous call to open(). 
+
+	int request 	Equals VIDEO_CONTINUE for this command.
+
+    RETURNS 
+
+	EBADF 		fd is not a valid open file descriptor. 
+
+	EINTERNAL 	Internal error, possibly in the communication with 
+			the DVB subsystem.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_SELECT_SOURCE, videoStreamSource_t source); 
+
+    FUNCTION
+	
+	This ioctl call informs the video device which source shall be used 
+	for the input data. The possible sources are demux or memory. If 
+	internal is selected, the data is feed to the Video Device through 
+	the write command.
+
+    PARAMETERS 
+
+	int fd 		File descriptor returned by a previous call to open(). 
+
+	int request 	Equals VIDEO_SELECT_SOURCE for this command. 
+
+	videoStreamSource_t source 
+			Indicates which source shall be used for the Video stream.
+
+    RETURNS 
+
+	EBADF 		fd is not a valid open file descriptor. 
+	
+	EINTERNAL 	Internal error, possibly in the communication with 
+			the DVB subsystem.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_SET_BLANK, boolean mode);
+
+    DESCRIPTION
+	
+	This ioctl call asks the Video Device to blank out the picture.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+        int request		Equals VIDEO_SET_BLANK for this command.
+
+	boolean mode		TRUE: Blank screen when stop.
+                 		FALSE:  Show last decoded frame.
+
+    RETURNS
+
+	EBADF		      	fd is not a valid open file descriptor.
+
+        EINTERNAL		Internal error
+	
+	EINVAL      		Illegal input parameter.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_GET_STATUS, struct videoStatus *status);
+
+    DESCRIPTION
+    
+	This ioctl call asks the Video Device to return the current status of the device.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals VIDEO_GET_STATUS for this command.
+
+	struct videoStatus      Returns the current status of the Video Device.
+               *status
+
+
+    RETURNS
+
+	EBADF    		fd is not a valid open file descriptor.
+
+	EINTERNAL  		Internal error
+
+	EFAULT                  status points to invalid address
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_GET_EVENT, struct videoEvent *ev);
+
+    DESCRIPTION
+
+	This ioctl call returns an event of type videoEvent if available.
+	If an event is not available, the behavior depends on whether the device is in
+	blocking or non-blocking mode.  In the latter case, the call fails immediately
+	with errno set to EWOULDBLOCK. In the former case, the call blocks until an 
+	event becomes available.
+        The standard Linux poll() and/or select() system calls can be used with the 
+	device file descriptor to watch for new events.  For select(), the file 
+	descriptor should be included in the exceptfds argument, and for poll(), 
+	POLLPRI should be specified as the wake-up condition.
+        Read-only permissions are sufficient for this ioctl call.
+
+    PARAMETERS
+          
+	int fd			File descriptor returned by a previous call to open().
+
+        int request		Equals VIDEO_GET_EVENT for this command.
+
+	struct videoEvent *ev 	Points to the location where the event, if any, is
+                                to be stored.
+
+
+    RETURNS
+    
+	EBADF    		fd is not a valid open file descriptor
+
+	EFAULT                  ev points to invalid address
+
+        EWOULDBLOCK             There is no event pending, and the device is in 
+				non-blocking mode.
+
+        EBUFFEROVERFLOW         Overflow in event queue - one or more events were lost.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_SET_DISPLAY_FORMAT, videoDisplayFormat_t format);
+
+    DESCRIPTION
+
+	This ioctl call asks the Video Device to select the video format to be applied
+	by the MPEG chip on the video.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals  VIDEO_SET_DISPLAY_FORMAT for this command.
+
+	videoDisplayFormat_t	Selects the video format to be used.
+        format
+        
+    RETURNS
+    
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+        EINVAL			Illegal parameter format.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_STILLPICTURE, struct videoDisplayStillPicture *sp);
+
+    DESCRIPTION
+
+	This ioctl call asks the Video Device to display a still picture (I-frame). 
+	The input data shall contain an I-frame. If the pointer is NULL, then the 
+	current displayed still picture is blanked.
+	
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals VIDEO_STILLPICTURE for this command.
+
+        struct videoDisplayStillPicture	*sp	Pointer to a location where an I-frame
+                                        	and size is stored.
+
+    RETURNS
+	
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+	EFAULT			sp points to an invalid iframe.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_FAST_FORWARD, int nFrames);
+
+    DESCRIPTION
+    
+	This ioctl call asks the Video Device to skip decoding of N number of I-frames.
+	This call can only be used if VIDEO_SOURCE_INTRENAL is selected.
+
+    PARAMETERS
+	
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals VIDEO_FAST_FORWARD for this command.
+
+	int nFrames		The number of frames to skip.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL               Internal error
+
+        EPERM			Mode VIDEO_SOURCE_MEMORY not selected.
+
+	EINVAL			Illegal parameter format.
+
+
+
+
+

+ +

+

+
+int ioctl(int fd, int request = VIDEO_SLOWMOTION, int nFrames);
+
+    DESCRIPTION
+
+	This ioctl call asks the Video Device to repeat decoding frames N number of times.
+	This call can only be used if VIDEO_SOURCE_MEMORY is selected.
+
+    PARAMETERS
+
+	int fd			File descriptor returned by a previous call to open().
+
+	int request		Equals VIDEO_SLOWMOTION for this command.
+
+	int nFrames		The number of frames to skip.
+
+    RETURNS
+
+	EBADF			fd is not a valid open file descriptor.
+
+	EINTERNAL		Internal error
+
+        EPERM                   Mode VIDEO_SOURCE_MEMORY not selected.
+
+        EINVAL                  Illegal parameter format.
+
+
+
+
+

+ +

+ +
+ + -- cgit v1.2.3