From 75b63b6d43c650fa4878b2c1671956c657dd0108 Mon Sep 17 00:00:00 2001 From: cvs Date: Wed, 27 Sep 2000 14:54:19 -0300 Subject: Initial revision --- dvb-spec/README.CABLE | 5 +++ dvb-spec/README.EON | 7 ++++ dvb-spec/channel | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+) create mode 100644 dvb-spec/README.CABLE create mode 100644 dvb-spec/README.EON create mode 100644 dvb-spec/channel diff --git a/dvb-spec/README.CABLE b/dvb-spec/README.CABLE new file mode 100644 index 000000000..de13af020 --- /dev/null +++ b/dvb-spec/README.CABLE @@ -0,0 +1,5 @@ +- The analog module is not fully supported yet. + The MSP3400 module will have to be extended to handle then audio and + video switching for the module. + If you want sound you will have to remove the module for now. + diff --git a/dvb-spec/README.EON b/dvb-spec/README.EON new file mode 100644 index 000000000..df5098132 --- /dev/null +++ b/dvb-spec/README.EON @@ -0,0 +1,7 @@ +- If you do not receive any packets over the dvb0 device the reason could + be the rp_filter. + Check if your distribution enables this or disable it with: + + "echo 0 > /proc/sys/net/ipv4/conf/dvb0/rp_filter" + + This disables source validation by reversed path lookup. \ No newline at end of file diff --git a/dvb-spec/channel b/dvb-spec/channel new file mode 100644 index 000000000..f17e8cb19 --- /dev/null +++ b/dvb-spec/channel @@ -0,0 +1,104 @@ +This file describes the format of the new channel config file. + +Comments start with # +Each section starts with one of the identifiers: LNB, DISEQC, ROTOR, ... + +IDs are either the official transponder, network, etc. id if it exists +and is unique, otherwise it is just a consecutive number assigned by +the application. +An LNB can also describe a cable TV outlet or a terrestrial antenna. +Names (as all parameters in brackets) are optional. In this case the +application should use the ID as name. + +The application should offer selection sorted by channel number, network, +satellite, bouquet. + + +# satellite definition +SAT + ID satid # ID = xxxy, sat is at position xxx.y degrees + [NAME name] + LNBID lnbid # LNB this sat is received with + [ROTORID rotorid] # rotor commands to position it on this sat + +# LNB definition +LNB + ID lnbid + [NAME name] + [INPUT input] # input of card which the lnb is connected to (default 0) + TYPE type # LNB, CATV or terrestrial antenna? + LOF1 offset1 # local oscillator frequency 1 + LOF2 offset2 # local oscillator frequency 2 + SLOF switchfreq # switching frequency + [DISEQCNR diseqcnr] # simple 2- or 4-switch DiSEqC + [DISEQCID diseqcid] + [INPUT input] + [SWITCHID switchid] + +# A transponder definition +TRANSPONDER + ID tpid + TYPE type # digital (DVB-S(1), C(2) or T(3)) or analog(0) ? + SATID satid + [NAME name] # if analog this is the channel name + FREQ freq + POL H/V + [QAM qam] # only needed if DVB-C + [SRATE sr] # only if DVB + [FEC fec] # only if DVB + [PICID picid] # picture attributes for all channels on this transponder + +# channel definition (only if DVB) +CHANNEL + ID channelid + [NAME name] + TPID tpid + TYPE type + PNR pnr + VPID vpid + APID apid + TPID tpid + [PMTPID pmtpid] + [PCRPID pcrpid] + [APID apid2 APID apid3 ... APID apidn] # more audio PIDs for several languages + [AC3PID ac3] + [NETWID networkid] + [BOUQID bouquetid] + [PICID picid] + +# network definition +NETWORK + ID nwid + [NAME name] + +# bouquet definition +BOUQUET + ID bqid + [NAME name] + + + +# These will be implemented later + +# DiSEqC command sequence +DISEQC + ID disid + [NAME name] + MESSAGE data1 [ ... datan ] BURST 0/1 END + [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] + +# DiSEqC switch +SWITCH + ID switchid + SWITCHID switchid # next "higher" switch + [NAME name] + MESSAGE data1 [ ... datan ] BURST 0/1 END + + +# DiSEqC rotor command sequence leading to a certain rotor position +ROTOR + ID rotid + POS degrees + MESSAGE data1 [ ... datan ] BURST 0/1 END + [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] + -- cgit v1.2.3 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 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 From fe468b0b8c98736ad218453c397cb062897e8a35 Mon Sep 17 00:00:00 2001 From: rjkm Date: Thu, 8 Feb 2001 01:38:48 -0200 Subject: XML version of full API description --- dvb-spec/API/linux_dvb_api.xml | 3592 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3592 insertions(+) create mode 100644 dvb-spec/API/linux_dvb_api.xml diff --git a/dvb-spec/API/linux_dvb_api.xml b/dvb-spec/API/linux_dvb_api.xml new file mode 100644 index 000000000..b1040ffe5 --- /dev/null +++ b/dvb-spec/API/linux_dvb_api.xml @@ -0,0 +1,3592 @@ + + + +
+ +Linux DVB API + +Documentation + + + + + + Dr. + Ralph + Metzler + rjkm@convergence.de + + + + Andreas + Bogk + bogk@convergence.de + + +feb. 7, 2000 +2000convergence +integrated media GmbH + +
Rosenthalerstr. 51, 10178 Berlin
+ + linux + dvb + api + documentation + + + +About the Linux DVB API + + + +The Linux DVB API is based on a proposal by Nokia. As a commitment to the +development of terminals based on open standards, Nokia and convergence published +it on linuxtv.org. + + + + Convergence is +the maintainer of the Linux DVB API. Together with the LinuxTV community +(i.e. you, the reader of this document), the Linux DVB API will be constantly +reviewed and improved. With the Linux driver for the Siemens/ Hauppauge DVB PCI +card convergence provides a first implementation of the Linux DVB API. + + + + + + + + + + Introduction + + + + 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. + + + A first implementations of the Linux DVB API for the Siemens/ + Hauppauge DVB PCI card is available in the LinuxTV Public + CVS. + + + + + + DVB Devices + + + There are currently 6 DVB devices: Video, Audio, Frontend, SEC, + Demux and CA. The APIs of those devices are described in the + sections below. + + + + 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. + +
+ + + + + + + + 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 + + + +
+ + + + + + + + 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. + + + +
+ + + + + + + + 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 + + + +
+ + + + + + + + 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. + + + +
+ + + + + + + + DVB CA API + + The DVB CA device controls the conditional access hardware. + This allows functionalities like display of menues and entering of PIN numbers. + It can be accessed through /dev/ost/ca. + + + The function calls defined in the include file audio.h are described in + detail below: + + + + CA API IO control calls + + The exact io calls for this device have not been decided on yet. + + + + + + + + + + + + + + + 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 + + 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. + + The type of data returned to the callback can be selected by the + new function int (*set_type) (struct dmx_ts_feed_s* feed, int type, + dmx_ts_pes_t pes_type) which is part of the dmx_ts_feed_s struct + (also cf. to the include file ost/demux.h) + The type parameter decides if the raw TS packet (TS_PACKET) or just the + payload (TS_PACKET|TS_PAYLOAD_ONLY) should be returned. + If additionally the TS_DECODER bit is set the stream will also be sent + to the hardware MPEG decoder. In this case, the second flag decides + as what kind of data the stream should be interpreted. + The possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, + DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, DMX_TS_PES_PCR, or + DMX_TS_PES_OTHER. + + + Returns + + 0 Continue filtering. + + -1 Stop filtering - has the same effect as a call + to stop_filtering() on the TS Feed API. + + + +
+ + +
+ +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. + + + +
+ + + + + + + + + + +
-- cgit v1.2.3 From c2ca96fee8c574074c67c9da023e4165f2f9b2e3 Mon Sep 17 00:00:00 2001 From: rjkm Date: Sun, 16 Sep 2001 22:25:40 -0300 Subject: removed old API docs --- 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 ------- dvb-spec/API/linux_dvb_api.xml | 3592 ------------------------------------ 14 files changed, 8919 deletions(-) delete mode 100644 dvb-spec/API/dvb_api.xml delete mode 100644 dvb-spec/API/dvb_api/audio.h delete mode 100644 dvb-spec/API/dvb_api/audio.xml delete mode 100644 dvb-spec/API/dvb_api/demux.h delete mode 100644 dvb-spec/API/dvb_api/demux.xml delete mode 100644 dvb-spec/API/dvb_api/demux_mod.xml delete mode 100644 dvb-spec/API/dvb_api/dmx.h delete mode 100644 dvb-spec/API/dvb_api/frontend.h delete mode 100644 dvb-spec/API/dvb_api/frontend.xml delete mode 100644 dvb-spec/API/dvb_api/sec.h delete mode 100644 dvb-spec/API/dvb_api/sec.xml delete mode 100644 dvb-spec/API/dvb_api/video.h delete mode 100644 dvb-spec/API/dvb_api/video.xml delete mode 100644 dvb-spec/API/linux_dvb_api.xml diff --git a/dvb-spec/API/dvb_api.xml b/dvb-spec/API/dvb_api.xml deleted file mode 100644 index bd2302551..000000000 --- a/dvb-spec/API/dvb_api.xml +++ /dev/null @@ -1,233 +0,0 @@ - - - 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 deleted file mode 100644 index 8a98f2f98..000000000 --- a/dvb-spec/API/dvb_api/audio.h +++ /dev/null @@ -1,69 +0,0 @@ -/* - * 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 deleted file mode 100644 index 4d6f31575..000000000 --- a/dvb-spec/API/dvb_api/audio.xml +++ /dev/null @@ -1,571 +0,0 @@ - - - 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 deleted file mode 100644 index 62cbf0a58..000000000 --- a/dvb-spec/API/dvb_api/demux.h +++ /dev/null @@ -1,295 +0,0 @@ -/* * 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 deleted file mode 100644 index b15824d0b..000000000 --- a/dvb-spec/API/dvb_api/demux.xml +++ /dev/null @@ -1,568 +0,0 @@ - - - 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 deleted file mode 100644 index c36467977..000000000 --- a/dvb-spec/API/dvb_api/demux_mod.xml +++ /dev/null @@ -1,1215 +0,0 @@ - - - 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 deleted file mode 100644 index e12056514..000000000 --- a/dvb-spec/API/dvb_api/dmx.h +++ /dev/null @@ -1,130 +0,0 @@ -/* - * 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 deleted file mode 100644 index 534a97175..000000000 --- a/dvb-spec/API/dvb_api/frontend.h +++ /dev/null @@ -1,96 +0,0 @@ -/* - * 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 deleted file mode 100644 index 1cd1b0fbd..000000000 --- a/dvb-spec/API/dvb_api/frontend.xml +++ /dev/null @@ -1,843 +0,0 @@ - - - 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 deleted file mode 100644 index f6eda5a0a..000000000 --- a/dvb-spec/API/dvb_api/sec.h +++ /dev/null @@ -1,116 +0,0 @@ -/* - * 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 deleted file mode 100644 index 22062d4a9..000000000 --- a/dvb-spec/API/dvb_api/sec.xml +++ /dev/null @@ -1,430 +0,0 @@ - - - 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 deleted file mode 100644 index de5ac2b19..000000000 --- a/dvb-spec/API/dvb_api/video.h +++ /dev/null @@ -1,95 +0,0 @@ -/* - * 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 deleted file mode 100644 index 18ff9aa28..000000000 --- a/dvb-spec/API/dvb_api/video.xml +++ /dev/null @@ -1,666 +0,0 @@ - - - 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.
-
-
-
-
-

- -

- -
- - diff --git a/dvb-spec/API/linux_dvb_api.xml b/dvb-spec/API/linux_dvb_api.xml deleted file mode 100644 index b1040ffe5..000000000 --- a/dvb-spec/API/linux_dvb_api.xml +++ /dev/null @@ -1,3592 +0,0 @@ - - - -
- -Linux DVB API - -Documentation - - - - - - Dr. - Ralph - Metzler - rjkm@convergence.de - - - - Andreas - Bogk - bogk@convergence.de - - -feb. 7, 2000 -2000convergence -integrated media GmbH - -
Rosenthalerstr. 51, 10178 Berlin
- - linux - dvb - api - documentation - - - -About the Linux DVB API - - - -The Linux DVB API is based on a proposal by Nokia. As a commitment to the -development of terminals based on open standards, Nokia and convergence published -it on linuxtv.org. - - - - Convergence is -the maintainer of the Linux DVB API. Together with the LinuxTV community -(i.e. you, the reader of this document), the Linux DVB API will be constantly -reviewed and improved. With the Linux driver for the Siemens/ Hauppauge DVB PCI -card convergence provides a first implementation of the Linux DVB API. - - - - - - - - - - Introduction - - - - 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. - - - A first implementations of the Linux DVB API for the Siemens/ - Hauppauge DVB PCI card is available in the LinuxTV Public - CVS. - - - - - - DVB Devices - - - There are currently 6 DVB devices: Video, Audio, Frontend, SEC, - Demux and CA. The APIs of those devices are described in the - sections below. - - - - 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. - -
- - - - - - - - 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 - - - -
- - - - - - - - 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. - - - -
- - - - - - - - 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 - - - -
- - - - - - - - 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. - - - -
- - - - - - - - DVB CA API - - The DVB CA device controls the conditional access hardware. - This allows functionalities like display of menues and entering of PIN numbers. - It can be accessed through /dev/ost/ca. - - - The function calls defined in the include file audio.h are described in - detail below: - - - - CA API IO control calls - - The exact io calls for this device have not been decided on yet. - - - - - - - - - - - - - - - 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 - - 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. - - The type of data returned to the callback can be selected by the - new function int (*set_type) (struct dmx_ts_feed_s* feed, int type, - dmx_ts_pes_t pes_type) which is part of the dmx_ts_feed_s struct - (also cf. to the include file ost/demux.h) - The type parameter decides if the raw TS packet (TS_PACKET) or just the - payload (TS_PACKET|TS_PAYLOAD_ONLY) should be returned. - If additionally the TS_DECODER bit is set the stream will also be sent - to the hardware MPEG decoder. In this case, the second flag decides - as what kind of data the stream should be interpreted. - The possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO, - DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE, DMX_TS_PES_PCR, or - DMX_TS_PES_OTHER. - - - Returns - - 0 Continue filtering. - - -1 Stop filtering - has the same effect as a call - to stop_filtering() on the TS Feed API. - - - -
- - -
- -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. - - - -
- - - - - - - - - - -
-- cgit v1.2.3 From 9034551a3bbc76b79a152806c781b1b8e8ea3a9a Mon Sep 17 00:00:00 2001 From: rjkm Date: Sun, 16 Sep 2001 22:27:03 -0300 Subject: new API docs --- dvb-spec/dvbapi/Makefile | 30 ++ dvb-spec/dvbapi/audio.tex | 436 +++++++++++++++++ dvb-spec/dvbapi/bibsection.sty | 29 ++ dvb-spec/dvbapi/ca.tex | 127 +++++ dvb-spec/dvbapi/cimlogo.psi | 122 +++++ dvb-spec/dvbapi/demux.tex | 392 ++++++++++++++++ dvb-spec/dvbapi/devices.tex | 12 + dvb-spec/dvbapi/dvbapi.tex | 166 +++++++ dvb-spec/dvbapi/dvbstb.fig | 59 +++ dvb-spec/dvbapi/examples.tex | 365 +++++++++++++++ dvb-spec/dvbapi/fig2pstex | 6 + dvb-spec/dvbapi/getbb | 12 + dvb-spec/dvbapi/intro.tex | 192 ++++++++ dvb-spec/dvbapi/kdapi.tex | 1007 ++++++++++++++++++++++++++++++++++++++++ dvb-spec/dvbapi/sec.tex | 282 +++++++++++ dvb-spec/dvbapi/title.tex | 24 + dvb-spec/dvbapi/video.tex | 684 +++++++++++++++++++++++++++ 17 files changed, 3945 insertions(+) create mode 100644 dvb-spec/dvbapi/Makefile create mode 100644 dvb-spec/dvbapi/audio.tex create mode 100644 dvb-spec/dvbapi/bibsection.sty create mode 100644 dvb-spec/dvbapi/ca.tex create mode 100644 dvb-spec/dvbapi/cimlogo.psi create mode 100644 dvb-spec/dvbapi/demux.tex create mode 100644 dvb-spec/dvbapi/devices.tex create mode 100644 dvb-spec/dvbapi/dvbapi.tex create mode 100644 dvb-spec/dvbapi/dvbstb.fig create mode 100644 dvb-spec/dvbapi/examples.tex create mode 100755 dvb-spec/dvbapi/fig2pstex create mode 100755 dvb-spec/dvbapi/getbb create mode 100644 dvb-spec/dvbapi/intro.tex create mode 100644 dvb-spec/dvbapi/kdapi.tex create mode 100644 dvb-spec/dvbapi/sec.tex create mode 100644 dvb-spec/dvbapi/title.tex create mode 100644 dvb-spec/dvbapi/video.tex diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile new file mode 100644 index 000000000..fe9827cff --- /dev/null +++ b/dvb-spec/dvbapi/Makefile @@ -0,0 +1,30 @@ +all: dvbapi.ps dvbapi.pdf + +TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex sec.tex frontend.tex \ + intro.tex title.tex dvbstb.ps + +dvbapi.pdf: dvbapi.dvi + dvipdf $< $@ + +dvbapi.ps: dvbapi.dvi + dvips -o $@ $< + +dvbapi.dvi: dvbapi.bbl $(TEXS) + -latex dvbapi + -bibtex dvbapi + -makeindex dvbapi + -latex dvbapi + -latex dvbapi + +dvbapi.bbl: $(TEXS) + -latex dvbapi + -bibtex dvbapi + -makeindex dvbapi + +%.ps: %.fig + ./fig2pstex $< + +clean: + rm -f dvbapi.dvi + rm -f *.aux *.bbl *.blg *.idx *.ilg *.ind *.log *.out *.toc + rm -f *.pdf *.pst *.ps diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex new file mode 100644 index 000000000..8c5b4fe82 --- /dev/null +++ b/dvb-spec/dvbapi/audio.tex @@ -0,0 +1,436 @@ +\devsec{DVB Audio Device} + +The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. +It can be accessed through \texttt{/dev/ost/audio}. + + +\devsubsec{Audio Data Types} + +This section describes the structures, data types and defines used when +talking to the audio device. + +\devsubsubsec{audioStreamSource\_t} +\label{audiostreamsource} +The audio stream source is set through the AUDIO\_SELECT\_SOURCE +call and can take the following values, depending on whether we are +replaying from an internal (demuxer) or external (user write) source. +\begin{verbatim} +typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY +} audioStreamSource_t; +\end{verbatim} +AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed +either by the frontend or the DVR device) as the source of +the video stream. +If AUDIO\_SOURCE\_MEMORY is selected the stream +comes from the application through the \texttt{write()} +system call. + +\devsubsubsec{audioPlayState\_t} +The following values can be returned by the AUDIO\_GET\_STATUS call +representing the state of audio playback. +\label{audioplaystate} +\begin{verbatim} +typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED +} audioPlayState_t; +\end{verbatim} + +\devsubsubsec{audioChannelSelect\_t} +\label{audiochannelselect} +The audio channel selected via AUDIO\_CHANNEL\_SELECT is determined by +the following values. +\begin{verbatim} +typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, +} audioChannelSelect_t; +\end{verbatim} + +\devsubsubsec{audioStatus\_t} +\label{audiostatus} +The AUDIO\_GET\_STATUS call returns the following structure informing +about various states of the playback operation. +\begin{verbatim} +typedef struct audioStatus { + boolean AVSyncState; + boolean muteState; + audioPlayState_t playState; + audioStreamSource_t streamSource; + audioChannelSelect_t channelSelect; + boolean bypassMode; +} audioStatus_t; +\end{verbatim} + +\devsubsubsec{audioMixer\_t} +\label{audiomixer} +The following structure is used by the AUDIO\_SET\_MIXER call to set +the audio volume. +\begin{verbatim} +typedef struct audioMixer { + unsigned int volume_left; + unsigned int volume_right; +} audioMixer_t; +\end{verbatim} + +\devsubsubsec{audio encodings} +\label{audiotypes} +A call to AUDIO\_GET\_CAPABILITIES returns an unsigned integer with +the following bits set according to the hardwares capabilities. +\begin{verbatim} +#define AUDIO_CAP_DTS 1 +#define AUDIO_CAP_LPCM 2 +#define AUDIO_CAP_MP1 4 +#define AUDIO_CAP_MP2 8 +#define AUDIO_CAP_MP3 16 +#define AUDIO_CAP_AAC 32 +#define AUDIO_CAP_OGG 64 +#define AUDIO_CAP_SDDS 128 +#define AUDIO_CAP_AC3 256 +\end{verbatim} + + +\devsubsubsec{audio karaoke} +\label{audiokaraoke} +The ioctl AUDIO\_SET\_KARAOKE uses the following format: +\begin{verbatim} +typedef +struct audioKaraoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ + int vocal1; /* into left and right t at 70% each */ + int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets */ + int melody; /* mixed into the left channel and */ + /* Vocal2 into the right channel at 100% each. */ + /* if Melody is non-zero, the melody channel gets mixed */ /* into left and right */ +} audioKaraoke_t; +\end{verbatim} + +\devsubsubsec{audio attributes} +\label{aattrib} +The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES: +\begin{verbatim} +typedef uint16_t audioAttributes_t; +/* bits: descr. */ +/* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ +/* 12 multichannel extension */ +/* 11-10 audio type (0=not spec, 1=language included) */ +/* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */ +/* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */ +/* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */ +/* 2- 0 number of audio channels (n+1 channels) */ +\end{verbatim} + + +\clearpage + +\devsubsec{Audio Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + 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 error code will be returned. + If the Audio Device is opened in O\_RDONLY mode, the only ioctl call that can + be used is AUDIO\_GET\_STATUS. All other call will return with an error code. + }{ + const char *deviceName & Name of specific audio device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened audio device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\function{write()}{ + size\_t write(int fd, const void *buf, size\_t count);}{ + 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. + }{ + 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.\\ + }{ + EPERM& Mode AUDIO\_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.\\ +} + +\ifunction{AUDIO\_STOP}{ + int ioctl(int fd, int request = AUDIO\_STOP);}{ + This ioctl call asks the Audio Device to stop playing the current stream. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals AUDIO\_STOP for this command. + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_PLAY}{ + int ioctl(int fd, int request = AUDIO\_PLAY);}{ + This ioctl call asks the Audio Device to start playing an audio stream + from the selected source. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals AUDIO\_PLAY for this command. + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_PAUSE}{ + int ioctl(int fd, int request = AUDIO\_PAUSE);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals AUDIO\_PAUSE for this command. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_SELECT\_SOURCE}{ + int ioctl(int fd, int request = AUDIO\_SELECT\_SOURCE, + audioStreamSource\_t source);}{ + 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. + }{ + 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. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_SET\_MUTE}{ + int ioctl(int fd, int request = AUDIO\_SET\_MUTE, boolean state);}{ + This ioctl call asks the audio device to mute the stream that is + currently being played. + }{ + 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 Un-mute\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_SET\_AV\_SYNC}{ + int ioctl(int fd, int request = AUDIO\_SET\_AV\_SYNC, boolean state);}{ + This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization. + }{ + 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 + synchronization shall be ON or OFF.\\ + & TRUE AV-sync ON \\ + & FALSE AV-sync OFF\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_SET\_BYPASS\_MODE}{ + int ioctl(int fd, int request = AUDIO\_SET\_BYPASS\_MODE, boolean mode);}{ + This ioctl call asks the Audio Device to bypass the Audio decoder and forward + the stream without decoding. This mode shall be used if streams that can't be + handled by the DVB system shall be decoded. + Dolby DigitalTM streams are automatically forwarded by the DVB + subsystem if the hardware can handle it. + }{ + 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\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_CHANNEL\_SELECT}{ + int ioctl(int fd, int request = AUDIO\_CHANNEL\_SELECT, + audioChannelSelect\_t);}{ + This ioctl call asks the Audio Device to select the requested channel + if possible. + }{ + 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 left/right, stereo). + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter ch. +} + +\ifunction{AUDIO\_GET\_STATUS}{ + int ioctl(int fd, int request = AUDIO\_GET\_STATUS, + struct audioStatus *status);}{ + This ioctl call asks the Audio Device to return the current state + of the Audio Device. + }{ + 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. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EFAULT & status points to invalid address. +} + +\ifunction{AUDIO\_GET\_CAPABILITIES}{ + int ioctl(int fd, int request = AUDIO\_GET\_CAPABILITIES, + unsigned int *cap);}{ + This ioctl call asks the Audio Device to tell us about the + decoding capabilities of the audio hardware. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_GET\_CAPABILITIES for this command.\\ + unsigned int *cap & Returns a bit array of supported sound formats. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EFAULT & cap points to an invalid address. +} + +\ifunction{AUDIO\_CLEAR\_BUFFER}{ + int ioctl(int fd, int request = AUDIO\_CLEAR\_BUFFER);}{ + This ioctl call asks the Audio Device to clear all software + and hardware buffers of the audio decoder device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_CLEAR\_BUFFER for this command. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_SET\_ID}{ + int ioctl(int fd, int request = AUDIO\_SET\_ID, int id);}{ + This ioctl selects which sub-stream is to be decoded if a program or + system stream is sent to the video device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_ID for this command.\\ + int id& audio sub-stream id + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Invalid sub-stream id. +} + +\ifunction{AUDIO\_SET\_MIXER}{ + int ioctl(int fd, int request = AUDIO\_SET\_MIXER, audioMixer\_t *mix);}{ + This ioctl lets you adjust the mixer settings of the audio decoder. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_ID for this command.\\ + audioMixer\_t *mix& mixer settings. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EFAULT & mix points to an invalid address. +} + +\ifunction{AUDIO\_SET\_STREAMTYPE}{ + int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, int type);}{ + This ioctl tells the driver which kind of audio stream to expect. + This is useful if the stream offers several audio sub-streams + like MPEG2 audio and AC3. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ + int type & stream type\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& type is not a valid or supported stream type.\\ +} + + +\ifunction{AUDIO\_SET\_EXT\_ID}{ + int ioctl(fd, int request = AUDIO\_SET\_EXT\_ID, int id);}{ + This ioctl can be used to set the audio sub\_stream\_id for DVD playback + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_EXT\_ID for this command.\\ + int id & audio sub\_stream\_id\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& id is not a valid id.\\ +} + +\ifunction{AUDIO\_SET\_ATTRIBUTES}{ + int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audioAttributes\_t attr );}{ + This ioctl is intended for DVD playback and allows you to set + certain information about the audio stream. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_ATTRIBUTES for this command.\\ + iaudioAttributes\_t attr & audio attributes according to section \ref{aattrib}\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& attr is not a valid or supported attribute setting.\\ +} + +\ifunction{AUDIO\_SET\_KARAOKE}{ + int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, audioKaraoke\_t *karaoke);}{ + This ioctl allows one to set the mixer settings for a karaoke DVD. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ + audioKaraoke\_t *karaoke & karaoke settings according to section \ref{audiokaraoke}.\\ + }{ + EBADF & fd is not a valid open file descriptor \\ + EINVAL& karaoke is not a valid or supported karaoke setting.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/bibsection.sty b/dvb-spec/dvbapi/bibsection.sty new file mode 100644 index 000000000..7f9eedc6a --- /dev/null +++ b/dvb-spec/dvbapi/bibsection.sty @@ -0,0 +1,29 @@ +\def\thebibliography#1{\chapter*{\bibname\@mkboth + {\uppercase{\bibname}}{\uppercase{\bibname}}} + \setcounter{chapter}{0} + \setcounter{section}{0} + \def\thechapter{Bib} + \def\thesection{\Alph{section}} + \edef\biblab{#1} + \addcontentsline{toc}{chapter}{\bibname} + } + +\def\bibtitle#1#2{\expandafter\def\csname bibtitle#1\endcsname{ + \bibsection{#2}} } + +\def\bibsection#1{\section{#1} + \begin{list} + {\@biblabel{\arabic{enumiv}}}{\settowidth\labelwidth{\@biblabel{\biblab}}% + \leftmargin\labelwidth + \advance\leftmargin\labelsep + \usecounter{enumiv}% + \let\p@enumiv\@empty + \def\theenumiv{\arabic{enumiv}}}% + \def\newblock{\hskip .11em plus.33em minus.07em}% + \sloppy\clubpenalty4000\widowpenalty4000 + \sfcode`\.=\@m} + +\def\endbibsection{\end{list}} + +\def\endthebibliography{\endbibsection} + diff --git a/dvb-spec/dvbapi/ca.tex b/dvb-spec/dvbapi/ca.tex new file mode 100644 index 000000000..eba512b1b --- /dev/null +++ b/dvb-spec/dvbapi/ca.tex @@ -0,0 +1,127 @@ +\devsec{DVB CA Device} + +The DVB CA device controls the conditional access hardware. +It can be accessed through \texttt{/dev/ost/ca}. + + +\devsubsec{CA Data Types} + +\devsubsubsec{ca\_slot\_info\_t} +\label{caslotinfo} + +\begin{verbatim} +/* slot interface types and info */ + +typedef struct ca_slot_info_s { + int num; /* slot number */ + + int type; /* CA interface this slot supports */ +#define CA_CI 1 /* CI high level interface */ +#define CA_CI_LINK 2 /* CI link layer level interface */ +#define CA_CI_PHYS 4 /* CI physical layer level interface */ +#define CA_SC 128 /* simple smart card interface */ + + unsigned int flags; +#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ +#define CA_CI_MODULE_READY 2 +} ca_slot_info_t; +\end{verbatim} + +\devsubsubsec{ca\_descr\_info\_t} +\label{cadescrinfo} + +\begin{verbatim} +typedef struct ca_descr_info_s { + unsigned int num; /* number of available descramblers (keys) */ + unsigned int type; /* type of supported scrambling system */ +#define CA_ECD 1 +#define CA_NDS 2 +#define CA_DSS 4 +} ca_descr_info_t; +\end{verbatim} + +\devsubsubsec{ca\_cap\_t} +\label{cacap} + +\begin{verbatim} +typedef struct ca_cap_s { + unsigned int slot_num; /* total number of CA card and module slots */ + unsigned int slot_type; /* OR of all supported types */ + unsigned int descr_num; /* total number of descrambler slots (keys) */ + unsigned int descr_type;/* OR of all supported types */ +} ca_cap_t; +\end{verbatim} + + +\devsubsubsec{ca\_msg\_t} +\label{camsg} + +\begin{verbatim} +/* a message to/from a CI-CAM */ +typedef struct ca_msg_s { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; +} ca_msg_t; +\end{verbatim} + + +\devsubsubsec{ca\_descr\_t} +\label{cadescr} + +\begin{verbatim} +typedef struct ca_descr_s { + unsigned int index; + unsigned int parity; + unsigned char cw[8]; +} ca_descr_t; +\end{verbatim} + +\clearpage + +\devsubsec{CA Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named ca device (e.g. /dev/ost/ca) + 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 CA Device in O\_RDWR mode. All other attempts to + open the device in this mode will fail, and an error code will be returned. + }{ + const char *deviceName & Name of specific video device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened audio device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/cimlogo.psi b/dvb-spec/dvbapi/cimlogo.psi new file mode 100644 index 000000000..b7b089a49 --- /dev/null +++ b/dvb-spec/dvbapi/cimlogo.psi @@ -0,0 +1,122 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: /home/rjkm/dvbapi/cimlogo.ps +%%Creator: XV Version 3.10a Rev: 12/29/94 (PNG patch 1.2) - by John Bradley +%%BoundingBox: 275 411 309 440 +%%Pages: 1 +%%DocumentFonts: +%%EndComments +%%EndProlog + +%%Page: 1 1 + +% remember original state +/origstate save def + +% build a temporary dictionary +20 dict begin + +% define string to hold a scanline's worth of data +/pix 45 string def + +% define space for color conversions +/grays 45 string def % space for gray scale line +/npixls 0 def +/rgbindx 0 def + +% lower left corner +275 411 translate + +% size of image (on paper, in 1/72inch coords) +33.76800 28.51200 scale + +45 38 8 % dimensions of data +[45 0 0 -38 0 38] % mapping matrix +{currentfile pix readhexstring pop} +image + +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffffff000000ffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffff0000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffff000000000000ffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffff00ffffffffffff0000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffff0000000000ffffffff000000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffff0000000000000000ffffff000000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffff0000000000000000ffffffff000000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffff000000000000000000ffffff000000000000ffffffffffffffffffffff +ffffffffffffffffff +ffffffffffff0000000000000000ffffffffff000000000000ffffff00000000ffffffff +ffffffffffffffffff +ffffffffff00000000000000ffffffffffffff0000000000ffffff0000000000ffffffff +ffffffffffffffffff +ffffffffff000000000000ffffffffffffff000000000000ffffff000000000000ffffff +ffffffffffffffffff +ffffffff00000000000000ffffffffffffff000000000000ffffffff000000000000ffff +ffffffffffffffffff +ffffffff000000000000ffffffffffffffff000000000000ffffffff000000000000ffff +ffffffffffffffffff +ffffffff0000000000ffffffffffffffff000000000000ffffffffffff0000000000ffff +ffffffffffffffffff +ffffff000000000000ffffffffffffffff000000000000ffffffffffff0000000000ffff +ffffffffffffffffff +ffffff0000000000ffffffffffffffffff000000000000ffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffffff0000000000ffffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffff000000000000ffffffffffffffff0000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffff000000000000ffffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffff0000000000ffffffffffffffffff0000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffff000000000000ffffffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffff000000000000ffffffffffffffff0000000000ffff +ffffffffffffffffff +ffffff000000000000ffffffffffffff00000000ffffffffffffffffff0000000000ffff +ffffffffffffffffff +ffffffff0000000000ffffffffffffffff0000ffffffffffffffffff000000000000ffff +ffffffffffffffffff +ffffffff000000000000ffffffffffffffffffffffffffffffffffff000000000000ffff +ffffffffffffffffff +ffffffff000000000000ffffffffffffffffffffffffffffffffff000000000000ffffff +ffffffffffffffffff +ffffffffff00000000000000ffffffffffffffffffffffffffff000000000000ffffffff +ff0000000000ffffff +ffffffffff0000000000000000ffffffffffffffffffffffff00000000000000ffffffff +00000000000000ffff +ffffffffffff000000000000000000ffffffffffffffff0000000000000000ffffffffff +00000000000000ffff +ffffffffffffff0000000000000000000000000000000000000000000000ffffffffffff +0000000000000000ff +ffffffffffffffff000000000000000000000000000000000000000000ffffffffffffff +00000000000000ffff +ffffffffffffffffffff0000000000000000000000000000000000ffffffffffffffffff +00000000000000ffff +ffffffffffffffffffffffff00000000000000000000000000ffffffffffffffffffffff +ff0000000000ffffff +ffffffffffffffffffffffffffffff00ff0000000000ffffffffffffffffffffffffffff +ffffff0000ffffffff +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff + +showpage + +% stop using temporary dictionary +end + +% restore original state +origstate restore + +%%Trailer diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex new file mode 100644 index 000000000..541ee633a --- /dev/null +++ b/dvb-spec/dvbapi/demux.tex @@ -0,0 +1,392 @@ +\devsec{DVB Demux Device} + +The DVB demux device controls the filters of the DVB hardware/software. +It can be accessed through \texttt{/dev/ost/demux}. + +\devsubsec{Demux Data Types} + +\begin{verbatim} +typedef uint16_t dvb_pid_t; +\end{verbatim} + + +\devsubsubsec{dmxOutput\_t} +\label{dmxoutput} + +\begin{verbatim} +typedef enum +{ + DMX_OUT_DECODER, + DMX_OUT_TAP, + DMX_OUT_TS_TAP +} dmxOutput_t; +\end{verbatim} +/* Output multiplexed into a new TS */ +/* (to be retrieved by reading from the */ +/* logical DVR device). */ + + +\devsubsubsec{dmxInput\_t} +\label{dmxinput} + +\begin{verbatim} +typedef enum +{ + DMX_IN_FRONTEND, /* Input from a front-end device. */ + DMX_IN_DVR /* Input from the logical DVR device. */ +} dmxInput_t; +\end{verbatim} + + +\devsubsubsec{dmxPesType\_t} +\label{dmxpestype} + +\begin{verbatim} +typedef enum +{ + DMX_PES_AUDIO, + DMX_PES_VIDEO, + DMX_PES_TELETEXT, + DMX_PES_SUBTITLE, + DMX_PES_PCR, + DMX_PES_OTHER +} dmxPesType_t; +\end{verbatim} + + +\devsubsubsec{dmxEvent\_t} +\label{dmxeventt} + +\begin{verbatim} +typedef enum +{ + DMX_SCRAMBLING_EV, + DMX_FRONTEND_EV +} dmxEvent_t; +\end{verbatim} + + +\devsubsubsec{dmxScramblingStatus\_t} +\label{dmxscramblingstatus} + +\begin{verbatim} +typedef enum +{ + DMX_SCRAMBLING_OFF, + DMX_SCRAMBLING_ON +} dmxScramblingStatus_t; +\end{verbatim} + + +\devsubsubsec{dmxFilter\_t} +\label{dmxfilter} + +\begin{verbatim} +typedef struct dmxFilter +{ + uint8_t filter[DMX_FILTER_SIZE]; + uint8_t mask[DMX_FILTER_SIZE]; +} dmxFilter_t; +\end{verbatim} + + +\devsubsubsec{dmxSctFilterParams} +\label{dmxsctfilterparams} + +\begin{verbatim} +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 +}; +\end{verbatim} + + +\devsubsubsec{dmxPesFilterParams} +\label{dmxpesfilterparams} + +\begin{verbatim} +struct dmxPesFilterParams +{ + dvb_pid_t pid; + dmxInput_t input; + dmxOutput_t output; + dmxPesType_t pesType; + uint32_t flags; +}; +\end{verbatim} + + +\devsubsubsec{dmxEvent} +\label{dmxevent} + +\begin{verbatim} +struct dmxEvent +{ + dmxEvent_t event; + time_t timeStamp; + union + { + dmxScramblingStatus_t scrambling; + } u; +}; +\end{verbatim} + +\clearpage + +\devsubsec{Demux Function Calls} +\function{open()}{ + int open(const char *deviceName, int flags);}{ + 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 functionality. When reading from + this device a transport stream containing the packets from all PES + filters set in the corresponding demux device (/dev/ost/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. + }{ + const char *deviceName & Name of demux device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + 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.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call deactivates and deallocates a filter that was previously + allocated via the open() call. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\function{read()}{ + size\_t read(int fd, void *buf, size\_t count); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + void *buf & Pointer to the buffer to be used for returned filtered data.\\ + size\_t count & Size of buf.\\ + }{ + 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.\\ +} + +\function{write()}{ + ssize\_t write(int fd, const void *buf, size\_t count); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + void *buf & Pointer to the buffer containing the Transport Stream.\\ + size\_t count & Size of buf.\\ + }{ + 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.\\ +} + +\ifunction{DMX\_START}{ + int ioctl( int fd, int request = DMX\_START); + }{ + This ioctl call is used to start the actual filtering operation + defined via the ioctl calls DMX\_SET\_FILTER or DMX\_SET\_PES\_FILTER. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_START for this command.\\ + }{ + 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.\\ +} + +\ifunction{DMX\_STOP}{ + int ioctl( int fd, int request = DMX\_STOP); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_STOP for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ +} + +\ifunction{DMX\_SET\_FILTER}{ + int ioctl( int fd, int request = DMX\_SET\_FILTER, struct dmxSctFilterParams *params); + }{ + This ioctl call sets up a filter according to the filter and mask + parameters provided. A timeout may be defined stating number of seconds + to wait for a section to be loaded. A value of 0 means that no timeout + should be applied. Finally there is a flag field where it is possible to + state whether a section should be CRC-checked, whether the filter should + be a "one-shot" filter, i.e. if the filtering operation should be stopped + after the first section is received, and whether the filtering operation + should be started immediately (without waiting for a DMX\_START ioctl call). + If a filter was previously set-up, this filter will be canceled, and the + receive buffer will be flushed. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_SET\_FILTER for this command.\\ + struct dmxSctFilterParams *params + & Pointer to structure containing filter parameters.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EINVAL & Invalid argument.\\ +} + +\ifunction{DMX\_SET\_PES\_FILTER}{ + int ioctl( int fd, int request = DMX\_SET\_PES\_FILTER, + struct dmxPesFilterParams *params); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_SET\_PES\_FILTER for this command.\\ + struct dmxPesFilterParams *params + & Pointer to structure containing filter parameters.\\ + }{ + 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.\\ +} + +\ifunction{DMX\_SET\_BUFFER\_SIZE}{ + int ioctl( int fd, int request = DMX\_SET\_BUFFER\_SIZE, unsigned long size); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_SET\_BUFFER\_SIZE for this command.\\ + unsigned long size & Size of circular buffer.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + ENOMEM & The driver was not able to allocate a buffer of the requested size.\\ +} + +\ifunction{DMX\_GET\_EVENT}{ + int ioctl( int fd, int request = DMX\_GET\_EVENT, struct dmxEvent *ev); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_GET\_EVENT for this command.\\ + struct dmxEvent *ev & Pointer to the location where the event is to be stored.\\ + }{ + 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.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/devices.tex b/dvb-spec/dvbapi/devices.tex new file mode 100644 index 000000000..9c561e853 --- /dev/null +++ b/dvb-spec/dvbapi/devices.tex @@ -0,0 +1,12 @@ +\input{video.tex} +\input{audio.tex} +\input{frontend.tex} +\input{sec.tex} +\input{demux.tex} +\input{ca.tex} +\input{kdapi.tex} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex new file mode 100644 index 000000000..f9fcb841c --- /dev/null +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -0,0 +1,166 @@ +\documentclass[10pt]{book} +\usepackage[dvips,colorlinks=true]{hyperref} + +\usepackage{times} + +%\usepackage[hang]{caption} +\usepackage{fancyheadings} +%\usepackage{lucidabr} +%\usepackage{fancybox} +\usepackage{array} +\usepackage{graphicx} +%\usepackage{latexsym} +%\usepackage{pstricks,pst-node,pst-tree} +%\usepackage{verbatim} +%\usepackage{rotating} +%\usepackage{pdftex} +%\usepackage{color} +%\usepackage{subfigure} +%\usepackage{wrapfig} + +\newcommand{\devsec}[1]{\chapter{#1}} +\newcommand{\devsubsec}[1]{\section{#1}} +\newcommand{\devsubsubsec}[1]{\subsection{#1}} +\newcommand{\function}[5]{ + \subsection{#1} + + \noindent DESCRIPTION + \medskip + + \begin{tabular}[h]{p{11cm}} + #3 + \end{tabular} + + \medskip + \noindent SYNOPSIS + \medskip + + \begin{tabular}[h]{p{11cm}} + {\tt #2} + \end{tabular} + + %\item[] +\medskip +\noindent PARAMETERS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #4 + \end{tabular} + + %\item[] +\medskip +\noindent ERRORS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #5 + \end{tabular} + + %\end{itemize} + +\medskip +} +\def\ifunction#1#2#3#4#5{\function{#1\index{#1}}{#2}{#3}{#4}{#5}} + +\newcommand{\kfunction}[5]{ + \subsection{#1} + \noindent DESCRIPTION + \medskip + + \begin{tabular}[h]{p{11cm}} + #3 + \end{tabular} + + \medskip + \noindent SYNOPSIS + \medskip + + \begin{tabular}[h]{p{11cm}} + {\tt #2} + \end{tabular} + + %\item[] +\medskip +\noindent PARAMETERS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #4 + \end{tabular} + + %\item[] +\medskip +\noindent RETURNS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #5 + \end{tabular} + + %\end{itemize} + +\medskip +} +\def\kifunction#1#2#3#4#5{\kfunction{#1\index{#1}}{#2}{#3}{#4}{#5}} + + +%\usepackage{index} +%\makeindex + + +\begin{document} + +\input{title.tex} + +\cleardoublepage + +\pagenumbering{roman} +\pagestyle{fancyplain} + + +\tableofcontents +%\listoffigures +%\listoftables + +\cleardoublepage + +\pagenumbering{arabic} + +\renewcommand{\chaptermark}[1]{\markboth{\uppercase{#1}}{}} +\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} +\lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} +\rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} +\cfoot{\copyright 2001 convergence integrated media GmbH} + +\input{intro.tex} + +\input{devices.tex} + +\input{examples.tex} + +\cleardoublepage + +\appendix + +\cleardoublepage + +\thispagestyle{plain}\chaptermark{Bibliography} +\addcontentsline{toc}{chapter}{Bibliography} +\bibliographystyle{bibsec} +\bibliography{main} + +\cleardoublepage + +\thispagestyle{plain}\chaptermark{Subject Index} +\addcontentsline{toc}{chapter}{Subject Index} +%\printindex + +\cleardoublepage + +\end{document} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: diff --git a/dvb-spec/dvbapi/dvbstb.fig b/dvb-spec/dvbapi/dvbstb.fig new file mode 100644 index 000000000..0a6bbadc3 --- /dev/null +++ b/dvb-spec/dvbapi/dvbstb.fig @@ -0,0 +1,59 @@ +#FIG 3.2 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1620 360 2520 360 2520 900 1620 900 1620 360 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 1260 1080 1620 630 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 2520 630 2880 630 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2880 360 3780 360 3780 900 2880 900 2880 360 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 0 0 1.00 60.00 120.00 + 4590 900 3330 1170 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 0 0 1.00 60.00 120.00 + 4590 900 4590 1170 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4140 360 5040 360 5040 900 4140 900 4140 360 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3780 630 4140 630 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4140 1170 5040 1170 5040 1710 4140 1710 4140 1170 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2880 1170 3780 1170 3780 1710 2880 1710 2880 1170 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1620 1170 2520 1170 2520 1710 1620 1710 1620 1170 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 0 0 1.00 60.00 120.00 + 1620 1440 1260 1080 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1350 225 5175 225 5175 1845 1350 1845 1350 225 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3240 1710 3960 2070 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4590 1710 3960 2070 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3510 2070 4410 2070 4410 2610 3510 2610 3510 2070 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 360 810 1260 810 1260 1350 360 1350 360 810 +4 0 0 50 0 0 12 0.0000 4 135 675 1755 675 Frontend\001 +4 0 0 50 0 0 12 0.0000 4 135 690 4275 675 Demuxer\001 +4 0 0 50 0 0 12 0.0000 4 135 450 4365 1485 Video\001 +4 0 0 50 0 0 12 0.0000 4 135 450 3105 1485 Audio\001 +4 0 0 50 0 0 12 0.0000 4 135 345 1890 1485 SEC\001 +4 0 0 50 0 0 12 0.0000 4 135 255 3195 675 CA\001 +4 0 0 50 0 0 12 0.0000 4 135 645 495 1125 Antenna\001 +4 0 0 50 0 0 12 0.0000 4 135 240 3870 2385 TV\001 diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex new file mode 100644 index 000000000..d2786a6f6 --- /dev/null +++ b/dvb-spec/dvbapi/examples.tex @@ -0,0 +1,365 @@ +\chapter{Examples} +In this section we would like to present some examples for using the DVB API. + +\section{Tuning} +We will start with a generic tuning subroutine that uses the frontend +and SEC, as well as the demux devices. The example is given for QPSK +tuners, but can easily be adjusted for QAM. + +{\small +\begin{verbatim} +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +#define DMX "/dev/ost/demux" +#define QPSK "/dev/ost/qpskfe" +#define SEC "/dev/ost/sec" + +/* routine for checking if we have a signal */ +int has_signal(int front) +{ + feStatus stat; + + if ( front < 0 ){ + if((front = open(QPSK,O_RDWR)) < 0){ + perror("FRONTEND DEVICE: "); + return -1; + } + } + + FEReadStatus(front, &stat); + if (stat & FE_HAS_SIGNAL) + return 0; + else { + printf("Tuning failed\n"); + return -1; + } +} + +/* tune qpsk */ +/* freq: frequency of transponder */ +/* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */ +/* diseqc: DiSEqC address of the used LNB */ +/* pol: Polarisation */ +/* srate: Symbol Rate */ +/* fec. FEC */ +/* lnb_lof1: local frequency of lower LNB band */ +/* lnb_lof2: local frequency of upper LNB band */ +/* lnb_slof: switch frequency of LNB */ + +int set_qpsk_channel(int freq, int vpid, int apid, int tpid, + int diseqc, int pol, int srate, int fec, int lnb_lof1, + int lnb_lof2, int lnb_slof) +{ + struct secCommand scmd; + struct secCmdSequence scmds; + struct dmxPesFilterParams pesFilterParams; + struct qpskParameters qpsk; + struct pollfd pfd[1]; + struct qpskEvent event; + int front, sec, demux1, demux2, demux3; + + /* Open all the necessary the devices */ + + if((front = open(QPSK,O_RDWR)) < 0){ + perror("FRONTEND DEVICE: "); + return -1; + } + + if((sec = open(SEC,O_RDWR)) < 0){ + perror("SEC DEVICE: "); + return -1; + } + + if ((demux1 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + + if ((demux2 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + + if ((demux3 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + + /* Set the frequency of the transponder, taking into account the + local frequencies of the LNB */ + + if (freq < lnb_slof) { + qpsk.iFrequency = (freq - lnb_lof1); + scmds.continuousTone = SEC_TONE_OFF; + } else { + qpsk.iFrequency = (freq - lnb_lof2); + scmds.continuousTone = SEC_TONE_ON; + } + + /* Set the polarity of the transponder by setting the correct + voltage on the universal LNB */ + + if (pol) scmds.voltage = SEC_VOLTAGE_18; + else scmds.voltage = SEC_VOLTAGE_13; + + /* In case we have a DiSEqC, set it to the correct address */ + + scmd.type=0; + scmd.u.diseqc.addr=0x10; + scmd.u.diseqc.cmd=0x38; + scmd.u.diseqc.numParams=1; + scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) | + (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | + (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); + + scmds.miniCommand=SEC_MINI_NONE; + scmds.numCommands=1; + scmds.commands=&scmd; + + /* Send the data to the SEC device to prepare the LNB for tuning */ + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + /* Set symbol rate and FEC */ + + qpsk.SymbolRate = srate; + qpsk.FEC_inner = fec; + + /* Now send it all to the frontend device */ + if (ioctl(front, QPSK_TUNE, &qpsk) < 0){ + perror("QPSK TUNE: "); + return -1; + } + + /* poll for QPSK event to check if tuning worked */ + pfd[0].fd = front; + pfd[0].events = POLLIN; + + if (poll(pfd,1,3000)){ + if (pfd[0].revents & POLLIN){ + printf("Getting QPSK event\n"); + if ( ioctl(front, QPSK_GET_EVENT, &event) + + == -EBUFFEROVERFLOW){ + perror("qpsk get event"); + return -1; + } + printf("Received "); + switch(event.type){ + case FE_UNEXPECTED_EV: + printf("unexpected event\n"); + return -1; + case FE_FAILURE_EV: + printf("failure event\n"); + return -1; + case FE_COMPLETION_EV: + printf("completion event\n"); + } + } + } + + + /* Set the filters for video, audio and teletext demuxing */ + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pesType = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_vpid"); + return -1; + } + + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pesType = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_apid"); + return -1; + } + + pesFilterParams.pid = tpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pesType = DMX_PES_TELETEXT; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_tpid"); + return -1; + } + + /* check if we have a signal */ + return has_signal(front); +} + +\end{verbatim} +} +The program assumes that you are using a universal LNB and a standard +DiSEqC switch with up to 4 addresses. Of course, you could build in +some more checking if tuning was successful and maybe try to repeat +the tuning process. Depending on the external hardware, i.e. LNB and +DiSEqC switch, and weather conditions this may be necessary. + + +\section{The DVR device} +The following program code shows how to use the DVR device for +recording. + +{\small +\begin{verbatim} +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#define DVR "/dev/ost/dvr" +#define AUDIO "/dev/ost/audio" +#define VIDEO "/dev/ost/video" + +#define BUFFY (188*20) +#define MAX_LENGTH (1024*1024*5) /* record 5MB */ + + +/* switch the demuxes to recording, assuming the transponder is tuned */ + +/* demux1, demux2: file descriptor of video and audio filters */ +/* vpid, apid: PIDs of video and audio channels */ + +int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) +{ + struct dmxPesFilterParams pesFilterParams; + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMXdemuxs, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pesType = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pesType = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + return 0; +} + +/* start recording MAX_LENGTH , assuming the transponder is tuned */ + +/* demux1, demux2: file descriptor of video and audio filters */ +/* vpid, apid: PIDs of video and audio channels */ +int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) +{ + int i; + int len; + int written; + uint8_t buf[BUFFY]; + uint64_t length; + struct pollfd pfd[1]; + int dvr, dvr_out; + + /* open dvr device */ + if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ + perror("DVR DEVICE"); + return -1; + } + + /* switch video and audio demuxes to dvr */ + printf ("Switching dvr on\n"); + i = switch_to_record(demux1, demux2, vpid, apid); + printf("finished: "); + + printf("Recording %2.0f MB of test file in TS format\n", + MAX_LENGTH/(1024.0*1024.0)); + length = 0; + + /* open output file */ + if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT + |O_TRUNC, S_IRUSR|S_IWUSR + |S_IRGRP|S_IWGRP|S_IROTH| + S_IWOTH)) < 0){ + perror("Can't open file for dvr test"); + return -1; + } + + pfd[0].fd = dvr; + pfd[0].events = POLLIN; + + /* poll for dvr data and write to file */ + while (length < MAX_LENGTH ) { + if (poll(pfd,1,1)){ + if (pfd[0].revents & POLLIN){ + len = read(dvr, buf, BUFFY); + if (len < 0){ + perror("recording"); + return -1; + } + if (len > 0){ + written = 0; + while (written < len) + written += + write (dvr_out, + buf, len); + length += len; + printf("written %2.0f MB\r", + length/1024./1024.); + } + } + } + } + return 0; +} + +\end{verbatim} +} +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% TeX-master: t +%%% End: diff --git a/dvb-spec/dvbapi/fig2pstex b/dvb-spec/dvbapi/fig2pstex new file mode 100755 index 000000000..bf62eb7ec --- /dev/null +++ b/dvb-spec/dvbapi/fig2pstex @@ -0,0 +1,6 @@ +#!/bin/sh +f=`basename $1 .fig` +fig2dev -L pstex $f.fig $f.ps +fig2dev -L pstex_t -p $f.ps $f.fig $f.pst2 +./getbb $f.pst2 $f.ps > $f.pst +rm $f.pst2 \ No newline at end of file diff --git a/dvb-spec/dvbapi/getbb b/dvb-spec/dvbapi/getbb new file mode 100755 index 000000000..004714d3a --- /dev/null +++ b/dvb-spec/dvbapi/getbb @@ -0,0 +1,12 @@ +#!/bin/sh +f=`grep BoundingBox $2 | cut -d' ' -f2,3,4,5` +g=`\ +echo $2" llx=";(echo $f|cut -d' ' -f1 );\ +echo " lly=";(echo $f|cut -d' ' -f2 );\ +echo " urx=";(echo $f|cut -d' ' -f3 );\ +echo " ury=";(echo $f|cut -d' ' -f4 );\ +echo " rwi=";(echo $f|cut -d' ' -f3 );\ +echo "0" +` +h=`echo $g| sed "s/= /=/g" | sed "s/ 0/0/g"` +cat $1 | sed "s/psfile=$2/psfile=$h/" diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex new file mode 100644 index 000000000..acb6b4b85 --- /dev/null +++ b/dvb-spec/dvbapi/intro.tex @@ -0,0 +1,192 @@ +\chapter{Introduction} +%\addcontentsline{toc}{part}{Introduction} +%\chaptermark{Introduction} +\section{What you need to know} +The reader of this document is required to have some knowledge in the +area of digital video broadcasting (DVB) and should be familiar with +part I of ISO/IEC 13818, i.e you should know what a +program/transport stream (PS/TS) is and what is meant by a packetized elementary +stream (PES) or an I-frame. + +It is also necessary to know how to access unix/linux devices and how +to use ioctl calls. This also includes the knowledge of C or C++. +\section{History} + +The first API for DVB cards we used at Convergence in late 1999 +was an extension of the Video4Linux API which was primarily +developed for frame grabber cards. +As such it was not really well suited to be used for DVB cards and +their new features like recording MPEG streams and filtering several +section and PES data streams at the same time. + +In early 2000, we were approached by Nokia with a proposal for a new +standard Linux DVB API. +As a commitment to the development of terminals based on open standards, +Nokia and Convergence made it available to all Linux developers and +published it on \texttt{http://www.linuxtv.org/} in September 2000. +Convergence is the maintainer of the Linux DVB API. +Together with the LinuxTV community (i.e. you, the reader of this document), +the Linux DVB API will be constantly reviewed and improved upon. +With the Linux driver for the Siemens/Hauppauge DVB PCI card Convergence +provides a first implementation of the Linux DVB API. + + +\section{Overview} + +\begin{figure}[htbp] + \begin{center} + \includegraphics{dvbstb.ps} + \caption{Components of a DVB card/STB} + \label{fig:dvbstb} + \end{center} +\end{figure} + + +A DVB PCI card or DVB set-top-box (STB) usually consists of the following +main hardware components: +\begin{itemize} +\item Frontend consisting of tuner and DVB demodulator + +Here the raw signal reaches the DVB hardware from a satellite dish or antenna +or directly from cable. The frontend down-converts and demodulates +this signal into an MPEG transport stream (TS). + +\item SEC for controlling external hardware like LNBs and antennas + +This part of the hardware can send signals back through the satellite +cable to control the polarization of the LNB, to switch between +different LNBs or even to control the movements of a dish rotor. + + +\item Conditional Access (CA) hardware like CI adapters and smartcard slots + +The complete TS is passed through the CA hardware. Programs to which +the user has access (controlled by the smart card) are decoded in real +time and re-inserted into the TS. + +\item Demultiplexer which filters the incoming DVB stream + +The demultiplexer splits the TS into its components like audio and video +streams. Besides usually several of such audio and video streams it also +contains data strams with information about the programs offered in this +or other streams of the same provider. + +\item MPEG2 audio and video decoder + +The main targets of the demultiplexer are the MPEG2 audio and video +decoders. After decoding the pass on the uncompressed audio +and video to the computer screen or (through a PAL/NTSC encoder) to +a TV set. +\end{itemize} +Figure \ref{fig:dvbstb} shows a crude schematic of the control and data flow +between those components. + +On a DVB PCI card not all of these have to be present since some +functionality can be provided by the main CPU of the PC (e.g. MPEG picture +and sound decoding) or is not needed (e.g. for data-only uses like +``internet over satellite''). +Also not every card or STB provides conditional access hardware. + +\section{Linux DVB Devices} + +The Linux DVB API lets you control these hardware components +through currently six Unix-style character devices for +video, audio, frontend, SEC, demux and CA. +The video and audio devices control the MPEG2 decoder hardware, +the frontend device the tuner and the DVB demodulator. +External hardware like DiSEqC switches and rotors can be controlled +through the SEC device. +The demux device gives you control over the PES and section filters +of the hardware. If the hardware does not support filtering these filters +can be implemented in software. +Finally, the CA device controls all the conditional access capabilities +of the hardware. It can depend on the individual security requirements +of the platform, if and how many of the CA functions are made available +to the application through this device. + +All devices can be found in the \texttt{/dev} tree under +\texttt{/dev/ost}, where OST stands for Open Standards Terminal. +The individual devices are called +\begin{itemize} +\item \texttt{/dev/ost/audio}, +\item \texttt{/dev/ost/video}, +\item \texttt{/dev/ost/qpskfe}, +\item \texttt{/dev/ost/qamfe}, +\item \texttt{/dev/ost/sec}, +\item \texttt{/dev/ost/demux}, +\item \texttt{/dev/ost/ca}, +\end{itemize} +but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of +these devices. + +%Thus, the \texttt{audio} and \texttt{video} devices directly control +%the MPEG2 decoder audio and video decoder, respectively. +%Depending on the kind of frontend present (satellite, cable or +%terrestrial), it will be controlled either through the +%\texttt{qpsk} or \texttt{qamfe} device. +%DiSEqC or other kinds of control signals can be sent to the +%antenna hardware through the \texttt{sec} device. + +If more than one card is present in the system the other cards +can be accessed through the corresponding devices with the +card's number appended. \texttt{/dev/ost/demux0} (which +is identical to \texttt{/dev/ost/demux}) would, e.g., control the +demultiplexer of the first card, while \texttt{/dev/ost/demux1} +would control the demultiplexer of the second card, and so on. + +More details about the data structures and function calls of +all the devices are described in the following chapters. + + +\section{DVB Devices with Devfs} + +Recent Linux kernel versions support a special file system called +\textsl{devfs} which is a replacement for the traditional +device directory. +With devfs a Linux DVB driver will only create those device file entries +which actually exist. +It also makes dealing with more complex DVB hardware much easier. +The device structure described above is not well suited to deal +with multiple DVB cards with more than one frontend or demultiplexer. +Consider, e.g., two DVB cards, one with two frontends and +one demultiplexer, the other with one frontend and two demultiplexers. +If we just assign them consecutive numbers, there would be a demultiplexer +and a frontend which do notbelong to the same card but have +the same number. + +With \textsl{devfs} we propose a different scheme for the device names. +The root directory for all DVB cards will be \texttt{/dev/dvb}. +Each card gets assigned a sub-directory with the name \texttt{/dev/card0}, +\texttt{/dev/card1}, etc. +The files created in these sub-directories will correspond directly to the +hardware actually present on the card. +Thus, if the first card has one QAM frontend, one demultiplexer +and otherwise no other hardware, +only \texttt{/dev/dvb/card0/qamfe0} and \texttt{/dev/dvb/card0/demux0} +will be created. +When a second DVB-S card with one frontend (including SEC) device, +two demultiplexers and an MPEG2 audio/video decoder is added, the +complete \texttt{/dev/dvb} tree will look like this: + +\begin{verbatim} +/dev/dvb/card0/qam0 + demux0 + +/dev/dvb/card1/video0 + audio0 + demux0 + demux1 + qpskfe0 + sec0 +\end{verbatim} + + +\section{Using the Devices} + +\dots + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex new file mode 100644 index 000000000..6cee25c85 --- /dev/null +++ b/dvb-spec/dvbapi/kdapi.tex @@ -0,0 +1,1007 @@ +\devsec{Kernel Demux API} + +The kernel demux API + +\devsubsec{Kernel Demux Data Types} + +\devsubsubsec{dmx\_success\_t} +\label{dmxsuccesst} + +\begin{verbatim} +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; +\end{verbatim} + + +\devsubsubsec{TS filter types} +\label{tsfiltertypes} + +\begin{verbatim} +/*--------------------------------------------------------------------------*/ +/* TS packet reception */ +/*--------------------------------------------------------------------------*/ + +/* TS filter type for set_type() */ + +#define TS_PACKET 1 /* send TS packets (188 bytes) to callback (default) */ +#define TS_PAYLOAD_ONLY 2 /* in case TS_PACKET is set, only send the TS + payload (<=184 bytes per packet) to callback */ +#define TS_DECODER 4 /* send stream to built-in decoder (if present) */ +\end{verbatim} + + +\devsubsubsec{dmx\_ts\_pes\_t} +\label{dmxtspest} + +The structure +/\begin{verbatim} +typedef enum +{ + DMX_TS_PES_AUDIO, /* also send packets to audio decoder (if it exists) */ + DMX_TS_PES_VIDEO, /* ... */ + DMX_TS_PES_TELETEXT, + DMX_TS_PES_SUBTITLE, + DMX_TS_PES_PCR, + DMX_TS_PES_OTHER, +} dmx_ts_pes_t; +\end{verbatim} +describes the PES type for filters which write to +a built-in decoder. +The correspond (and should be kept identical) to the types in +the demux device. + +\begin{verbatim} +struct dmx_ts_feed_s { + int is_filtering; /* Set to non-zero when filtering in progress */ + struct dmx_demux_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ + int (*set) (struct dmx_ts_feed_s* feed, + __u16 pid, + size_t callback_length, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (*start_filtering) (struct dmx_ts_feed_s* feed); + int (*stop_filtering) (struct dmx_ts_feed_s* feed); + int (*set_type) (struct dmx_ts_feed_s* feed, + int type, + dmx_ts_pes_t pes_type); +}; + +typedef struct dmx_ts_feed_s dmx_ts_feed_t; +\end{verbatim} + +\begin{verbatim} +/*--------------------------------------------------------------------------*/ +/* PES packet reception (not supported yet) */ +/*--------------------------------------------------------------------------*/ + +typedef struct dmx_pes_filter_s { + struct dmx_pes_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ +} dmx_pes_filter_t; +\end{verbatim} + +\begin{verbatim} +typedef struct dmx_pes_feed_s { + int is_filtering; /* Set to non-zero when filtering in progress */ + struct dmx_demux_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ + int (*set) (struct dmx_pes_feed_s* feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (*start_filtering) (struct dmx_pes_feed_s* feed); + int (*stop_filtering) (struct dmx_pes_feed_s* feed); + int (*allocate_filter) (struct dmx_pes_feed_s* feed, + dmx_pes_filter_t** filter); + int (*release_filter) (struct dmx_pes_feed_s* feed, + dmx_pes_filter_t* filter); +} dmx_pes_feed_t; +\end{verbatim} + + +\begin{verbatim} +\label{sectionfilter} +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; +\end{verbatim} + +\begin{verbatim} +struct dmx_section_feed_s { + int is_filtering; /* Set to non-zero when filtering in progress */ + struct dmx_demux_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ + int (*set) (struct dmx_section_feed_s* feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + int check_crc); + int (*allocate_filter) (struct dmx_section_feed_s* feed, + dmx_section_filter_t** filter); + int (*release_filter) (struct dmx_section_feed_s* feed, + dmx_section_filter_t* filter); + int (*start_filtering) (struct dmx_section_feed_s* feed); + int (*stop_filtering) (struct dmx_section_feed_s* feed); +}; +typedef struct dmx_section_feed_s dmx_section_feed_t; + +/*--------------------------------------------------------------------------*/ +/* Callback functions */ +/*--------------------------------------------------------------------------*/ + +typedef int (*dmx_ts_cb) ( __u8 * buffer1, + size_t buffer1_length, + __u8 * buffer2, + size_t buffer2_length, + dmx_ts_feed_t* source, + dmx_success_t success); + +typedef int (*dmx_section_cb) ( __u8 * buffer1, + size_t buffer1_len, + __u8 * buffer2, + size_t buffer2_len, + dmx_section_filter_t * source, + dmx_success_t success); + +typedef int (*dmx_pes_cb) ( __u8 * buffer1, + size_t buffer1_len, + __u8 * buffer2, + size_t buffer2_len, + dmx_pes_filter_t* source, + dmx_success_t success); + +/*--------------------------------------------------------------------------*/ +/* DVB Front-End */ +/*--------------------------------------------------------------------------*/ + +typedef enum { + DMX_OTHER_FE = 0, + DMX_SATELLITE_FE, + DMX_CABLE_FE, + DMX_TERRESTRIAL_FE, + DMX_LVDS_FE, + DMX_ASI_FE, /* DVB-ASI interface */ + DMX_MEMORY_FE +} dmx_frontend_source_t; + +typedef struct { + /* The following char* fields point to NULL terminated strings */ + char* id; /* Unique front-end identifier */ + char* vendor; /* Name of the front-end vendor */ + char* model; /* Name of the front-end model */ + struct list_head connectivity_list; /* List of front-ends that can + be connected to a particular + demux */ + void* priv; /* Pointer to private data of the API client */ + dmx_frontend_source_t source; +} dmx_frontend_t; + +/*--------------------------------------------------------------------------*/ +/* MPEG-2 TS Demux */ +/*--------------------------------------------------------------------------*/ + +/* + * Flags OR'ed in the capabilites field of struct dmx_demux_s. + */ + +#define DMX_TS_FILTERING 1 +#define DMX_PES_FILTERING 2 +#define DMX_SECTION_FILTERING 4 +#define DMX_MEMORY_BASED_FILTERING 8 /* write() available */ +#define DMX_CRC_CHECKING 16 +#define DMX_TS_DESCRAMBLING 32 +#define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 +#define DMX_MAC_ADDRESS_DESCRAMBLING 128 +\end{verbatim} + +\devsubsubsec{demux\_demux\_t} +\label{demuxdemuxt} + +\begin{verbatim} +/* + * DMX_FE_ENTRY(): Casts elements in the list of registered + * front-ends from the generic type struct list_head + * to the type * dmx_frontend_t + *. +*/ + +#define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) + +struct dmx_demux_s { + /* The following char* fields point to NULL terminated strings */ + char* id; /* Unique demux identifier */ + char* vendor; /* Name of the demux vendor */ + char* model; /* Name of the demux model */ + __u32 capabilities; /* Bitfield of capability flags */ + dmx_frontend_t* frontend; /* Front-end connected to the demux */ + struct list_head reg_list; /* List of registered demuxes */ + void* priv; /* Pointer to private data of the API client */ + int users; /* Number of users */ + int (*open) (struct dmx_demux_s* demux); + int (*close) (struct dmx_demux_s* demux); + int (*write) (struct dmx_demux_s* demux, const char* buf, size_t count); + int (*allocate_ts_feed) (struct dmx_demux_s* demux, + dmx_ts_feed_t** feed, + dmx_ts_cb callback); + int (*release_ts_feed) (struct dmx_demux_s* demux, + dmx_ts_feed_t* feed); + int (*allocate_pes_feed) (struct dmx_demux_s* demux, + dmx_pes_feed_t** feed, + dmx_pes_cb callback); + int (*release_pes_feed) (struct dmx_demux_s* demux, + dmx_pes_feed_t* feed); + int (*allocate_section_feed) (struct dmx_demux_s* demux, + dmx_section_feed_t** feed, + dmx_section_cb callback); + int (*release_section_feed) (struct dmx_demux_s* demux, + dmx_section_feed_t* feed); + int (*descramble_mac_address) (struct dmx_demux_s* demux, + __u8* buffer1, + size_t buffer1_length, + __u8* buffer2, + size_t buffer2_length, + __u16 pid); + int (*descramble_section_payload) (struct dmx_demux_s* demux, + __u8* buffer1, + size_t buffer1_length, + __u8* buffer2, size_t buffer2_length, + __u16 pid); + int (*add_frontend) (struct dmx_demux_s* demux, + dmx_frontend_t* frontend); + int (*remove_frontend) (struct dmx_demux_s* demux, + dmx_frontend_t* frontend); + struct list_head* (*get_frontends) (struct dmx_demux_s* demux); + int (*connect_frontend) (struct dmx_demux_s* demux, + dmx_frontend_t* frontend); + int (*disconnect_frontend) (struct dmx_demux_s* demux); + + + /* added because js cannot keep track of these himself */ + int (*get_pes_pids) (struct dmx_demux_s* demux, __u16 *pids); +}; +typedef struct dmx_demux_s dmx_demux_t; +\end{verbatim} + + +\devsubsubsec{Demux directory} +\label{demuxdir} + +\begin{verbatim} +/* + * 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); +\end{verbatim} + +\clearpage + +\devsubsec{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. + +\kifunction{dmx\_register\_demux()}{ + int dmx\_register\_demux ( dmx\_demux\_t *demux ) + }{ + 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(), + }{ + dmx\_demux\_t* demux & Pointer to the demux structure. + }{ + 0 & The function was completed without errors.\\ + -EEXIST & A demux with the same value of the id field + already stored in the directory.\\ + -ENOSPC & No space left in the directory. +} + +\kifunction{dmx\_unregister\_demux()}{ + int dmx\_unregister\_demux ( dmx\_demux\_t *demux ) + }{ + 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. + }{ + dmx\_demux\_t* demux & Pointer to the demux structure which is to be unregistered. + }{ + 0 & The function was completed without errors.\\ + ENODEV & The specified demux is not registered in the demux directory.\\ + EBUSY & The specified demux is currently in use. +} + +\kifunction{dmx\_get\_demuxes()}{ + struct list\_head *dmx\_get\_demuxes () + }{ + 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. + }{ + none + }{ + struct list\_head * & + A list of demux interfaces, or NULL in the case of an empty list. +} + +\clearpage + +\devsubsec{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 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 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. + +\kfunction{open()}{ + int open ( demux\_t* demux ); + }{ + 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. + }{ + demux\_t* demux & Pointer to the demux API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EUSERS & Maximum usage count reached.\\ + -EINVAL & Bad parameter. +} + +\kfunction{close()}{ + int close(demux\_t* demux); + }{ + 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. + }{ + demux\_t* demux & Pointer to the demux API and instance data. + }{ + 0 & The function was completed without errors.\\ + -ENODEV & The demux was not in use.\\ + -EINVAL & Bad parameter. +} + +\kfunction{write()}{ + int write(demux\_t* demux, const char* buf, size\_t count); + }{ + This function provides the demux driver with a memory buffer containing TS + packets. Instead of receiving TS packets from the DVB front-end, the demux + driver software will read packets from memory. Any clients of this demux + with active TS, PES or Section filters will receive filtered data via the Demux + callback API (see 0). The function returns when all the data in the buffer has + been consumed by the demux. + Demux hardware typically cannot read TS from memory. If this is the case, + memory-based filtering has to be implemented entirely in software. + }{ + demux\_t* demux & Pointer to the demux API and instance data.\\ + const char* buf & Pointer to the TS data in kernel-space memory.\\ + size\_t length & Length of the TS data. + }{ + 0 & The function was completed without errors.\\ + -ENOSYS & The command is not implemented.\\ + -EINVAL & Bad parameter. +} + +\kifunction{allocate\_ts\_feed()}{ + int allocate\_ts\_feed(dmx\_demux\_t* demux, + dmx\_ts\_feed\_t** feed, dmx\_ts\_cb callback); + }{ + 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. + }{ + demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_ts\_feed\_t** feed & Pointer to the TS feed API and instance data.\\ + dmx\_ts\_cb callback & Pointer to the callback function for + passing received TS packet + }{ + 0 & The function was completed without errors.\\ + -EBUSY & No more TS feeds available.\\ + -ENOSYS & The command is not implemented.\\ + -EINVAL & Bad parameter. +} + +\kifunction{release\_ts\_feed()}{ + int release\_ts\_feed(dmx\_demux\_t* demux, dmx\_ts\_feed\_t* feed); + }{ + Releases the resources allocated with allocate\_ts\_feed(). Any filtering in progress + on the TS feed should be stopped before calling this function. + }{ + demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{allocate\_section\_feed()}{ + int allocate\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t **feed, + dmx\_section\_cb callback); + }{ + 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. + }{ + demux\_t *demux & Pointer to the demux API and instance data.\\ + dmx\_section\_feed\_t **feed & Pointer to the section feed API and instance data.\\ + dmx\_section\_cb callback & Pointer to the callback function for + passing received sections. + }{ + 0 & The function was completed without errors.\\ + -EBUSY & No more section feeds available.\\ + -ENOSYS & The command is not implemented.\\ + -EINVAL & Bad parameter. +} + + +\kifunction{release\_section\_feed()}{ + int release\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t *feed); + }{ + 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. + }{ + demux\_t *demux & Pointer to the demux API and instance data.\\ + dmx\_section\_feed\_t *feed & Pointer to the section feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{descramble\_mac\_address()}{ + int descramble\_mac\_address(dmx\_demux\_t* demux, + \_\_u8 *buffer1, size\_t buffer1\_length, + \_\_u8 *buffer2, size\_t buffer2\_length, \_\_u16 pid); + }{ + This function runs a descrambling algorithm on the destination MAC address field of a + DVB Datagram Section, replacing the original address with its un-encrypted version. + Otherwise, the description on the function descramble\_section\_payload() applies + also to this function. + }{ + dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ + \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ + size\_t buffer1\_length & Length of the section data, including headers and CRC, + in buffer1.\\ + \_\_u8* buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a + non-NULL value if the section wraps + past the end of a circular buffer.\\ + size\_t buffer2\_length & Length of the section data, + including headers and CRC, in buffer2.\\ + \_\_u16 pid & The PID on which the section was received. Useful for obtaining the + descrambling key, e.g. from a DVB Common Access facility. + }{ + 0 & The function was completed without errors.\\ + -ENOSYS & No descrambling facility available.\\ + -EINVAL & Bad parameter. +} + +\kifunction{descramble\_section\_payload()}{ + int descramble\_section\_payload(dmx\_demux\_t* demux, + \_\_u8 *buffer1, size\_t buffer1\_length, \_\_u8 *buffer2, size\_t + buffer2\_length, \_\_u16 pid); + }{ + This function runs a descrambling algorithm on the payload of a DVB Datagram + Section, replacing the original payload with its un-encrypted version. + The function will + be called from the demux API implementation; the API client need + not call this function directly. + Section-level scrambling algorithms are currently standardized only for DVB-RCC + (return channel over 2-directional cable TV network) systems. For all other DVB + networks, encryption schemes are likely to be proprietary to each data broadcaster. + Thus, it is expected that this function pointer will have the value of NULL + (i.e., function not available) in most demux API implementations. + Nevertheless, it should be possible + to use the function pointer as a hook for dynamically adding a ``plug-in'' + descrambling facility to a demux driver.\\ + 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. + }{ + dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ + \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ + size\_t buffer1\_length & Length of the section data, including headers and CRC, in + buffer1.\\ + \_\_u8 *buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a + non-NULL value if the section wraps + past the end of a circular buffer.\\ + size\_t buffer2\_length & Length of the section data, including headers and CRC, in + buffer2.\\ + \_\_u16 pid & The PID on which the section was received. Useful for obtaining the + descrambling key, e.g. from a DVB Common Access facility. + }{ + 0 & The function was completed without errors.\\ + -ENOSYS & No descrambling facility available.\\ + -EINVAL & Bad parameter. +} + +\kifunction{add\_frontend()}{ + int add\_frontend(dmx\_demux\_t *demux, dmx\_frontend\_t *frontend); + }{ + 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(). + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_frontend\_t* frontend & Pointer to the front-end instance data. + }{ + 0 & The function was completed without errors.\\ + -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 parameter. +} + +\kifunction{remove\_frontend()}{ + int remove\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); + }{ + Indicates that the given front-end, registered by a call to add\_frontend(), can no + longer be connected as a TS source by this demux. The function should be called + when a front-end driver or a demux driver is removed from the system. If the front-end + is in use, the function fails with the return value of -EBUSY. + After successfully calling this function, the caller can free the memory of + the frontend struct if it was dynamically allocated before the add\_frontend() + operation. + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_frontend\_t* frontend & Pointer to the front-end instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter.\\ + -EBUSY & The front-end is in use, i.e. a call to + connect\_frontend() has not been followed by + a call to disconnect\_frontend(). +} + +\kifunction{get\_frontends()}{ + struct list\_head* get\_frontends(dmx\_demux\_t* demux); + }{ + 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. + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data. + }{ + dmx\_demux\_t* & A list of front-end interfaces, or NULL in the case of an empty list. +} + + +\kifunction{connect\_frontend()}{ + int connect\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); + }{ + 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(). + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_frontend\_t* frontend & Pointer to the front-end instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter.\\ + -EBUSY & The front-end is in use. +} + +\kifunction{disconnect\_frontend()}{ + int disconnect\_frontend(dmx\_demux\_t* demux); + }{ + Disconnects the demux and a front-end previously connected by a + connect\_frontend() call. + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\clearpage + +\devsubsec{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. + +\kifunction{dmx\_ts\_cb()}{ + 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); + }{ + 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. \\ + Any TS packets that match the filter settings are copied to a circular buffer. + The filtered TS packets are delivered to the client using this callback + function. The size of the circular buffer is controlled by the + circular\_buffer\_size parameter of the set() function in the TS Feed API. It is + expected that the buffer1 and buffer2 callback parameters point to addresses + within the circular buffer, but other implementations are also + possible. Note that the called party should not try to free the memory the + buffer1 and buffer2 parameters point to.\\ + When this function is called, the buffer1 parameter typically points to the + start of the first undelivered TS packet within a circular buffer. The buffer2 + buffer parameter is normally NULL, except when the received TS packets have + crossed the last address of the circular buffer and "wrapped" to the beginning + of the buffer. In the latter case the buffer1 parameter would contain an + address within the circular buffer, while the buffer2 parameter would contain + the first address of the circular buffer.\\ + The number of bytes delivered with this function (i.e. buffer1\_length + + buffer2\_length) is usually equal to the value of callback\_length parameter given + in the set() function, with one exception: if a timeout occurs before receiving + callback\_length bytes of TS data, any undelivered packets are immediately + delivered to the client by calling this function. The timeout duration is + controlled by the set() function in the TS Feed API.\\ + If a TS packet is received with errors that could not be fixed by the TS-level + forward error correction (FEC), the Transport\_error\_indicator flag of the TS + packet header should be set. The TS packet should not be discarded, as the + error can possibly be corrected by a higher layer protocol. + If the called party is slow in processing the callback, it is possible that + the circular buffer eventually fills up. If this happens, the demux driver + should discard any TS packets received while the buffer is full. The error + should be indicated to the client on the next callback by setting the success + parameter to the value of DMX\_OVERRUN\_ERROR.\\ + The type of data returned to the callback can be selected by the + new function int (*set\_type) (struct dmx\_ts\_feed\_s* feed, int type, + dmx\_ts\_pes\_t pes\_type) which is part of the dmx\_ts\_feed\_s struct + (also cf. to the include file ost/demux.h) + The type parameter decides if the raw TS packet (TS\_PACKET) or just the + payload (TS\_PACKET|TS\_PAYLOAD\_ONLY) should be returned. + If additionally the TS\_DECODER bit is set the stream will also be sent + to the hardware MPEG decoder. In this case, the second flag decides + as what kind of data the stream should be interpreted. + The possible choices are one of DMX\_TS\_PES\_AUDIO, DMX\_TS\_PES\_VIDEO, + DMX\_TS\_PES\_TELETEXT, DMX\_TS\_PES\_SUBTITLE, DMX\_TS\_PES\_PCR, or + DMX\_TS\_PES\_OTHER. + }{ + \_\_u8* buffer1 & Pointer to the start of the filtered TS packets.\\ + size\_t buffer1\_length & Length of the TS data in buffer1.\\ + \_\_u8* buffer2 & Pointer to the tail of the filtered TS packets, or NULL.\\ + size\_t buffer2\_length & Length of the TS data in buffer2.\\ + dmx\_ts\_feed\_t* source & Indicates which TS feed is the source of the callback.\\ + dmx\_success\_t success & Indicates if there was an error in TS reception. + }{ + 0 & Continue filtering.\\ + -1& Stop filtering - has the same effect as a call + to stop\_filtering() on the TS Feed API. +} + +\kifunction{dmx\_section\_cb()}{ + 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); + }{ + This function, provided by the client of the demux API, is called from the demux code. + The function is only called when filtering of sections has been enabled using the + function start\_filtering() of the section feed API. + When the demux driver has received a complete section that matches at least one + section filter, the client is notified via this callback function. Normally this function is + called for each received section; however, it is also possible to deliver multiple sections + with one callback, for example when the system load is high. + If an error occurs while receiving a section, this function should be called with the + corresponding error type set in the success field, whether or not there is data to + deliver. + The Section Feed implementation should maintain a circular buffer for received sections. + However, this is not necessary if the Section Feed API is implemented as a client of + the TS Feed API, because the TS Feed implementation then buffers the + received data. + The size of the circular buffer can be configured using the set() function in the + Section Feed API. If there is no room in the circular buffer when a new section is + received, the section must be discarded. If this happens, the value of the success + parameter should be DMX\_OVERRUN\_ERROR on the next callback. + }{ + \_\_u8* buffer1 & Pointer to the start of the filtered section, e.g. + within the circular buffer of the demux driver.\\ + size\_t buffer1\_length & 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 circular + buffer.\\ + size\_t buffer2\_length & Length of the filtered section data in buffer2, + including headers and CRC.\\ + dmx\_section\_filter\_t* filter & Indicates the filter that triggered the callback.\\ + dmx\_success\_t success & Indicates if there was an error in section reception. + }{ + 0 & Continue filtering.\\ + -1& Stop filtering - has the same effect as a call + to stop\_filtering() on the Section Feed API. +} + +\clearpage + +\devsubsec{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. + +\kifunction{set()}{ + int set ( dmx\_ts\_feed\_t* feed, \_\_u16 pid, size\_t callback\_length, + size\_t circular\_buffer\_size, int descramble, struct timespec timeout); + }{ + This function sets the parameters of a TS feed. + Any filtering in progress on the TS feed + must be stopped before calling this function. + }{ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data.\\ + \_\_u16 pid & PID value to filter. Only the TS packets carrying the specified PID will + be passed to the API client.\\ + size\_t callback\_length & 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 circular\_buffer\_size & Size of the circular buffer for the filtered TS packets.\\ + int descramble & If non-zero, descramble the filtered TS packets.\\ + struct timespec timeout & Maximum time to wait before + delivering received TS packets to the client. + }{ + 0 & The function was completed without errors.\\ + -ENOMEM & Not enough memory for the requested buffer size.\\ + -ENOSYS & No descrambling facility available for TS.\\ + -EINVAL & Bad parameter. +} + + +\kifunction{start\_filtering()}{ + int start\_filtering(dmx\_ts\_feed\_t* feed); + }{ + 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(). + }{ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{stop\_filtering()}{ + int stop\_filtering(dmx\_ts\_feed\_t* feed); + }{ + Stops filtering TS packets on this TS feed. + }{ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\clearpage + +\devsubsec{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. + + +\kifunction{set()}{ + int set(dmx\_section\_feed\_t* feed, \_\_u16 pid, size\_t circular\_buffer\_size, + int descramble, int check\_crc); + }{ + This function sets the parameters of a section feed. Any filtering in progress on the + section feed must be stopped before calling this function. + If descrambling is enabled, the payload\_scrambling\_control and + address\_scrambling\_control fields of received DVB datagram sections should be + observed. If either one is non-zero, the section should be descrambled either in + hardware or using the functions descramble\_mac\_address() and + descramble\_section\_payload() of the demux API. Note that according to the + MPEG-2 Systems specification, only the payloads of private sections can be + scrambled while the rest of the section data must be sent in the clear. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + \_\_u16 pid & PID value to filter; only the TS packets + carrying the specified PID will be accepted.\\ + size\_t circular\_buffer\_size & Size of the circular buffer for filtered sections.\\ + int descramble & If non-zero, descramble any sections that are scrambled.\\ + int check\_crc & If non-zero, check the CRC values of filtered sections. + }{ + 0 & The function was completed without errors.\\ + -ENOMEM & Not enough memory for the requested buffer size.\\ + -ENOSYS & No descrambling facility available for sections.\\ + -EINVAL & Bad parameters. +} + +\kifunction{allocate\_filter()}{ + int allocate\_filter(dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t** filter); + }{ + This function is used to allocate a section filter on the demux. + It should only be called when no filtering is in progress on this section feed. + If a filter cannot be allocated, the function fails with -ENOSPC. + See in section \ref{sectionfilter} for the format of the section filter. \\ + 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. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + dmx\_section\_filter\_t** filter & Pointer to the allocated filter. + }{ + 0 & The function was completed without errors.\\ + -ENOSPC & No filters of given type and length available.\\ + -EINVAL & Bad parameters. +} + +\kifunction{release\_filter()}{ + int release\_filter ( dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t* filter); + }{ + 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. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + dmx\_section\_filter\_t* filter & I/O Pointer to the instance data of a section filter. + }{ + 0 & The function was completed without errors.\\ + -ENODEV & No such filter allocated.\\ + -EINVAL & Bad parameter. +} + +\kifunction{start\_filtering()}{ + int start\_filtering ( dmx\_section\_feed\_t* feed ); + }{ + 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(). + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{stop\_filtering()}{ + int stop\_filtering ( dmx\_section\_feed\_t* feed ); + }{ + 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. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex new file mode 100644 index 000000000..6ccd89481 --- /dev/null +++ b/dvb-spec/dvbapi/sec.tex @@ -0,0 +1,282 @@ +\devsec{DVB SEC API} + +The DVB SEC device controls the Satellite Equipment Control of +the DVB hardware, i.e. DiSEqC and V-SEC. +It is accessed through \texttt{/dev/ost/sec}. + +\devsubsec{SEC Data Types} + +\devsubsubsec{secDiseqcCmd} +\label{secdiseqccmd} + +\begin{verbatim} +struct secDiseqcCmd { + uint8_t addr; + uint8_t cmd; + uint8_t numParams; + uint8_t params[SEC_MAX_DISEQC_PARAMS]; +}; +\end{verbatim} + + +\devsubsubsec{secVoltage} +\label{secvoltage} + +\begin{verbatim} +typedef uint32_t secVoltage; +\end{verbatim} +\begin{verbatim} +enum { + SEC_VOLTAGE_OFF, + SEC_VOLTAGE_LT, + SEC_VOLTAGE_13, + SEC_VOLTAGE_13_5, + SEC_VOLTAGE_18, + SEC_VOLTAGE_18_5 +}; +\end{verbatim} + + +\devsubsubsec{secToneMode} +\label{sectonemode} + +\begin{verbatim} +typedef uint32_t secToneMode; +\end{verbatim} +\begin{verbatim} +typedef enum { + SEC_TONE_ON, + SEC_TONE_OFF +} secToneMode_t; +\end{verbatim} + + +\devsubsubsec{secMiniCmd} +\label{secminicmd} + +\begin{verbatim} +typedef uint32_t secMiniCmd; +\end{verbatim} +\begin{verbatim} +typedef enum { + SEC_MINI_NONE, + SEC_MINI_A, + SEC_MINI_B +} secMiniCmd_t; +\end{verbatim} +\begin{verbatim} +struct secStatus { + int32_t busMode; + secVoltage selVolt; + secToneMode contTone; +}; +\end{verbatim} + +\begin{verbatim} +enum { + SEC_BUS_IDLE, + SEC_BUS_BUSY, + SEC_BUS_OFF, + SEC_BUS_OVERLOAD +}; +\end{verbatim} + + +\devsubsubsec{secCommand} +\label{seccommand} + +\begin{verbatim} +struct secCommand { + int32_t type; + union { + struct secDiseqcCmd diseqc; + uint8_t vsec; + uint32_t pause; + } u; +}; +\end{verbatim} + + +\devsubsubsec{secCmdSequence} +\label{seccmdsequence} + +\begin{verbatim} +struct secCmdSequence { + secVoltage voltage; + secMiniCmd miniCommand; + secToneMode continuousTone; + + uint32_t numCommands; + struct secCommand* commands; +}; +\end{verbatim} + +\begin{verbatim} +enum { + SEC_CMDTYPE_DISEQC, + SEC_CMDTYPE_VSEC, + SEC_CMDTYPE_PAUSE +}; +\end{verbatim} + +\begin{verbatim} +typedef enum { + SEC_DISEQC_SENT, + SEC_VSEC_SENT, + SEC_PAUSE_COMPLETE, + SEC_CALLBACK_ERROR +} secCallback_t; +\end{verbatim} + +\clearpage + +\devsubsec{SEC Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named SEC device for subsequent use. + If the device is opened in read-only mode, only status and statistics + monitoring is allowed. If the device is opened in read/write mode, all + types of operations can be performed. + Any number of applications can have simultaneous access to the device. + }{ + const char *deviceName & Name of specific SEC device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & The optional flag O\_NONBLOCK is not supported. If O\_NONBLOCK is set, + open() and most other subsequent calls to the device will return -1 and + set errno to EWOULDBLOCK. + The communication with the peripheral devices is sequential by nature, + so it is probably preferable to use the device in synchronous mode. + This is the motivation for not going through the extra effort of + implementing asynchronous operation of the device. + }{ + ENODEV & Device driver not loaded/available.\\ + EFAULT & deviceName does not refer to a valid memory area.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened SEC device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\ifunction{SEC\_GET\_STATUS}{ + int ioctl(int fd, int request = SEC\_GET\_STATUS, struct secStatus* status);}{ + This call gets the status of the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_GET\_STATUS for this command.\\ + struct secStatus* status & The status of the device.\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EFAULT & status is an invalid pointer.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ + EPERM & File not opened with read permissions.\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{SEC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = SEC\_RESET\_OVERLOAD);}{ + If the bus has been automatically powered off due to power overload, this + ioctl call restores the power to the bus. The call requires read/write + access to the device. + This call has no effect if the device is manually powered off. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_RESET\_OVERLOAD for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{SEC\_RESET\_OVERLOAD}{ +int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); +}{ +This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC +commands. The first version of the SEC device does not support V-SEC +signaling and it aborts the operation with an error code if a V-SEC +command is detected in the input data.\\ +\begin{itemize} +\item[$\bullet$] The call will fail with errno set to EBUSOVERLOAD if the bus is +overloaded. If the bus is overloaded, SEC\_RESET\_OVERLOAD can be +called and the operation can be retried. +\item[$\bullet$] If seq.numCommands equals 0 and seq.miniCommand equals SEC\_MINI\_NONE, +the bus voltage will be switched and the continuous 22kHz tone +generation enabled/disabled immediately. +\end{itemize}\\ +This operation is atomic. If several processes calls this ioctl +simultaneously, the operations will be serialized so a complete sequence +is sent at a time. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_SEND\_SEQUENCE for this command.\\ + struct secCmdSequence *seq & Pointer to the command sequence to be transmitted.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & Seq points to an invalid address.\\ + EINVAL & The data structure referred to by seq is invalid in some way.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ + EBUSMODE & The device is not prepared for transmission + (e.g. it might be manually powered off).\\ + EBUSOVERLOAD & Bus overload has occurred.\\ +} + + +\ifunction{SEC\_SET\_TONE}{ +int ioctl(int fd, int request = SEC\_SET\_TONE, secToneMode tone); +}{ +This call is used to set the generation of the continuous 22kHz tone. +The possibility to just change the tone mode is already provided by +ioctl SEC\_SEND\_SEQUENCE, but SEC\_SET\_TONE is an easier to use interface. +To keep the transmission of a command sequence as +an atomic operation, SEC\_SET\_TONE will block if a transmission is in +progress. This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals SEC\_SET\_TONE for this command.\\ +secToneMode tone & The requested tone generation mode (on/off).\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{SEC\_SET\_VOLTAGE}{ +int ioctl(int fd, int request = SEC\_SET\_VOLTAGE, secVoltage voltage); +}{ +This call is used to set the bus voltage. The possibility to just change +the bus voltage is already provided by ioctl SEC\_SEND\_SEQUENCE, but +SEC\_SET\_VOLTAGE is an easier to use interface. +To keep the transmission of a command sequence as +an atomic operation, SEC\_SET\_VOLTAGE will block if a transmission is in +progress. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals SEC\_SET\_VOLTAGE for this command.\\ +secVoltage voltage & The requested bus voltage.\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex new file mode 100644 index 000000000..ce8b584c1 --- /dev/null +++ b/dvb-spec/dvbapi/title.tex @@ -0,0 +1,24 @@ +\pagenumbering{arabic} +\pagestyle{empty} +\title{\huge\textbf{LINUX DVB API}} + +\author{ +\includegraphics{cimlogo.psi}\\ + Convergence integrated media GmbH\\\\ + Dr. Ralph J.K. Metzler\\ + \texttt{}\\\\ + Dr. Marcus O.C. Metzler\\ + \texttt{} +% Rosenthalerstr. 51\\ +% 10178 Berlin\\Germany +} +\date{09/15/2001\\V 0.9.4} +\maketitle + +\newpage + +%\end{titlepage} +% Local Variables: +% mode: latex +% TeX-master: "dvbapi" +% End: \ No newline at end of file diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex new file mode 100644 index 000000000..67abb9586 --- /dev/null +++ b/dvb-spec/dvbapi/video.tex @@ -0,0 +1,684 @@ +\devsec{DVB Video Device} + +The DVB video device controls the MPEG2 video decoder of the DVB hardware. +It can be accessed through \texttt{/dev/ost/video}. +The include file \texttt{ost/video.h} defines the data types and lists all I/O calls. + + +\devsubsec{Video Data Types} + +\devsubsubsec{videoFormat\_t} +\label{videoformat} + +The \texttt{videoFormat\_t} data type defined by +\begin{verbatim} +typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9 +} videoFormat_t; +\end{verbatim} +is used in the VIDEO\_SET\_FORMAT function (\ref{videosetformat}) to +tell the driver which aspect ratio the output hardware (e.g. TV) has. +It is also used in the data structures videoStatus (\ref{videostatus}) +returned by VIDEO\_GET\_STATUS (\ref{videogetstatus}) and +videoEvent (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) +which report about the display format of the current video stream. + +\devsubsubsec{videoDisplayFormat\_t} +\label{videodispformat} + +In case the display format of the video stream and of the +display hardware differ the application has to specify how to handle +the cropping of the picture. +This can be done using the VIDEO\_SET\_DISPLAY\_FORMAT call +(\ref{videosetdisplayformat}) which accepts +\begin{verbatim} +typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT +} videoDisplayFormat_t; +\end{verbatim} +as argument. + + +\devsubsubsec{video stream source} +\label{videostreamsource} +The video stream source is set through the VIDEO\_SELECT\_SOURCE +call and can take the following values, depending on whether we are +replaying from an internal (demuxer) or external (user write) source. +\begin{verbatim} +typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY +} videoStreamSource_t; +\end{verbatim} +VIDEO\_SOURCE\_DEMUX selects the demultiplexer (fed +either by the frontend or the DVR device) as the source of +the video stream. +If VIDEO\_SOURCE\_MEMORY is selected the stream +comes from the application through the \texttt{write()} +system call. + +\devsubsubsec{video play state} +\label{videoplaystate} +The following values can be returned by the VIDEO\_GET\_STATUS call +representing the state of video playback. +\begin{verbatim} +typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED +} videoPlayState_t; +\end{verbatim} + + +\devsubsubsec{video event} +\label{videoevent} +The following is the structure of a video event as it is returned by +the VIDEO\_GET\_EVENT call. +\begin{verbatim} +struct videoEvent { + int32_t type; + time_t timestamp; + union { + videoFormat_t videoFormat; + } u; +}; +\end{verbatim} + +\devsubsubsec{video status} +\label{videostatus} +The VIDEO\_GET\_STATUS call returns the following structure informing +about various states of the playback operation. +\begin{verbatim} +struct videoStatus { + boolean videoBlank; + videoPlayState_t playState; + videoStreamSource_t streamSource; + videoFormat_t videoFormat; + videoDisplayFormat_t displayFormat; +}; +\end{verbatim} +If videoBlank is set video will be blanked out if the channel is changed or +if playback is stopped. Otherwise, the last picture will be displayed. +playState indicates if the video is currently frozen, stopped, or +being played back. The streamSource corresponds to the seleted source +for the video stream. It can come either from the demultiplexer or from memory. +The videoFormat indicates the aspect ratio (one of 4:3 or 16:9) +of the currently played video stream. +Finally, displayFormat corresponds to the selected cropping mode in case the +source video format is not the same as the format of the output device. + + +\devsubsubsec{video display still picture} +\label{videostill} +An I-frame displayed via the VIDEO\_STILLPICTURE call is passed on +within the following structure. +\begin{verbatim} +/* pointer to and size of a single iframe in memory */ +struct videoDisplayStillPicture { + char *iFrame; + int32_t size; +}; +\end{verbatim} + +\devsubsubsec{video capabilities} +\label{videocaps} +A call to VIDEO\_GET\_CAPABILITIES returns an unsigned integer with +the following bits set according to the hardwares capabilities. +\begin{verbatim} +/* bit definitions for capabilities: */ +/* can the hardware decode MPEG1 and/or MPEG2? */ +#define VIDEO_CAP_MPEG1 1 +#define VIDEO_CAP_MPEG2 2 +/* can you send a system and/or program stream to video device? + (you still have to open the video and the audio device but only + send the stream to the video device) */ +#define VIDEO_CAP_SYS 4 +#define VIDEO_CAP_PROG 8 +/* can the driver also handle SPU, NAVI and CSS encoded data? + (CSS API is not present yet) */ +#define VIDEO_CAP_SPU 16 +#define VIDEO_CAP_NAVI 32 +#define VIDEO_CAP_CSS 64 +\end{verbatim} + + +\devsubsubsec{video system} +\label{videosys} +A call to VIDEO\_SET\_SYSTEM sets the desired video system for TV +output. The following system types can be set: + +\begin{verbatim} +typedef enum { + VIDEO_SYSTEM_PAL, + VIDEO_SYSTEM_NTSC, + VIDEO_SYSTEM_PALN, + VIDEO_SYSTEM_PALNc, + VIDEO_SYSTEM_PALM, + VIDEO_SYSTEM_NTSC60, + VIDEO_SYSTEM_PAL60, + VIDEO_SYSTEM_PALM60 +} videoSystem_t; +\end{verbatim} + + + +\devsubsubsec{video highlights} +\label{vhilite} +Calling the ioctl VIDEO\_SET\_HIGHLIGHTS posts the SPU highlight +information. The call expects the following format for that information: + +\begin{verbatim} +typedef +struct videoHighlight { + boolean active; /* 1=show highlight, 0=hide highlight */ + uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ + /* 3- 0 Background pixel contrast */ + uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */ + /* 3- 0 Emphasis pixel-1 contrast */ + uint8_t color1; /* 7- 4 Pattern pixel color */ + /* 3- 0 Background pixel color */ + uint8_t color2; /* 7- 4 Emphasis pixel-2 color */ + /* 3- 0 Emphasis pixel-1 color */ + uint32_t ypos; /* 23-22 auto action mode */ + /* 21-12 start y */ + /* 9- 0 end y */ + uint32_t xpos; /* 23-22 button color number */ + /* 21-12 start x */ + /* 9- 0 end x */ +} videoHighlight_t; +\end{verbatim} + + +\devsubsubsec{video SPU} +\label{videospu} +Calling VIDEO\_SET\_SPU deactivates or activates SPU decoding, +according to the following format: +\begin{verbatim} +typedef +struct videoSPU { + boolean active; + int streamID; +} videoSPU_t; +\end{verbatim} + + +\devsubsubsec{video SPU palette} +\label{vspupal} +The following structure is used to set the SPU palette by calling VIDEO\_SPU\_PALETTE: +\begin{verbatim} +typedef +struct videoSPUPalette{ /* SPU Palette information */ + int length; + uint8_t *palette; +} videoSPUPalette_t; +\end{verbatim} + +\devsubsubsec{video NAVI pack} +\label{videonavi} +In order to get the navigational data the following structure has to +be passed to the ioctl VIDEO\_GET\_NAVI: +\begin{verbatim} +typedef +struct videoNaviPack{ + int length; /* 0 ... 1024 */ + uint8_t data[1024]; +} videoNaviPack_t; +\end{verbatim} + + +\devsubsubsec{video attributes} +\label{vattrib} +The following attributes can be set by a call to VIDEO\_SET\_ATTRIBUTES: +\begin{verbatim} +typedef uint16_t videoAttributes_t; +/* bits: descr. */ +/* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ +/* 13-12 TV system (0=525/60, 1=625/50) */ +/* 11-10 Aspect ratio (0=4:3, 3=16:9) */ +/* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */ +/* 7 line 21-1 data present in GOP (1=yes, 0=no) */ +/* 6 line 21-2 data present in GOP (1=yes, 0=no) */ +/* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */ +/* 2 source letterboxed (1=yes, 0=no) */ +/* 0 film/camera mode (0=camera, 1=film (625/50 only)) */ +\end{verbatim} + + +\clearpage + +\devsubsec{Video Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + 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 attempts to + open the device in this mode will fail, and an error-code will be returned. + If the Video Device is opened in O\_RDONLY mode, the only ioctl call that can + be used is VIDEO\_GET\_STATUS. All other call will return an error code. + }{ + const char *deviceName & Name of specific video device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened video device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\function{write()}{ + size\_t write(int fd, const void *buf, size\_t count);}{ + This system call can only be used if VIDEO\_SOURCE\_MEMORY is selected in the + ioctl call VIDEO\_SELECT\_SOURCE. The data provided shall be in PES + format, unless the capability allows other formats. + If O\_NONBLOCK is not specified the function will block until buffer space is + available. The amount of data to be transferred is implied by count. + }{ + 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.\\ + }{ + 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.\\ +} + + +\ifunction{VIDEO\_STOP}{ + int ioctl(fd, int request = VIDEO\_STOP, boolean mode);}{ + 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. +}{ +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.\\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ +} + +\ifunction{VIDEO\_PLAY}{ + int ioctl(fd, int request = VIDEO\_PLAY);}{ + This ioctl call asks the Video Device to start playing a video stream + from the selected source. +}{ +int fd & File descriptor returned by a previous call to open(). \\ +int request & Equals VIDEO\_PLAY for this command. \\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ +} + + +\ifunction{VIDEO\_FREEZE}{ + int ioctl(fd, int request = VIDEO\_FREEZE);}{ + This ioctl call suspends the live video stream being played. + Decoding and playing are frozen. It is then possible to restart + the decoding and playing process of the video stream using the + VIDEO\_CONTINUE command. If VIDEO\_SOURCE\_MEMORY is selected in the + ioctl call VIDEO\_SELECT\_SOURCE, the DVB subsystem will not decode + any more data until the ioctl call VIDEO\_CONTINUE or VIDEO\_PLAY is + performed. +}{ +int fd & File descriptor returned by a previous call to open(). \\ +int request & Equals VIDEO\_FREEZE for this command. \\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ +} + +\ifunction{VIDEO\_CONTINUE}{ + int ioctl(fd, int request = VIDEO\_CONTINUE);}{ + This ioctl call restarts decoding and playing processes of the video + stream which was played before a call to VIDEO\_FREEZE was made. + }{ + int fd & File descriptor returned by a previous call to open(). \\ + int request & Equals VIDEO\_CONTINUE for this command. \\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ + } + + +\ifunction{VIDEO\_SELECT\_SOURCE}{ + int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, videoStreamSource\_t source);}{ + This ioctl call informs the video device which source shall be used + for the input data. The possible sources are demux or memory. If + memory is selected, the data is fed to the video device through + the write command. + }{ + 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.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ +} + +\ifunction{VIDEO\_SET\_BLANK}{ + int ioctl(fd, int request = VIDEO\_SET\_BLANK, boolean mode);}{ + This ioctl call asks the Video Device to blank out the picture. +}{ +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.\\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ +EINVAL & Illegal input parameter\\ +} + +\ifunction{VIDEO\_GET\_STATUS}{ +\label{videogetstatus} + int ioctl(fd, int request = VIDEO\_GET\_STATUS, struct videoStatus *status);}{ + This ioctl call asks the Video Device to return the current status of the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals VIDEO\_GET\_STATUS for this command.\\ + struct videoStatus *status & Returns the current status of the Video Device.\\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ +EFAULT & status points to invalid address\\ +} + +\ifunction{VIDEO\_GET\_EVENT}{ +\label{videogetevent} + int ioctl(fd, int request = VIDEO\_GET\_EVENT, struct videoEvent *ev);}{ + 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. + }{ + 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.\\ +}{ +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.\\ +} + +\ifunction{VIDEO\_SET\_DISPLAY\_FORMAT}{ +\label{videosetdisplayformat} + int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, videoDisplayFormat\_t format);}{ + This ioctl call asks the Video Device to select the video format to be applied + by the MPEG chip on the video. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_DISPLAY\_FORMAT for this command.\\ + videoDisplayFormat\_t format & Selects the video format to be used.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal parameter format.\\ +} + +\ifunction{VIDEO\_STILLPICTURE}{ + int ioctl(fd, int request = VIDEO\_STILLPICTURE, struct videoDisplayStillPicture *sp);}{ + 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. + }{ + 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.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EFAULT & sp points to an invalid iframe.\\ +} + +\ifunction{VIDEO\_FAST\_FORWARD}{ + int ioctl(fd, int request = VIDEO\_FAST\_FORWARD, int nFrames);}{ + This ioctl call asks the Video Device to skip decoding of N number of I-frames. + This call can only be used if VIDEO\_SOURCE\_MEMORY is selected. + }{ + 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.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EPERM & Mode VIDEO\_SOURCE\_MEMORY not selected.\\ + EINVAL & Illegal parameter format.\\ +} + +\ifunction{VIDEO\_SLOWMOTION}{ + int ioctl(fd, int request = VIDEO\_SLOWMOTION, int nFrames);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SLOWMOTION for this command.\\ + int nFrames & The number of times to repeat each frame.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EPERM & Mode VIDEO\_SOURCE\_MEMORY not selected.\\ + EINVAL & Illegal parameter format.\\ +} + +\ifunction{VIDEO\_GET\_CAPABILITIES}{ + int ioctl(fd, int request = VIDEO\_GET\_CAPABILITIES, unsigned int *cap);}{ + This ioctl call asks the video device about its decoding capabilities. + On success it returns and integer which has bits set according to the + defines in section \ref{videocaps}. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_GET\_CAPABILITIES for this command.\\ + unsigned int *cap & Pointer to a location where to store the + capability information.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EFAULT & cap points to an invalid iframe.\\ +} + +\ifunction{VIDEO\_SET\_ID}{ + int ioctl(int fd, int request = VIDEO\_SET\_ID, int id);}{ + This ioctl selects which sub-stream is to be decoded if a program or + system stream is sent to the video device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_ID for this command.\\ + int id& video sub-stream id + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Invalid sub-stream id. +} + +\ifunction{VIDEO\_CLEAR\_BUFFER}{ + int ioctl(fd, int request = VIDEO\_CLEAR\_BUFFER);}{ + This ioctl call clears all video buffers in the driver and + in the decoder hardware. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_CLEAR\_BUFFER for this command.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ +} + +\ifunction{VIDEO\_SET\_STREAMTYPE}{ + int ioctl(fd, int request = VIDEO\_SET\_STREAMTYPE, int type);}{ + This ioctl tells the driver which kind of stream to expect + being written to it. If this call is not used the default of video PES + is used. Some drivers might not support this call and always expect PES. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_STREAMTYPE for this command.\\ + int type & stream type\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& type is not a valid or supported stream type.\\ +} + +\ifunction{VIDEO\_SET\_FORMAT}{ +\label{videosetformat} + int ioctl(fd, int request = VIDEO\_SET\_FORMAT, videoFormat\_t format); +}{ + This ioctl sets the screen format (aspect ratio) of the connected + output device (TV) so that the output of the decoder can + be adjusted accordingly. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_FORMAT for this command.\\ + videoFormat\_t format& video format of TV as defined in section \ref{videoformat}.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& format is not a valid video format.\\ +} + +\ifunction{VIDEO\_SET\_SYSTEM}{ +\label{videosetsystem} + int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , videoSystem\_t system); +}{ + This ioctl sets the television output format. The format (see section + \ref{videosys}) may vary from the color format of the displayed MPEG + stream. If the hardware is not able to display the requested format + the call will return an error. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_FORMAT for this command.\\ + videoSystem\_t system& video system of TV output.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& system is not a valid or supported video system.\\ +} + +\ifunction{VIDEO\_SET\_HIGHLIGHT}{ +\label{videosethighlight} + int ioctl(fd, int request = VIDEO\_SET\_HIGHLIGHT ,videoHighlight\_t *vhilite) +}{ + This ioctl sets the SPU highlight information for the menu access of + a DVD. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_HIGHLIGHT for this command.\\ + videoHighlight\_t *vhilite& SPU Highlight information according to + section \ref{vhilite}.\\ +}{ + EBADF& fd is not a valid open file descriptor. \\ + EINVAL& input is not a valid highlight setting.\\ +} + + +\ifunction{VIDEO\_SET\_SPU}{ +\label{videosetspu} + int ioctl(fd, int request = VIDEO\_SET\_SPU , videoSPU\_t *spu) +}{ + This ioctl activates or deactivates SPU decoding in a DVD input + stream. It can only be used, if the driver is able to handle a DVD + stream. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_SPU for this command.\\ + videoSPU\_t *spu& SPU decoding (de)activation and subid setting + according to section \ref{videospu}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& input is not a valid spu setting or driver cannot handle SPU.\\ +} + + +\ifunction{VIDEO\_SET\_SPU\_PALETTE}{ +\label{videosetspupalette} + int ioctl(fd, int request = VIDEO\_SET\_SPU\_PALETTE ,videoSPUPalette\_t *palette ) +}{ + This ioctl sets the SPU color palette. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_SPU\_PALETTE for this command.\\ + videoSPUPalette\_t *palette& SPU palette according to section \ref{vspupal}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& input is not a valid palette or driver doesn't handle SPU.\\ +} + + + +\ifunction{VIDEO\_GET\_NAVI}{ +\label{videosetnavi} + int ioctl(fd, int request = VIDEO\_GET\_NAVI , videoNaviPack\_t *navipack) +}{ + This ioctl returns navigational information from the DVD stream. This is + especially needed if an encoded stream has to be decoded by the hardware. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_GET\_NAVI for this command.\\ + videoNaviPack\_t *navipack& PCI or DSI pack (private stream 2) + according to section \ref{videonavi}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EFAULT& driver is not able to return navigational information\\ +} + + +\ifunction{VIDEO\_SET\_ATTRIBUTES}{ +\label{videosetattributes} + int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,videoAttributes\_t + vattr) +}{ + This ioctl is intended for DVD playback and allows you to set + certain information about the stream. Some hardware may not need + this information, but the call also tells the hardware to prepare + for DVD playback. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_ATTRIBUTE for this command.\\ + videoAttributes\_t vattr& video attributes according to section \ref{vattrib}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& input is not a valid attribute setting.\\ +} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: -- cgit v1.2.3 From 7577c23439dfbc1d67e490d9dfa4cbd8e3b548ed Mon Sep 17 00:00:00 2001 From: rjkm Date: Sun, 16 Sep 2001 22:27:38 -0300 Subject: added new API docs --- dvb-spec/dvbapi/frontend.tex | 612 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 612 insertions(+) create mode 100644 dvb-spec/dvbapi/frontend.tex diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex new file mode 100644 index 000000000..74f21225d --- /dev/null +++ b/dvb-spec/dvbapi/frontend.tex @@ -0,0 +1,612 @@ +\devsec{DVB Frontend API} + +The DVB frontend device controls the tuner and DVB demodulator hardware. +It can be accessed through \texttt{/dev/ost/frontend}. +If you are using \texttt{devfs} you can use \texttt{/dev/dvb/card0/frontend}. +The frontend device will only be made visible through \texttt{devfs} +if the corresponding card actually has a frontend. Cards which support +the DVB API but, e.g., only can play back recordings, will not offer the +frontend device. + +\devsubsec{Frontend Data Types} + +\devsubsubsec{frontend status} +\label{frontendstatus} + +Several functions of the frontend device use the feStatus data +type defined by +\begin{verbatim} +typedef uint32_t feStatus; +\end{verbatim} +to indicate the current state and/or state changes of +the frontend hardware. + +\noindent +It can take on the values +\begin{verbatim} +#define FE_HAS_POWER 1 +#define FE_HAS_SIGNAL 2 +#define FE_SPECTRUM_INV 4 +#define FE_HAS_LOCK 8 +#define TUNER_HAS_LOCK 128 +\end{verbatim} +which can be ORed together and have the following meaning: + +\medskip + +\begin{tabular}{lp{11cm}} +FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ +FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ +FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ +FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ +TUNER\_HAS\_LOCK & the tuner has a frequency lock +\end{tabular} + + +\devsubsubsec{frontend parameters} +\label{frontendparameters} + +The kind of parameters passed to the frontend device for tuning +depend on the kind of hardware you are using. +All kinds of parameters are combined as a union in the +FrontendParameters structure: +\begin{verbatim} +typedef struct { + __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ + /* intermediate frequency in kHz for QPSK */ + union { + QPSKParameters qpsk; + QAMParameters qam; + OFDMParameters ofdm; + } u; +} FrontendParameters; +\end{verbatim} + +For satellite QPSK frontends you have to use QPSKParameters defined by +\begin{verbatim} +typedef struct { + __u32 SymbolRate; /* symbol rate in Symbols per second */ + CodeRate FEC_inner; /* forward error correction (see above) */ +} QPSKParameters; +\end{verbatim} +for cable QAM frontend you use the QAMParameters structure +\begin{verbatim} +typedef struct { + __u32 SymbolRate; /* symbol rate in Symbols per second */ + CodeRate FEC_inner; /* forward error correction (see above) */ + CodeRate FEC_outer; /* forward error correction (see above) */ + Modulation QAM; /* modulation type (see above) */ +} QAMParameters; +\end{verbatim} +DVB-T frontends are supported by the OFDMParamters structure +\begin{verbatim} +typedef struct { + BandWidth bandWidth; + CodeRate HP_CodeRate; /* high priority stream code rate */ + CodeRate LP_CodeRate; /* low priority stream code rate */ + Modulation Constellation; /* modulation type (see above) */ + TransmitMode TransmissionMode; + GuardInterval guardInterval; + Hierarchy HierarchyInformation; +} OFDMParameters; +\end{verbatim} + +In the case of QPSK frontends the Frequency field specifies the intermediate +frequency, i.e. the offset which is effectively added to the local oscillator +frequency (LOF) of the LNB. +The intermediate frequency has to be specified in units of kHz. +For QAM and OFDM frontends the Frequency specifies the absolute frequency +and is given in Hz. + +\noindent +The possible values for the FEC\_inner field are +\begin{verbatim} +enum { + FEC_AUTO, + FEC_1_2, + FEC_2_3, + FEC_3_4, + FEC_5_6, + FEC_7_8, + FEC_NONE +}; +\end{verbatim} +which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., +no error correction or auto detection. + +\noindent +For cable and terrestrial frontends (QAM and OFDM) one also has to +specify the quadrature modulation mode which can be one of the following: +\begin{verbatim} +typedef enum +{ QPSK, + QAM_16, + QAM_32, + QAM_64, + QAM_128, + QAM_256 +} QAM_TYPE; +\end{verbatim} + +Finally, there are several more parameters for OFDM: +\begin{verbatim} +typedef enum { + TRANSMISSION_MODE_2K, + TRANSMISSION_MODE_8K +} TransmitMode; +\end{verbatim} + +\begin{verbatim} +typedef enum { + BANDWIDTH_8_MHZ, + BANDWIDTH_7_MHZ, + BANDWIDTH_6_MHZ +} BandWidth; +\end{verbatim} + +\begin{verbatim} +typedef enum { + GUARD_INTERVAL_1_32, + GUARD_INTERVAL_1_16, + GUARD_INTERVAL_1_8, + GUARD_INTERVAL_1_4 +} GuardInterval; +\end{verbatim} + +\begin{verbatim} +typedef enum { + HIERARCHY_NONE, + HIERARCHY_1, + HIERARCHY_2, + HIERARCHY_4 +} Hierarchy; +\end{verbatim} + + +\devsubsubsec{frontend events} +\label{frontendevents} + +\begin{verbatim} +enum { + FE_UNEXPECTED_EV, + FE_COMPLETION_EV, + FE_FAILURE_EV +}; +\end{verbatim} + +\begin{verbatim} +typedef struct { + EventType type; /* type of event, FE_UNEXPECTED_EV, ... */ + long timestamp; /* time in seconds since 1970-01-01 */ + + union { + struct { + FrontendStatus previousStatus; /* status before event */ + FrontendStatus currentStatus; /* status during event */ + } unexpectedEvent; + FrontendParameters completionEvent; /* parameters for which the + tuning succeeded */ + FrontendStatus failureEvent; /* status at failure (e.g. no lock) */ + } u; +} FrontendEvent; +\end{verbatim} + +\begin{verbatim} +struct qpskRegister { + uint8_t chipId; + uint8_t address; + uint8_t value; +}; +\end{verbatim} + +\begin{verbatim} +struct qamRegister { + uint8_t chipId; + uint8_t address; + uint8_t value; +}; +\end{verbatim} + +\begin{verbatim} +struct qpskFrontendInfo { + uint32_t minFrequency; + uint32_t maxFrequency; + uint32_t maxSymbolRate; + uint32_t minSymbolRate; + uint32_t hwType; + uint32_t hwVersion; +}; +\end{verbatim} + +\begin{verbatim} +struct qamFrontendInfo { + uint32_t minFrequency; + uint32_t maxFrequency; + uint32_t maxSymbolRate; + uint32_t minSymbolRate; + uint32_t hwType; + uint32_t hwVersion; +}; +\end{verbatim} + +\begin{verbatim} +typedef enum { + FE_POWER_ON, + FE_POWER_STANDBY, + FE_POWER_SUSPEND, + FE_POWER_OFF +} powerState_t; +\end{verbatim} + + +\clearpage + + +\devsubsec{Frontend Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named frontend device (e.g. /dev/ost/qpskfe + for a satellite frontend or /dev/ost/qamfe for a cable frontend) + 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. + + }{ + const char *deviceName & Name of specific video device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + 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. + This system call closes a previously opened audio device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\ifunction{OST\_SELFTEST}{ + int ioctl(int fd, int request = OST\_SELFTEST);}{ + This ioctl call initiates an automatic self-test of the front-end hardware. + This call requires read/write access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals OST\_SELFTEST for this command.\\ + }{ + -1& Self test failure.\\ +} + +\ifunction{OST\_SET\_POWER\_STATE}{ + int ioctl(int fd, int request = OST\_SET\_POWER\_STATE, uint32\_t state);}{ + 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 supports 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: \\ + \begin{center} + \begin{tabular}[h]{cll} + number of low-power & requested state & resulting state\\ + states supported &&\\ + \\ + 1 & standby & suspend \\ + 1 & suspend & suspend \\ + 0 & standby & on \\ + 0 & suspend & on + \end{tabular} + \end{center}\\ + 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.) + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals OST\_SET\_POWER\_STATE for this command.\\ + uint32\_t state & Requested power state. One of: \\ + & + \begin{tabular}[h]{ll} + 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\\ + \end{tabular} + }{ + 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. +} + +\ifunction{FE\_GET\_POWER\_STATE}{ + int ioctl(int fd, int request = OST\_GET\_POWER\_STATE, uint32\_t *state);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals OST\_GET\_POWER\_STATE for this command.\\ + uint32\_t *state & Requested power state. One of: \\ + & + \begin{tabular}[h]{ll} + 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\\ + \end{tabular} + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINVAL& Illegal state, or not available on this device.\\ + EFAULT& state points to invalid address.\\ + ENOSYS& Function not available for this device. +} + +\ifunction{FE\_READ\_STATUS}{ + int ioctl(int fd, int request = FE\_READ\_STATUS, feStatus *status);}{ + This ioctl call returns status information about the front-end. + This call only requires read-only access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_READ\_STATUS for this command.\\ + struct feStatus *status&Points to the location where the front-end + status word is to be stored. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& status points to invalid address.\\ +} + +\ifunction{FE\_READ\_BER}{ + int ioctl(int fd, int request = FE\_READ\_BER, uint32\_t *ber);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_READ\_BER for this command.\\ + uint32\_t *ber & 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\cdot 10^{-6}$, or 1 error in 400000 bits. + }{ + 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. +} + +\ifunction{FE\_READ\_SNR}{ + int ioctl(int fd, int request = FE\_READ\_SNR, int32\_t *snr);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_READ\_SNR for this command.\\ + int32\_t *snr& 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. +}{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& snr 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. +} + +\ifunction{FE\_READ\_SIGNAL\_STRENGTH}{ + int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int32\_t *strength); +}{ +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. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_READ\_SIGNAL\_STRENGTH for this command.\\ +int32\_t *strength & 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. +}{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& status 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. +} + +\ifunction{FE\_READ\_UNCORRECTED\_BLOCKS}{ + int ioctl( int fd, int request = FE\_READ\_UNCORRECTED\_BLOCKS, uint32\_t *ublocks); }{ + This ioctl call returns the number of uncorrected blocks detected by + the device driver during its lifetime. + For meaningful measurements, the increment in + block count during a specific time interval should be calculated. + For this command, read-only access to the device is sufficient.\\ + Note that the counter will wrap to zero after its maximum count has + been reached. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_READ\_UNCORRECTED\_BLOCKS for this command.\\ +uint32\_t *ublocks & The total number of uncorrected blocks seen +by the driver so far. +}{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& ublocks points to invalid address.\\ + ENOSYS& Function not available for this device. +} + + +\ifunction{FE\_GET\_NEXT\_FREQUENCY}{ + int ioctl( int fd, int request = FE\_GET\_NEXT\_FREQUENCY, uint32\_t *freq);}{ + 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 efficient 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.\\ + Note that scanning may still be excruciatingly slow on some hardware, for + other reasons than a non-optimal scanning step size. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_GET\_NEXT\_FREQUENCY for this command.\\ + uint32\_t *freq& Input: a given frequency \\ + & Output: the frequency corresponding to + the next higher frequency setting.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& freq points to invalid address.\\ + EINVAL& Maximum supported frequency reached.\\ + ENOSYS& Function not available for this device. +} + +\ifunction{FE\_GET\_NEXT\_SYMBOL\_RATE}{ + int ioctl( int fd, int request = FE\_GET\_NEXT\_SYMBOL\_RATE, uint32\_t *symbolRate); + }{ + 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 efficient 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_GET\_NEXT\_SYMBOL\_RATE for this command.\\ + uint32\_t *symbolRate& Input: a given symbol rate \\ + & Output: the symbol rate corresponding to + the next higher symbol rate.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& symbolRate points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ + ENOSYS& Function not available for this device. +} + +\ifunction{FE\_SET\_FRONTEND}{ + int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct FrontendParameters *p);}{ + This ioctl call starts a tuning operation using specified parameters. + The result of this call will be successful if the parameters were valid and + the tuning could be initiated. + The result of the tuning operation in itself, however, will arrive + asynchronously as an event (see documentation for FE\_GET\_EVENT + and FrontendEvent.) + If a new FE\_SET\_FRONTEND operation is initiated before the previous + one was completed, + the previous operation will be aborted in favor of the new one. + This command requires read/write access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_SET\_FRONTEND for this command.\\ + struct FrontendParameters *p& Points to parameters for tuning operation.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& p points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ +} + +\ifunction{FE\_GET\_EVENT}{ + int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct qpskEvent *ev);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals QPSK\_GET\_EVENT for this command.\\ + struct qpskEvent *ev&Points to the location where the event, if any, is to be stored. + }{ + 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.\\ +} + +\ifunction{FE\_GET\_INFO}{ + int ioctl(int fd, int request = FE\_GET\_INFO, struct FrontendInfo *info);}{ + This ioctl call returns information about the front-end. + This call only requires read-only access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_GET\_INFO for this command.\\ + struct qpskFrontendInfo *info & Points to the location where the front-end + information is to be stored. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& info points to invalid address.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: -- cgit v1.2.3 From f1e2fc77631891bd568baff424cbe535a2795d65 Mon Sep 17 00:00:00 2001 From: rjkm Date: Wed, 19 Sep 2001 18:48:28 -0300 Subject: removed some typos --- dvb-spec/dvbapi/frontend.tex | 1 - dvb-spec/dvbapi/kdapi.tex | 4 ++-- dvb-spec/dvbapi/sec.tex | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index 74f21225d..5b496c688 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -288,7 +288,6 @@ typedef enum { another front-end device. To affect an unconditional power down, it should be done explicitly using the OST\_SET\_POWER\_STATE ioctl. - This system call closes a previously opened audio device. }{ int fd & File descriptor returned by a previous call to open().\\ }{ diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex index 6cee25c85..59490299b 100644 --- a/dvb-spec/dvbapi/kdapi.tex +++ b/dvb-spec/dvbapi/kdapi.tex @@ -41,7 +41,7 @@ typedef enum { \label{dmxtspest} The structure -/\begin{verbatim} +\begin{verbatim} typedef enum { DMX_TS_PES_AUDIO, /* also send packets to audio decoder (if it exists) */ @@ -109,8 +109,8 @@ typedef struct dmx_pes_feed_s { \end{verbatim} -\begin{verbatim} \label{sectionfilter} +\begin{verbatim} typedef struct { __u8 filter_value [DMX_MAX_FILTER_SIZE]; __u8 filter_mask [DMX_MAX_FILTER_SIZE]; diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex index 6ccd89481..88342c3a6 100644 --- a/dvb-spec/dvbapi/sec.tex +++ b/dvb-spec/dvbapi/sec.tex @@ -198,7 +198,7 @@ typedef enum { EINTERNAL & Internal error in the device driver.\\ } -\ifunction{SEC\_RESET\_OVERLOAD}{ +\ifunction{SEC\_SEND\_SEQUENCE}{ int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); }{ This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC -- cgit v1.2.3 From 4b03c3f1a363c428d5bf45e040073345d336ec1c Mon Sep 17 00:00:00 2001 From: rjkm Date: Fri, 21 Sep 2001 09:47:12 -0300 Subject: added inversion field --- dvb-spec/dvbapi/frontend.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index 5b496c688..23b9d3e22 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -26,8 +26,11 @@ It can take on the values \begin{verbatim} #define FE_HAS_POWER 1 #define FE_HAS_SIGNAL 2 -#define FE_SPECTRUM_INV 4 +#define FE_SPECTRUM_INV 4 #define FE_HAS_LOCK 8 +#define FE_HAS_CARRIER 16 +#define FE_HAS_VITERBI 32 +#define FE_HAS_SYNC 64 #define TUNER_HAS_LOCK 128 \end{verbatim} which can be ORed together and have the following meaning: @@ -39,6 +42,9 @@ FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ +FE\_HAS\_CARRIER & carrier detected in signal\\ +FE\_HAS\_VITERBI & lock at viterbi decoder stage\\ +FE\_HAS\_SYNC & TS sync bytes detected \\ TUNER\_HAS\_LOCK & the tuner has a frequency lock \end{tabular} @@ -54,6 +60,7 @@ FrontendParameters structure: typedef struct { __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ /* intermediate frequency in kHz for QPSK */ + SpectralInversion Inversion; /* spectral inversion */ union { QPSKParameters qpsk; QAMParameters qam; @@ -73,8 +80,8 @@ for cable QAM frontend you use the QAMParameters structure \begin{verbatim} typedef struct { __u32 SymbolRate; /* symbol rate in Symbols per second */ - CodeRate FEC_inner; /* forward error correction (see above) */ CodeRate FEC_outer; /* forward error correction (see above) */ + CodeRate FEC_inner; /* forward error correction (see above) */ Modulation QAM; /* modulation type (see above) */ } QAMParameters; \end{verbatim} @@ -98,6 +105,18 @@ The intermediate frequency has to be specified in units of kHz. For QAM and OFDM frontends the Frequency specifies the absolute frequency and is given in Hz. +The Inversion field can take one of these values: +\begin{verbatim} +typedef enum { + INVERSION_OFF, + INVERSION_ON, + INVERSION_AUTO +} SpectralInversion; +\end{verbatim} +It indicates if spectral inversion should be presumed or not. +In the automatic setting (INVERSION_AUTO) the hardware will +try to figure out the correct setting by itself. + \noindent The possible values for the FEC\_inner field are \begin{verbatim} -- cgit v1.2.3 From bb5ef2e954dffbdc1ec75b20ead76b202365862a Mon Sep 17 00:00:00 2001 From: mocm Date: Mon, 15 Oct 2001 11:17:02 -0200 Subject: added ignore --- dvb-spec/dvbapi/.cvsignore | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 dvb-spec/dvbapi/.cvsignore diff --git a/dvb-spec/dvbapi/.cvsignore b/dvb-spec/dvbapi/.cvsignore new file mode 100644 index 000000000..fb6974f6b --- /dev/null +++ b/dvb-spec/dvbapi/.cvsignore @@ -0,0 +1,11 @@ +dvbapi.ps +dvbstb.ps +dvbstb.pst +dvbapi.bbl +dvbapi.aux +dvbapi.blg +dvbapi.dvi +dvbapi.log +dvbapi.pdf +dvbapi.out +dvbapi.toc -- cgit v1.2.3 From 231baf9444ac6726bec99d892d2cff2c4af32f5a Mon Sep 17 00:00:00 2001 From: mocm Date: Tue, 12 Feb 2002 14:29:24 -0200 Subject: updateupdatedd --- dvb-spec/dvbapi/frontend.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index 23b9d3e22..ceb2f93db 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -114,7 +114,7 @@ typedef enum { } SpectralInversion; \end{verbatim} It indicates if spectral inversion should be presumed or not. -In the automatic setting (INVERSION_AUTO) the hardware will +In the automatic setting (\verb INVERSION_AUTO) the hardware will try to figure out the correct setting by itself. \noindent -- cgit v1.2.3 From d50611422c6fb579b75a45b4d36613147abb69e4 Mon Sep 17 00:00:00 2001 From: mocm Date: Thu, 14 Feb 2002 08:51:00 -0200 Subject: some updates and correctionsome updates and correctionss --- dvb-spec/dvbapi/examples.tex | 115 ++++++++++++++++++++++--------------------- dvb-spec/dvbapi/intro.tex | 9 ++-- dvb-spec/dvbapi/title.tex | 4 +- 3 files changed, 64 insertions(+), 64 deletions(-) diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex index d2786a6f6..114579b80 100644 --- a/dvb-spec/dvbapi/examples.tex +++ b/dvb-spec/dvbapi/examples.tex @@ -23,30 +23,32 @@ tuners, but can easily be adjusted for QAM. #include #define DMX "/dev/ost/demux" -#define QPSK "/dev/ost/qpskfe" +#define FRONT "/dev/ost/frontend" #define SEC "/dev/ost/sec" -/* routine for checking if we have a signal */ -int has_signal(int front) +/* routine for checking if we have a signal and other status information*/ +int FEReadStatus(int fd, FrontendStatus *stat) { - feStatus stat; - - if ( front < 0 ){ - if((front = open(QPSK,O_RDWR)) < 0){ - perror("FRONTEND DEVICE: "); - return -1; - } - } + int ans; - FEReadStatus(front, &stat); - if (stat & FE_HAS_SIGNAL) - return 0; - else { - printf("Tuning failed\n"); + if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ + perror("FE READ STATUS: "); return -1; } + + if (*stat & FE_HAS_POWER) + printf("FE HAS POWER\n"); + + if (*stat & FE_HAS_SIGNAL) + printf("FE HAS SIGNAL\n"); + + if (*stat & FE_SPECTRUM_INV) + printf("SPEKTRUM INV\n"); + + return 0; } + /* tune qpsk */ /* freq: frequency of transponder */ /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */ @@ -65,14 +67,15 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, struct secCommand scmd; struct secCmdSequence scmds; struct dmxPesFilterParams pesFilterParams; - struct qpskParameters qpsk; + FrontendParameters frp; struct pollfd pfd[1]; - struct qpskEvent event; - int front, sec, demux1, demux2, demux3; + FrontendEvent event; + int demux1, dmeux2, demux3, front, - /* Open all the necessary the devices */ + frequency = (uint32_t) freq; + symbolrate = (uint32_t) srate; - if((front = open(QPSK,O_RDWR)) < 0){ + if((front = open(FRONT,O_RDWR)) < 0){ perror("FRONTEND DEVICE: "); return -1; } @@ -82,40 +85,41 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, return -1; } - if ((demux1 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ - perror("DEMUX DEVICE: "); - return -1; + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } } - if ((demux2 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ - perror("DEMUX DEVICE: "); - return -1; + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } } - if ((demux3 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ - perror("DEMUX DEVICE: "); - return -1; + if (demux3 < 0){ + if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } } - /* Set the frequency of the transponder, taking into account the - local frequencies of the LNB */ - if (freq < lnb_slof) { - qpsk.iFrequency = (freq - lnb_lof1); + frp.Frequency = (freq - lnb_lof1); scmds.continuousTone = SEC_TONE_OFF; } else { - qpsk.iFrequency = (freq - lnb_lof2); + frp.Frequency = (freq - lnb_lof2); scmds.continuousTone = SEC_TONE_ON; } - - /* Set the polarity of the transponder by setting the correct - voltage on the universal LNB */ - + frp.Inversion = INVERSION_AUTO; if (pol) scmds.voltage = SEC_VOLTAGE_18; else scmds.voltage = SEC_VOLTAGE_13; - - /* In case we have a DiSEqC, set it to the correct address */ - + scmd.type=0; scmd.u.diseqc.addr=0x10; scmd.u.diseqc.cmd=0x38; @@ -127,32 +131,31 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, scmds.miniCommand=SEC_MINI_NONE; scmds.numCommands=1; scmds.commands=&scmd; - - /* Send the data to the SEC device to prepare the LNB for tuning */ if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ perror("SEC SEND: "); return -1; } - /* Set symbol rate and FEC */ + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } - qpsk.SymbolRate = srate; - qpsk.FEC_inner = fec; + frp.u.qpsk.SymbolRate = srate; + frp.u.qpsk.FEC_inner = fec; - /* Now send it all to the frontend device */ - if (ioctl(front, QPSK_TUNE, &qpsk) < 0){ + if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ perror("QPSK TUNE: "); return -1; } - /* poll for QPSK event to check if tuning worked */ pfd[0].fd = front; pfd[0].events = POLLIN; if (poll(pfd,1,3000)){ if (pfd[0].revents & POLLIN){ printf("Getting QPSK event\n"); - if ( ioctl(front, QPSK_GET_EVENT, &event) + if ( ioctl(front, FE_GET_EVENT, &event) == -EBUFFEROVERFLOW){ perror("qpsk get event"); @@ -166,15 +169,14 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, case FE_FAILURE_EV: printf("failure event\n"); return -1; - case FE_COMPLETION_EV: + + case FE_COMPLETION_EV: printf("completion event\n"); } } } - /* Set the filters for video, audio and teletext demuxing */ - pesFilterParams.pid = vpid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_DECODER; @@ -205,8 +207,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, return -1; } - /* check if we have a signal */ - return has_signal(front); + return has_signal(fds); } \end{verbatim} @@ -262,7 +263,7 @@ int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) } if (demux2 < 0){ - if ((demux2=open(DMXdemuxs, O_RDWR|O_NONBLOCK)) + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) < 0){ perror("DEMUX DEVICE: "); return -1; diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex index acb6b4b85..e026a86e1 100644 --- a/dvb-spec/dvbapi/intro.tex +++ b/dvb-spec/dvbapi/intro.tex @@ -110,8 +110,7 @@ The individual devices are called \begin{itemize} \item \texttt{/dev/ost/audio}, \item \texttt{/dev/ost/video}, -\item \texttt{/dev/ost/qpskfe}, -\item \texttt{/dev/ost/qamfe}, +\item \texttt{/dev/ost/frontend}, \item \texttt{/dev/ost/sec}, \item \texttt{/dev/ost/demux}, \item \texttt{/dev/ost/ca}, @@ -151,7 +150,7 @@ with multiple DVB cards with more than one frontend or demultiplexer. Consider, e.g., two DVB cards, one with two frontends and one demultiplexer, the other with one frontend and two demultiplexers. If we just assign them consecutive numbers, there would be a demultiplexer -and a frontend which do notbelong to the same card but have +and a frontend which do not belong to the same card but have the same number. With \textsl{devfs} we propose a different scheme for the device names. @@ -169,14 +168,14 @@ two demultiplexers and an MPEG2 audio/video decoder is added, the complete \texttt{/dev/dvb} tree will look like this: \begin{verbatim} -/dev/dvb/card0/qam0 +/dev/dvb/card0/frontend0 demux0 /dev/dvb/card1/video0 audio0 demux0 demux1 - qpskfe0 + frontend0 sec0 \end{verbatim} diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex index ce8b584c1..574464d23 100644 --- a/dvb-spec/dvbapi/title.tex +++ b/dvb-spec/dvbapi/title.tex @@ -12,7 +12,7 @@ % Rosenthalerstr. 51\\ % 10178 Berlin\\Germany } -\date{09/15/2001\\V 0.9.4} +\date{02/14/2002\\V 0.9.4} \maketitle \newpage @@ -21,4 +21,4 @@ % Local Variables: % mode: latex % TeX-master: "dvbapi" -% End: \ No newline at end of file +% End: -- cgit v1.2.3 From 7dddc78f51709f911af1106541603949765e3c9f Mon Sep 17 00:00:00 2001 From: mocm Date: Fri, 15 Feb 2002 08:17:18 -0200 Subject: corrections to audio_set_id documentation --- dvb-spec/dvbapi/audio.tex | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex index 8c5b4fe82..e81dd2f89 100644 --- a/dvb-spec/dvbapi/audio.tex +++ b/dvb-spec/dvbapi/audio.tex @@ -354,7 +354,12 @@ typedef uint16_t audioAttributes_t; \ifunction{AUDIO\_SET\_ID}{ int ioctl(int fd, int request = AUDIO\_SET\_ID, int id);}{ This ioctl selects which sub-stream is to be decoded if a program or - system stream is sent to the video device. + system stream is sent to the video device. If no audio stream type is set + the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for + AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow + for other stream types. If the stream type is set the id just + specifies the substream id of the audio stream and only the first 5 + bits are recognized. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_ID for this command.\\ @@ -382,7 +387,7 @@ typedef uint16_t audioAttributes_t; int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, int type);}{ This ioctl tells the driver which kind of audio stream to expect. This is useful if the stream offers several audio sub-streams - like MPEG2 audio and AC3. + like LPCM and AC3. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ @@ -395,7 +400,8 @@ typedef uint16_t audioAttributes_t; \ifunction{AUDIO\_SET\_EXT\_ID}{ int ioctl(fd, int request = AUDIO\_SET\_EXT\_ID, int id);}{ - This ioctl can be used to set the audio sub\_stream\_id for DVD playback + This ioctl can be used to set the extension id for MPEG streams in + DVD playback. Only the first 3 bits are recognized. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_EXT\_ID for this command.\\ -- cgit v1.2.3 From aed2950af0b53026e245705b265059ee9a439e1f Mon Sep 17 00:00:00 2001 From: mocm Date: Mon, 4 Mar 2002 09:27:48 -0300 Subject: some error corrections --- dvb-spec/dvbapi/dvbapi.tex | 2 +- dvb-spec/dvbapi/intro.tex | 10 +--------- dvb-spec/dvbapi/video.tex | 6 ++++-- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex index f9fcb841c..ad0251c01 100644 --- a/dvb-spec/dvbapi/dvbapi.tex +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -131,7 +131,7 @@ \renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} \lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} \rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} -\cfoot{\copyright 2001 convergence integrated media GmbH} +\cfoot{\copyright 2002 convergence GmbH} \input{intro.tex} diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex index e026a86e1..1d859fadb 100644 --- a/dvb-spec/dvbapi/intro.tex +++ b/dvb-spec/dvbapi/intro.tex @@ -68,7 +68,7 @@ time and re-inserted into the TS. The demultiplexer splits the TS into its components like audio and video streams. Besides usually several of such audio and video streams it also -contains data strams with information about the programs offered in this +contains data streams with information about the programs offered in this or other streams of the same provider. \item MPEG2 audio and video decoder @@ -118,14 +118,6 @@ The individual devices are called but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of these devices. -%Thus, the \texttt{audio} and \texttt{video} devices directly control -%the MPEG2 decoder audio and video decoder, respectively. -%Depending on the kind of frontend present (satellite, cable or -%terrestrial), it will be controlled either through the -%\texttt{qpsk} or \texttt{qamfe} device. -%DiSEqC or other kinds of control signals can be sent to the -%antenna hardware through the \texttt{sec} device. - If more than one card is present in the system the other cards can be accessed through the corresponding devices with the card's number appended. \texttt{/dev/ost/demux0} (which diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex index 67abb9586..2659db238 100644 --- a/dvb-spec/dvbapi/video.tex +++ b/dvb-spec/dvbapi/video.tex @@ -2,8 +2,10 @@ The DVB video device controls the MPEG2 video decoder of the DVB hardware. It can be accessed through \texttt{/dev/ost/video}. -The include file \texttt{ost/video.h} defines the data types and lists all I/O calls. - +The include file \texttt{ost/video.h} defines the data types and lists +all I/O calls. Please note that some DVB cards don't have their own +MPEG decoder, which results in the omission of the audio and video +device as well as the video4linux device. \devsubsec{Video Data Types} -- cgit v1.2.3 From a08ca2834d7a03676f72367ef3ff2a9cba3db387 Mon Sep 17 00:00:00 2001 From: rjkm Date: Wed, 6 Mar 2002 20:44:49 -0300 Subject: change include files --- dvb-spec/dvbapi/audio.tex | 12 +++-- dvb-spec/dvbapi/dvbapi.tex | 2 +- dvb-spec/dvbapi/examples.tex | 115 ++++++++++++++++++++++--------------------- dvb-spec/dvbapi/frontend.tex | 2 +- dvb-spec/dvbapi/intro.tex | 19 ++----- dvb-spec/dvbapi/title.tex | 4 +- dvb-spec/dvbapi/video.tex | 6 ++- 7 files changed, 80 insertions(+), 80 deletions(-) diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex index 8c5b4fe82..e81dd2f89 100644 --- a/dvb-spec/dvbapi/audio.tex +++ b/dvb-spec/dvbapi/audio.tex @@ -354,7 +354,12 @@ typedef uint16_t audioAttributes_t; \ifunction{AUDIO\_SET\_ID}{ int ioctl(int fd, int request = AUDIO\_SET\_ID, int id);}{ This ioctl selects which sub-stream is to be decoded if a program or - system stream is sent to the video device. + system stream is sent to the video device. If no audio stream type is set + the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for + AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow + for other stream types. If the stream type is set the id just + specifies the substream id of the audio stream and only the first 5 + bits are recognized. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_ID for this command.\\ @@ -382,7 +387,7 @@ typedef uint16_t audioAttributes_t; int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, int type);}{ This ioctl tells the driver which kind of audio stream to expect. This is useful if the stream offers several audio sub-streams - like MPEG2 audio and AC3. + like LPCM and AC3. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ @@ -395,7 +400,8 @@ typedef uint16_t audioAttributes_t; \ifunction{AUDIO\_SET\_EXT\_ID}{ int ioctl(fd, int request = AUDIO\_SET\_EXT\_ID, int id);}{ - This ioctl can be used to set the audio sub\_stream\_id for DVD playback + This ioctl can be used to set the extension id for MPEG streams in + DVD playback. Only the first 3 bits are recognized. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_EXT\_ID for this command.\\ diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex index f9fcb841c..ad0251c01 100644 --- a/dvb-spec/dvbapi/dvbapi.tex +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -131,7 +131,7 @@ \renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} \lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} \rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} -\cfoot{\copyright 2001 convergence integrated media GmbH} +\cfoot{\copyright 2002 convergence GmbH} \input{intro.tex} diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex index d2786a6f6..114579b80 100644 --- a/dvb-spec/dvbapi/examples.tex +++ b/dvb-spec/dvbapi/examples.tex @@ -23,30 +23,32 @@ tuners, but can easily be adjusted for QAM. #include #define DMX "/dev/ost/demux" -#define QPSK "/dev/ost/qpskfe" +#define FRONT "/dev/ost/frontend" #define SEC "/dev/ost/sec" -/* routine for checking if we have a signal */ -int has_signal(int front) +/* routine for checking if we have a signal and other status information*/ +int FEReadStatus(int fd, FrontendStatus *stat) { - feStatus stat; - - if ( front < 0 ){ - if((front = open(QPSK,O_RDWR)) < 0){ - perror("FRONTEND DEVICE: "); - return -1; - } - } + int ans; - FEReadStatus(front, &stat); - if (stat & FE_HAS_SIGNAL) - return 0; - else { - printf("Tuning failed\n"); + if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ + perror("FE READ STATUS: "); return -1; } + + if (*stat & FE_HAS_POWER) + printf("FE HAS POWER\n"); + + if (*stat & FE_HAS_SIGNAL) + printf("FE HAS SIGNAL\n"); + + if (*stat & FE_SPECTRUM_INV) + printf("SPEKTRUM INV\n"); + + return 0; } + /* tune qpsk */ /* freq: frequency of transponder */ /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */ @@ -65,14 +67,15 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, struct secCommand scmd; struct secCmdSequence scmds; struct dmxPesFilterParams pesFilterParams; - struct qpskParameters qpsk; + FrontendParameters frp; struct pollfd pfd[1]; - struct qpskEvent event; - int front, sec, demux1, demux2, demux3; + FrontendEvent event; + int demux1, dmeux2, demux3, front, - /* Open all the necessary the devices */ + frequency = (uint32_t) freq; + symbolrate = (uint32_t) srate; - if((front = open(QPSK,O_RDWR)) < 0){ + if((front = open(FRONT,O_RDWR)) < 0){ perror("FRONTEND DEVICE: "); return -1; } @@ -82,40 +85,41 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, return -1; } - if ((demux1 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ - perror("DEMUX DEVICE: "); - return -1; + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } } - if ((demux2 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ - perror("DEMUX DEVICE: "); - return -1; + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } } - if ((demux3 = open(DMX, O_RDWR|O_NONBLOCK)) < 0){ - perror("DEMUX DEVICE: "); - return -1; + if (demux3 < 0){ + if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } } - /* Set the frequency of the transponder, taking into account the - local frequencies of the LNB */ - if (freq < lnb_slof) { - qpsk.iFrequency = (freq - lnb_lof1); + frp.Frequency = (freq - lnb_lof1); scmds.continuousTone = SEC_TONE_OFF; } else { - qpsk.iFrequency = (freq - lnb_lof2); + frp.Frequency = (freq - lnb_lof2); scmds.continuousTone = SEC_TONE_ON; } - - /* Set the polarity of the transponder by setting the correct - voltage on the universal LNB */ - + frp.Inversion = INVERSION_AUTO; if (pol) scmds.voltage = SEC_VOLTAGE_18; else scmds.voltage = SEC_VOLTAGE_13; - - /* In case we have a DiSEqC, set it to the correct address */ - + scmd.type=0; scmd.u.diseqc.addr=0x10; scmd.u.diseqc.cmd=0x38; @@ -127,32 +131,31 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, scmds.miniCommand=SEC_MINI_NONE; scmds.numCommands=1; scmds.commands=&scmd; - - /* Send the data to the SEC device to prepare the LNB for tuning */ if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ perror("SEC SEND: "); return -1; } - /* Set symbol rate and FEC */ + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } - qpsk.SymbolRate = srate; - qpsk.FEC_inner = fec; + frp.u.qpsk.SymbolRate = srate; + frp.u.qpsk.FEC_inner = fec; - /* Now send it all to the frontend device */ - if (ioctl(front, QPSK_TUNE, &qpsk) < 0){ + if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ perror("QPSK TUNE: "); return -1; } - /* poll for QPSK event to check if tuning worked */ pfd[0].fd = front; pfd[0].events = POLLIN; if (poll(pfd,1,3000)){ if (pfd[0].revents & POLLIN){ printf("Getting QPSK event\n"); - if ( ioctl(front, QPSK_GET_EVENT, &event) + if ( ioctl(front, FE_GET_EVENT, &event) == -EBUFFEROVERFLOW){ perror("qpsk get event"); @@ -166,15 +169,14 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, case FE_FAILURE_EV: printf("failure event\n"); return -1; - case FE_COMPLETION_EV: + + case FE_COMPLETION_EV: printf("completion event\n"); } } } - /* Set the filters for video, audio and teletext demuxing */ - pesFilterParams.pid = vpid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_DECODER; @@ -205,8 +207,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, return -1; } - /* check if we have a signal */ - return has_signal(front); + return has_signal(fds); } \end{verbatim} @@ -262,7 +263,7 @@ int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) } if (demux2 < 0){ - if ((demux2=open(DMXdemuxs, O_RDWR|O_NONBLOCK)) + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) < 0){ perror("DEMUX DEVICE: "); return -1; diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index 23b9d3e22..ceb2f93db 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -114,7 +114,7 @@ typedef enum { } SpectralInversion; \end{verbatim} It indicates if spectral inversion should be presumed or not. -In the automatic setting (INVERSION_AUTO) the hardware will +In the automatic setting (\verb INVERSION_AUTO) the hardware will try to figure out the correct setting by itself. \noindent diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex index acb6b4b85..1d859fadb 100644 --- a/dvb-spec/dvbapi/intro.tex +++ b/dvb-spec/dvbapi/intro.tex @@ -68,7 +68,7 @@ time and re-inserted into the TS. The demultiplexer splits the TS into its components like audio and video streams. Besides usually several of such audio and video streams it also -contains data strams with information about the programs offered in this +contains data streams with information about the programs offered in this or other streams of the same provider. \item MPEG2 audio and video decoder @@ -110,8 +110,7 @@ The individual devices are called \begin{itemize} \item \texttt{/dev/ost/audio}, \item \texttt{/dev/ost/video}, -\item \texttt{/dev/ost/qpskfe}, -\item \texttt{/dev/ost/qamfe}, +\item \texttt{/dev/ost/frontend}, \item \texttt{/dev/ost/sec}, \item \texttt{/dev/ost/demux}, \item \texttt{/dev/ost/ca}, @@ -119,14 +118,6 @@ The individual devices are called but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of these devices. -%Thus, the \texttt{audio} and \texttt{video} devices directly control -%the MPEG2 decoder audio and video decoder, respectively. -%Depending on the kind of frontend present (satellite, cable or -%terrestrial), it will be controlled either through the -%\texttt{qpsk} or \texttt{qamfe} device. -%DiSEqC or other kinds of control signals can be sent to the -%antenna hardware through the \texttt{sec} device. - If more than one card is present in the system the other cards can be accessed through the corresponding devices with the card's number appended. \texttt{/dev/ost/demux0} (which @@ -151,7 +142,7 @@ with multiple DVB cards with more than one frontend or demultiplexer. Consider, e.g., two DVB cards, one with two frontends and one demultiplexer, the other with one frontend and two demultiplexers. If we just assign them consecutive numbers, there would be a demultiplexer -and a frontend which do notbelong to the same card but have +and a frontend which do not belong to the same card but have the same number. With \textsl{devfs} we propose a different scheme for the device names. @@ -169,14 +160,14 @@ two demultiplexers and an MPEG2 audio/video decoder is added, the complete \texttt{/dev/dvb} tree will look like this: \begin{verbatim} -/dev/dvb/card0/qam0 +/dev/dvb/card0/frontend0 demux0 /dev/dvb/card1/video0 audio0 demux0 demux1 - qpskfe0 + frontend0 sec0 \end{verbatim} diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex index ce8b584c1..574464d23 100644 --- a/dvb-spec/dvbapi/title.tex +++ b/dvb-spec/dvbapi/title.tex @@ -12,7 +12,7 @@ % Rosenthalerstr. 51\\ % 10178 Berlin\\Germany } -\date{09/15/2001\\V 0.9.4} +\date{02/14/2002\\V 0.9.4} \maketitle \newpage @@ -21,4 +21,4 @@ % Local Variables: % mode: latex % TeX-master: "dvbapi" -% End: \ No newline at end of file +% End: diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex index 67abb9586..2659db238 100644 --- a/dvb-spec/dvbapi/video.tex +++ b/dvb-spec/dvbapi/video.tex @@ -2,8 +2,10 @@ The DVB video device controls the MPEG2 video decoder of the DVB hardware. It can be accessed through \texttt{/dev/ost/video}. -The include file \texttt{ost/video.h} defines the data types and lists all I/O calls. - +The include file \texttt{ost/video.h} defines the data types and lists +all I/O calls. Please note that some DVB cards don't have their own +MPEG decoder, which results in the omission of the audio and video +device as well as the video4linux device. \devsubsec{Video Data Types} -- cgit v1.2.3 From 6fd9805ce0670bf99c73ab708daf3ca38b55fc7d Mon Sep 17 00:00:00 2001 From: js Date: Tue, 1 Oct 2002 14:28:22 -0300 Subject: released under the GNU free documentation license --- dvb-spec/dvbapi/LICENSE | 355 +++++++++++++++++++++++++++++++++++++++++++ dvb-spec/dvbapi/dvbapi.tex | 6 +- dvb-spec/dvbapi/fdl.tex | 367 +++++++++++++++++++++++++++++++++++++++++++++ dvb-spec/dvbapi/title.tex | 17 ++- 4 files changed, 739 insertions(+), 6 deletions(-) create mode 100644 dvb-spec/dvbapi/LICENSE create mode 100644 dvb-spec/dvbapi/fdl.tex diff --git a/dvb-spec/dvbapi/LICENSE b/dvb-spec/dvbapi/LICENSE new file mode 100644 index 000000000..b42936beb --- /dev/null +++ b/dvb-spec/dvbapi/LICENSE @@ -0,0 +1,355 @@ + GNU Free Documentation License + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex index ad0251c01..e81940093 100644 --- a/dvb-spec/dvbapi/dvbapi.tex +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -131,7 +131,7 @@ \renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} \lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} \rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} -\cfoot{\copyright 2002 convergence GmbH} +\cfoot{\copyright\ 2002 Convergence GmbH} \input{intro.tex} @@ -145,6 +145,10 @@ \cleardoublepage +\input{fdl.tex} + +\cleardoublepage + \thispagestyle{plain}\chaptermark{Bibliography} \addcontentsline{toc}{chapter}{Bibliography} \bibliographystyle{bibsec} diff --git a/dvb-spec/dvbapi/fdl.tex b/dvb-spec/dvbapi/fdl.tex new file mode 100644 index 000000000..c0fcbe3f3 --- /dev/null +++ b/dvb-spec/dvbapi/fdl.tex @@ -0,0 +1,367 @@ +% fdl.tex +% This file is a chapter. It must be included in a larger document to work +% properly. + +\chapter{GNU Free Documentation License} + +Version 1.1, March 2000\\ + + Copyright \copyright\ 2000 Free Software Foundation, Inc.\\ + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +\section*{Preamble} + +The purpose of this License is to make a manual, textbook, or other +written document ``free'' in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +\section{Applicability and Definitions} + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, \LaTeX~input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +\section{Verbatim Copying} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\section{Copying in Quantity} + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\section{Modifications} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} + +\item Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +\item List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +\item State on the Title page the name of the publisher of the + Modified Version, as the publisher. +\item Preserve all the copyright notices of the Document. +\item Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +\item Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +\item Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +\item Include an unaltered copy of this License. +\item Preserve the section entitled ``History'', and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +\item Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +\item In any section entitled ``Acknowledgements'' or ``Dedications'', + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +\item Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +\item Delete any section entitled ``Endorsements''. Such a section + may not be included in the Modified Version. +\item Do not retitle any existing section as ``Endorsements'' + or to conflict in title with any Invariant Section. + +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties -- for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\section{Combining Documents} + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgements'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + + +\section{Collections of Documents} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + + +\section{Aggregation With Independent Works} + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +\section{Translation} + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +\section{Termination} + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\section{Future Revisions of This License} + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +\section*{ADDENDUM: How to use this License for your documents} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\begin{quote} + + Copyright \copyright\ YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + +\end{quote} + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being LIST''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex index 574464d23..693ed829d 100644 --- a/dvb-spec/dvbapi/title.tex +++ b/dvb-spec/dvbapi/title.tex @@ -4,17 +4,24 @@ \author{ \includegraphics{cimlogo.psi}\\ - Convergence integrated media GmbH\\\\ - Dr. Ralph J.K. Metzler\\ + Copyright \copyright 2002 Convergence GmbH\\\\ + Written by Dr. Ralph J.K. Metzler\\ \texttt{}\\\\ - Dr. Marcus O.C. Metzler\\ - \texttt{} + and Dr. Marcus O.C. Metzler\\ + \texttt{}\\ % Rosenthalerstr. 51\\ % 10178 Berlin\\Germany } -\date{02/14/2002\\V 0.9.4} +\date{10/01/2002\\V 0.9.5} + \maketitle +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation. +A copy of the license is included in the chapter entitled "GNU +Free Documentation License". + \newpage %\end{titlepage} -- cgit v1.2.3 From ab85b007da42f42856a775d8cff97332093f5b34 Mon Sep 17 00:00:00 2001 From: holger Date: Thu, 10 Oct 2002 15:59:05 -0300 Subject: make room for the new HEAD trunk --- dvb-spec/README.CABLE | 5 - dvb-spec/README.EON | 7 - dvb-spec/channel | 104 ----- dvb-spec/dvbapi/.cvsignore | 11 - dvb-spec/dvbapi/Makefile | 30 -- dvb-spec/dvbapi/audio.tex | 442 ------------------ dvb-spec/dvbapi/bibsection.sty | 29 -- dvb-spec/dvbapi/ca.tex | 127 ----- dvb-spec/dvbapi/cimlogo.psi | 122 ----- dvb-spec/dvbapi/demux.tex | 392 ---------------- dvb-spec/dvbapi/devices.tex | 12 - dvb-spec/dvbapi/dvbapi.tex | 166 ------- dvb-spec/dvbapi/dvbstb.fig | 59 --- dvb-spec/dvbapi/examples.tex | 366 --------------- dvb-spec/dvbapi/fig2pstex | 6 - dvb-spec/dvbapi/frontend.tex | 630 ------------------------- dvb-spec/dvbapi/getbb | 12 - dvb-spec/dvbapi/intro.tex | 183 -------- dvb-spec/dvbapi/kdapi.tex | 1007 ---------------------------------------- dvb-spec/dvbapi/sec.tex | 282 ----------- dvb-spec/dvbapi/title.tex | 24 - dvb-spec/dvbapi/video.tex | 686 --------------------------- 22 files changed, 4702 deletions(-) delete mode 100644 dvb-spec/README.CABLE delete mode 100644 dvb-spec/README.EON delete mode 100644 dvb-spec/channel delete mode 100644 dvb-spec/dvbapi/.cvsignore delete mode 100644 dvb-spec/dvbapi/Makefile delete mode 100644 dvb-spec/dvbapi/audio.tex delete mode 100644 dvb-spec/dvbapi/bibsection.sty delete mode 100644 dvb-spec/dvbapi/ca.tex delete mode 100644 dvb-spec/dvbapi/cimlogo.psi delete mode 100644 dvb-spec/dvbapi/demux.tex delete mode 100644 dvb-spec/dvbapi/devices.tex delete mode 100644 dvb-spec/dvbapi/dvbapi.tex delete mode 100644 dvb-spec/dvbapi/dvbstb.fig delete mode 100644 dvb-spec/dvbapi/examples.tex delete mode 100755 dvb-spec/dvbapi/fig2pstex delete mode 100644 dvb-spec/dvbapi/frontend.tex delete mode 100755 dvb-spec/dvbapi/getbb delete mode 100644 dvb-spec/dvbapi/intro.tex delete mode 100644 dvb-spec/dvbapi/kdapi.tex delete mode 100644 dvb-spec/dvbapi/sec.tex delete mode 100644 dvb-spec/dvbapi/title.tex delete mode 100644 dvb-spec/dvbapi/video.tex diff --git a/dvb-spec/README.CABLE b/dvb-spec/README.CABLE deleted file mode 100644 index de13af020..000000000 --- a/dvb-spec/README.CABLE +++ /dev/null @@ -1,5 +0,0 @@ -- The analog module is not fully supported yet. - The MSP3400 module will have to be extended to handle then audio and - video switching for the module. - If you want sound you will have to remove the module for now. - diff --git a/dvb-spec/README.EON b/dvb-spec/README.EON deleted file mode 100644 index df5098132..000000000 --- a/dvb-spec/README.EON +++ /dev/null @@ -1,7 +0,0 @@ -- If you do not receive any packets over the dvb0 device the reason could - be the rp_filter. - Check if your distribution enables this or disable it with: - - "echo 0 > /proc/sys/net/ipv4/conf/dvb0/rp_filter" - - This disables source validation by reversed path lookup. \ No newline at end of file diff --git a/dvb-spec/channel b/dvb-spec/channel deleted file mode 100644 index f17e8cb19..000000000 --- a/dvb-spec/channel +++ /dev/null @@ -1,104 +0,0 @@ -This file describes the format of the new channel config file. - -Comments start with # -Each section starts with one of the identifiers: LNB, DISEQC, ROTOR, ... - -IDs are either the official transponder, network, etc. id if it exists -and is unique, otherwise it is just a consecutive number assigned by -the application. -An LNB can also describe a cable TV outlet or a terrestrial antenna. -Names (as all parameters in brackets) are optional. In this case the -application should use the ID as name. - -The application should offer selection sorted by channel number, network, -satellite, bouquet. - - -# satellite definition -SAT - ID satid # ID = xxxy, sat is at position xxx.y degrees - [NAME name] - LNBID lnbid # LNB this sat is received with - [ROTORID rotorid] # rotor commands to position it on this sat - -# LNB definition -LNB - ID lnbid - [NAME name] - [INPUT input] # input of card which the lnb is connected to (default 0) - TYPE type # LNB, CATV or terrestrial antenna? - LOF1 offset1 # local oscillator frequency 1 - LOF2 offset2 # local oscillator frequency 2 - SLOF switchfreq # switching frequency - [DISEQCNR diseqcnr] # simple 2- or 4-switch DiSEqC - [DISEQCID diseqcid] - [INPUT input] - [SWITCHID switchid] - -# A transponder definition -TRANSPONDER - ID tpid - TYPE type # digital (DVB-S(1), C(2) or T(3)) or analog(0) ? - SATID satid - [NAME name] # if analog this is the channel name - FREQ freq - POL H/V - [QAM qam] # only needed if DVB-C - [SRATE sr] # only if DVB - [FEC fec] # only if DVB - [PICID picid] # picture attributes for all channels on this transponder - -# channel definition (only if DVB) -CHANNEL - ID channelid - [NAME name] - TPID tpid - TYPE type - PNR pnr - VPID vpid - APID apid - TPID tpid - [PMTPID pmtpid] - [PCRPID pcrpid] - [APID apid2 APID apid3 ... APID apidn] # more audio PIDs for several languages - [AC3PID ac3] - [NETWID networkid] - [BOUQID bouquetid] - [PICID picid] - -# network definition -NETWORK - ID nwid - [NAME name] - -# bouquet definition -BOUQUET - ID bqid - [NAME name] - - - -# These will be implemented later - -# DiSEqC command sequence -DISEQC - ID disid - [NAME name] - MESSAGE data1 [ ... datan ] BURST 0/1 END - [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] - -# DiSEqC switch -SWITCH - ID switchid - SWITCHID switchid # next "higher" switch - [NAME name] - MESSAGE data1 [ ... datan ] BURST 0/1 END - - -# DiSEqC rotor command sequence leading to a certain rotor position -ROTOR - ID rotid - POS degrees - MESSAGE data1 [ ... datan ] BURST 0/1 END - [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] - diff --git a/dvb-spec/dvbapi/.cvsignore b/dvb-spec/dvbapi/.cvsignore deleted file mode 100644 index fb6974f6b..000000000 --- a/dvb-spec/dvbapi/.cvsignore +++ /dev/null @@ -1,11 +0,0 @@ -dvbapi.ps -dvbstb.ps -dvbstb.pst -dvbapi.bbl -dvbapi.aux -dvbapi.blg -dvbapi.dvi -dvbapi.log -dvbapi.pdf -dvbapi.out -dvbapi.toc diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile deleted file mode 100644 index fe9827cff..000000000 --- a/dvb-spec/dvbapi/Makefile +++ /dev/null @@ -1,30 +0,0 @@ -all: dvbapi.ps dvbapi.pdf - -TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex sec.tex frontend.tex \ - intro.tex title.tex dvbstb.ps - -dvbapi.pdf: dvbapi.dvi - dvipdf $< $@ - -dvbapi.ps: dvbapi.dvi - dvips -o $@ $< - -dvbapi.dvi: dvbapi.bbl $(TEXS) - -latex dvbapi - -bibtex dvbapi - -makeindex dvbapi - -latex dvbapi - -latex dvbapi - -dvbapi.bbl: $(TEXS) - -latex dvbapi - -bibtex dvbapi - -makeindex dvbapi - -%.ps: %.fig - ./fig2pstex $< - -clean: - rm -f dvbapi.dvi - rm -f *.aux *.bbl *.blg *.idx *.ilg *.ind *.log *.out *.toc - rm -f *.pdf *.pst *.ps diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex deleted file mode 100644 index e81dd2f89..000000000 --- a/dvb-spec/dvbapi/audio.tex +++ /dev/null @@ -1,442 +0,0 @@ -\devsec{DVB Audio Device} - -The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. -It can be accessed through \texttt{/dev/ost/audio}. - - -\devsubsec{Audio Data Types} - -This section describes the structures, data types and defines used when -talking to the audio device. - -\devsubsubsec{audioStreamSource\_t} -\label{audiostreamsource} -The audio stream source is set through the AUDIO\_SELECT\_SOURCE -call and can take the following values, depending on whether we are -replaying from an internal (demuxer) or external (user write) source. -\begin{verbatim} -typedef enum { - AUDIO_SOURCE_DEMUX, - AUDIO_SOURCE_MEMORY -} audioStreamSource_t; -\end{verbatim} -AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed -either by the frontend or the DVR device) as the source of -the video stream. -If AUDIO\_SOURCE\_MEMORY is selected the stream -comes from the application through the \texttt{write()} -system call. - -\devsubsubsec{audioPlayState\_t} -The following values can be returned by the AUDIO\_GET\_STATUS call -representing the state of audio playback. -\label{audioplaystate} -\begin{verbatim} -typedef enum { - AUDIO_STOPPED, - AUDIO_PLAYING, - AUDIO_PAUSED -} audioPlayState_t; -\end{verbatim} - -\devsubsubsec{audioChannelSelect\_t} -\label{audiochannelselect} -The audio channel selected via AUDIO\_CHANNEL\_SELECT is determined by -the following values. -\begin{verbatim} -typedef enum { - AUDIO_STEREO, - AUDIO_MONO_LEFT, - AUDIO_MONO_RIGHT, -} audioChannelSelect_t; -\end{verbatim} - -\devsubsubsec{audioStatus\_t} -\label{audiostatus} -The AUDIO\_GET\_STATUS call returns the following structure informing -about various states of the playback operation. -\begin{verbatim} -typedef struct audioStatus { - boolean AVSyncState; - boolean muteState; - audioPlayState_t playState; - audioStreamSource_t streamSource; - audioChannelSelect_t channelSelect; - boolean bypassMode; -} audioStatus_t; -\end{verbatim} - -\devsubsubsec{audioMixer\_t} -\label{audiomixer} -The following structure is used by the AUDIO\_SET\_MIXER call to set -the audio volume. -\begin{verbatim} -typedef struct audioMixer { - unsigned int volume_left; - unsigned int volume_right; -} audioMixer_t; -\end{verbatim} - -\devsubsubsec{audio encodings} -\label{audiotypes} -A call to AUDIO\_GET\_CAPABILITIES returns an unsigned integer with -the following bits set according to the hardwares capabilities. -\begin{verbatim} -#define AUDIO_CAP_DTS 1 -#define AUDIO_CAP_LPCM 2 -#define AUDIO_CAP_MP1 4 -#define AUDIO_CAP_MP2 8 -#define AUDIO_CAP_MP3 16 -#define AUDIO_CAP_AAC 32 -#define AUDIO_CAP_OGG 64 -#define AUDIO_CAP_SDDS 128 -#define AUDIO_CAP_AC3 256 -\end{verbatim} - - -\devsubsubsec{audio karaoke} -\label{audiokaraoke} -The ioctl AUDIO\_SET\_KARAOKE uses the following format: -\begin{verbatim} -typedef -struct audioKaraoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ - int vocal1; /* into left and right t at 70% each */ - int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets */ - int melody; /* mixed into the left channel and */ - /* Vocal2 into the right channel at 100% each. */ - /* if Melody is non-zero, the melody channel gets mixed */ /* into left and right */ -} audioKaraoke_t; -\end{verbatim} - -\devsubsubsec{audio attributes} -\label{aattrib} -The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES: -\begin{verbatim} -typedef uint16_t audioAttributes_t; -/* bits: descr. */ -/* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ -/* 12 multichannel extension */ -/* 11-10 audio type (0=not spec, 1=language included) */ -/* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */ -/* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */ -/* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */ -/* 2- 0 number of audio channels (n+1 channels) */ -\end{verbatim} - - -\clearpage - -\devsubsec{Audio Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - 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 error code will be returned. - If the Audio Device is opened in O\_RDONLY mode, the only ioctl call that can - be used is AUDIO\_GET\_STATUS. All other call will return with an error code. - }{ - const char *deviceName & Name of specific audio device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ - & \hspace{1em} (blocking mode is the default)\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EINTERNAL & Internal error.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call closes a previously opened audio device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\function{write()}{ - size\_t write(int fd, const void *buf, size\_t count);}{ - 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. - }{ - 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.\\ - }{ - EPERM& Mode AUDIO\_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.\\ -} - -\ifunction{AUDIO\_STOP}{ - int ioctl(int fd, int request = AUDIO\_STOP);}{ - This ioctl call asks the Audio Device to stop playing the current stream. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request& Equals AUDIO\_STOP for this command. - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error. -} - -\ifunction{AUDIO\_PLAY}{ - int ioctl(int fd, int request = AUDIO\_PLAY);}{ - This ioctl call asks the Audio Device to start playing an audio stream - from the selected source. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request& Equals AUDIO\_PLAY for this command. - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error. -} - -\ifunction{AUDIO\_PAUSE}{ - int ioctl(int fd, int request = AUDIO\_PAUSE);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request& Equals AUDIO\_PAUSE for this command. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error. -} - -\ifunction{AUDIO\_SELECT\_SOURCE}{ - int ioctl(int fd, int request = AUDIO\_SELECT\_SOURCE, - audioStreamSource\_t source);}{ - 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. - }{ - 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. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Illegal input parameter. -} - -\ifunction{AUDIO\_SET\_MUTE}{ - int ioctl(int fd, int request = AUDIO\_SET\_MUTE, boolean state);}{ - This ioctl call asks the audio device to mute the stream that is - currently being played. - }{ - 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 Un-mute\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Illegal input parameter. -} - -\ifunction{AUDIO\_SET\_AV\_SYNC}{ - int ioctl(int fd, int request = AUDIO\_SET\_AV\_SYNC, boolean state);}{ - This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization. - }{ - 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 - synchronization shall be ON or OFF.\\ - & TRUE AV-sync ON \\ - & FALSE AV-sync OFF\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Illegal input parameter. -} - -\ifunction{AUDIO\_SET\_BYPASS\_MODE}{ - int ioctl(int fd, int request = AUDIO\_SET\_BYPASS\_MODE, boolean mode);}{ - This ioctl call asks the Audio Device to bypass the Audio decoder and forward - the stream without decoding. This mode shall be used if streams that can't be - handled by the DVB system shall be decoded. - Dolby DigitalTM streams are automatically forwarded by the DVB - subsystem if the hardware can handle it. - }{ - 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\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Illegal input parameter. -} - -\ifunction{AUDIO\_CHANNEL\_SELECT}{ - int ioctl(int fd, int request = AUDIO\_CHANNEL\_SELECT, - audioChannelSelect\_t);}{ - This ioctl call asks the Audio Device to select the requested channel - if possible. - }{ - 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 left/right, stereo). - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Illegal input parameter ch. -} - -\ifunction{AUDIO\_GET\_STATUS}{ - int ioctl(int fd, int request = AUDIO\_GET\_STATUS, - struct audioStatus *status);}{ - This ioctl call asks the Audio Device to return the current state - of the Audio Device. - }{ - 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. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EFAULT & status points to invalid address. -} - -\ifunction{AUDIO\_GET\_CAPABILITIES}{ - int ioctl(int fd, int request = AUDIO\_GET\_CAPABILITIES, - unsigned int *cap);}{ - This ioctl call asks the Audio Device to tell us about the - decoding capabilities of the audio hardware. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_GET\_CAPABILITIES for this command.\\ - unsigned int *cap & Returns a bit array of supported sound formats. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EFAULT & cap points to an invalid address. -} - -\ifunction{AUDIO\_CLEAR\_BUFFER}{ - int ioctl(int fd, int request = AUDIO\_CLEAR\_BUFFER);}{ - This ioctl call asks the Audio Device to clear all software - and hardware buffers of the audio decoder device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_CLEAR\_BUFFER for this command. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error. -} - -\ifunction{AUDIO\_SET\_ID}{ - int ioctl(int fd, int request = AUDIO\_SET\_ID, int id);}{ - This ioctl selects which sub-stream is to be decoded if a program or - system stream is sent to the video device. If no audio stream type is set - the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for - AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow - for other stream types. If the stream type is set the id just - specifies the substream id of the audio stream and only the first 5 - bits are recognized. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_SET\_ID for this command.\\ - int id& audio sub-stream id - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Invalid sub-stream id. -} - -\ifunction{AUDIO\_SET\_MIXER}{ - int ioctl(int fd, int request = AUDIO\_SET\_MIXER, audioMixer\_t *mix);}{ - This ioctl lets you adjust the mixer settings of the audio decoder. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_SET\_ID for this command.\\ - audioMixer\_t *mix& mixer settings. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EFAULT & mix points to an invalid address. -} - -\ifunction{AUDIO\_SET\_STREAMTYPE}{ - int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, int type);}{ - This ioctl tells the driver which kind of audio stream to expect. - This is useful if the stream offers several audio sub-streams - like LPCM and AC3. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ - int type & stream type\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& type is not a valid or supported stream type.\\ -} - - -\ifunction{AUDIO\_SET\_EXT\_ID}{ - int ioctl(fd, int request = AUDIO\_SET\_EXT\_ID, int id);}{ - This ioctl can be used to set the extension id for MPEG streams in - DVD playback. Only the first 3 bits are recognized. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_SET\_EXT\_ID for this command.\\ - int id & audio sub\_stream\_id\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& id is not a valid id.\\ -} - -\ifunction{AUDIO\_SET\_ATTRIBUTES}{ - int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audioAttributes\_t attr );}{ - This ioctl is intended for DVD playback and allows you to set - certain information about the audio stream. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_SET\_ATTRIBUTES for this command.\\ - iaudioAttributes\_t attr & audio attributes according to section \ref{aattrib}\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& attr is not a valid or supported attribute setting.\\ -} - -\ifunction{AUDIO\_SET\_KARAOKE}{ - int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, audioKaraoke\_t *karaoke);}{ - This ioctl allows one to set the mixer settings for a karaoke DVD. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ - audioKaraoke\_t *karaoke & karaoke settings according to section \ref{audiokaraoke}.\\ - }{ - EBADF & fd is not a valid open file descriptor \\ - EINVAL& karaoke is not a valid or supported karaoke setting.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/bibsection.sty b/dvb-spec/dvbapi/bibsection.sty deleted file mode 100644 index 7f9eedc6a..000000000 --- a/dvb-spec/dvbapi/bibsection.sty +++ /dev/null @@ -1,29 +0,0 @@ -\def\thebibliography#1{\chapter*{\bibname\@mkboth - {\uppercase{\bibname}}{\uppercase{\bibname}}} - \setcounter{chapter}{0} - \setcounter{section}{0} - \def\thechapter{Bib} - \def\thesection{\Alph{section}} - \edef\biblab{#1} - \addcontentsline{toc}{chapter}{\bibname} - } - -\def\bibtitle#1#2{\expandafter\def\csname bibtitle#1\endcsname{ - \bibsection{#2}} } - -\def\bibsection#1{\section{#1} - \begin{list} - {\@biblabel{\arabic{enumiv}}}{\settowidth\labelwidth{\@biblabel{\biblab}}% - \leftmargin\labelwidth - \advance\leftmargin\labelsep - \usecounter{enumiv}% - \let\p@enumiv\@empty - \def\theenumiv{\arabic{enumiv}}}% - \def\newblock{\hskip .11em plus.33em minus.07em}% - \sloppy\clubpenalty4000\widowpenalty4000 - \sfcode`\.=\@m} - -\def\endbibsection{\end{list}} - -\def\endthebibliography{\endbibsection} - diff --git a/dvb-spec/dvbapi/ca.tex b/dvb-spec/dvbapi/ca.tex deleted file mode 100644 index eba512b1b..000000000 --- a/dvb-spec/dvbapi/ca.tex +++ /dev/null @@ -1,127 +0,0 @@ -\devsec{DVB CA Device} - -The DVB CA device controls the conditional access hardware. -It can be accessed through \texttt{/dev/ost/ca}. - - -\devsubsec{CA Data Types} - -\devsubsubsec{ca\_slot\_info\_t} -\label{caslotinfo} - -\begin{verbatim} -/* slot interface types and info */ - -typedef struct ca_slot_info_s { - int num; /* slot number */ - - int type; /* CA interface this slot supports */ -#define CA_CI 1 /* CI high level interface */ -#define CA_CI_LINK 2 /* CI link layer level interface */ -#define CA_CI_PHYS 4 /* CI physical layer level interface */ -#define CA_SC 128 /* simple smart card interface */ - - unsigned int flags; -#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ -#define CA_CI_MODULE_READY 2 -} ca_slot_info_t; -\end{verbatim} - -\devsubsubsec{ca\_descr\_info\_t} -\label{cadescrinfo} - -\begin{verbatim} -typedef struct ca_descr_info_s { - unsigned int num; /* number of available descramblers (keys) */ - unsigned int type; /* type of supported scrambling system */ -#define CA_ECD 1 -#define CA_NDS 2 -#define CA_DSS 4 -} ca_descr_info_t; -\end{verbatim} - -\devsubsubsec{ca\_cap\_t} -\label{cacap} - -\begin{verbatim} -typedef struct ca_cap_s { - unsigned int slot_num; /* total number of CA card and module slots */ - unsigned int slot_type; /* OR of all supported types */ - unsigned int descr_num; /* total number of descrambler slots (keys) */ - unsigned int descr_type;/* OR of all supported types */ -} ca_cap_t; -\end{verbatim} - - -\devsubsubsec{ca\_msg\_t} -\label{camsg} - -\begin{verbatim} -/* a message to/from a CI-CAM */ -typedef struct ca_msg_s { - unsigned int index; - unsigned int type; - unsigned int length; - unsigned char msg[256]; -} ca_msg_t; -\end{verbatim} - - -\devsubsubsec{ca\_descr\_t} -\label{cadescr} - -\begin{verbatim} -typedef struct ca_descr_s { - unsigned int index; - unsigned int parity; - unsigned char cw[8]; -} ca_descr_t; -\end{verbatim} - -\clearpage - -\devsubsec{CA Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - This system call opens a named ca device (e.g. /dev/ost/ca) - 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 CA Device in O\_RDWR mode. All other attempts to - open the device in this mode will fail, and an error code will be returned. - }{ - const char *deviceName & Name of specific video device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ - & \hspace{1em} (blocking mode is the default)\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EINTERNAL & Internal error.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call closes a previously opened audio device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/cimlogo.psi b/dvb-spec/dvbapi/cimlogo.psi deleted file mode 100644 index b7b089a49..000000000 --- a/dvb-spec/dvbapi/cimlogo.psi +++ /dev/null @@ -1,122 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: /home/rjkm/dvbapi/cimlogo.ps -%%Creator: XV Version 3.10a Rev: 12/29/94 (PNG patch 1.2) - by John Bradley -%%BoundingBox: 275 411 309 440 -%%Pages: 1 -%%DocumentFonts: -%%EndComments -%%EndProlog - -%%Page: 1 1 - -% remember original state -/origstate save def - -% build a temporary dictionary -20 dict begin - -% define string to hold a scanline's worth of data -/pix 45 string def - -% define space for color conversions -/grays 45 string def % space for gray scale line -/npixls 0 def -/rgbindx 0 def - -% lower left corner -275 411 translate - -% size of image (on paper, in 1/72inch coords) -33.76800 28.51200 scale - -45 38 8 % dimensions of data -[45 0 0 -38 0 38] % mapping matrix -{currentfile pix readhexstring pop} -image - -ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffffffffffffffffffffffffff000000ffffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffffffffffffffffffffffff0000000000ffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffffffffffffffffffffffff000000000000ffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffffffffff00ffffffffffff0000000000ffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffff0000000000ffffffff000000000000ffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffff0000000000000000ffffff000000000000ffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffff0000000000000000ffffffff000000000000ffffffffffffffffffff -ffffffffffffffffff -ffffffffffffff000000000000000000ffffff000000000000ffffffffffffffffffffff -ffffffffffffffffff -ffffffffffff0000000000000000ffffffffff000000000000ffffff00000000ffffffff -ffffffffffffffffff -ffffffffff00000000000000ffffffffffffff0000000000ffffff0000000000ffffffff -ffffffffffffffffff -ffffffffff000000000000ffffffffffffff000000000000ffffff000000000000ffffff -ffffffffffffffffff -ffffffff00000000000000ffffffffffffff000000000000ffffffff000000000000ffff -ffffffffffffffffff -ffffffff000000000000ffffffffffffffff000000000000ffffffff000000000000ffff -ffffffffffffffffff -ffffffff0000000000ffffffffffffffff000000000000ffffffffffff0000000000ffff -ffffffffffffffffff -ffffff000000000000ffffffffffffffff000000000000ffffffffffff0000000000ffff -ffffffffffffffffff -ffffff0000000000ffffffffffffffffff000000000000ffffffffffff000000000000ff -ffffffffffffffffff -ffffff0000000000ffffffffffffffffff0000000000ffffffffffffff000000000000ff -ffffffffffffffffff -ffffff0000000000ffffffffffffffff000000000000ffffffffffffffff0000000000ff -ffffffffffffffffff -ffffff0000000000ffffffffffffffff000000000000ffffffffffffff000000000000ff -ffffffffffffffffff -ffffff0000000000ffffffffffffffff0000000000ffffffffffffffffff0000000000ff -ffffffffffffffffff -ffffff0000000000ffffffffffffff000000000000ffffffffffffffff000000000000ff -ffffffffffffffffff -ffffff0000000000ffffffffffffff000000000000ffffffffffffffff0000000000ffff -ffffffffffffffffff -ffffff000000000000ffffffffffffff00000000ffffffffffffffffff0000000000ffff -ffffffffffffffffff -ffffffff0000000000ffffffffffffffff0000ffffffffffffffffff000000000000ffff -ffffffffffffffffff -ffffffff000000000000ffffffffffffffffffffffffffffffffffff000000000000ffff -ffffffffffffffffff -ffffffff000000000000ffffffffffffffffffffffffffffffffff000000000000ffffff -ffffffffffffffffff -ffffffffff00000000000000ffffffffffffffffffffffffffff000000000000ffffffff -ff0000000000ffffff -ffffffffff0000000000000000ffffffffffffffffffffffff00000000000000ffffffff -00000000000000ffff -ffffffffffff000000000000000000ffffffffffffffff0000000000000000ffffffffff -00000000000000ffff -ffffffffffffff0000000000000000000000000000000000000000000000ffffffffffff -0000000000000000ff -ffffffffffffffff000000000000000000000000000000000000000000ffffffffffffff -00000000000000ffff -ffffffffffffffffffff0000000000000000000000000000000000ffffffffffffffffff -00000000000000ffff -ffffffffffffffffffffffff00000000000000000000000000ffffffffffffffffffffff -ff0000000000ffffff -ffffffffffffffffffffffffffffff00ff0000000000ffffffffffffffffffffffffffff -ffffff0000ffffffff -ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -ffffffffffffffffff -ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -ffffffffffffffffff - -showpage - -% stop using temporary dictionary -end - -% restore original state -origstate restore - -%%Trailer diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex deleted file mode 100644 index 541ee633a..000000000 --- a/dvb-spec/dvbapi/demux.tex +++ /dev/null @@ -1,392 +0,0 @@ -\devsec{DVB Demux Device} - -The DVB demux device controls the filters of the DVB hardware/software. -It can be accessed through \texttt{/dev/ost/demux}. - -\devsubsec{Demux Data Types} - -\begin{verbatim} -typedef uint16_t dvb_pid_t; -\end{verbatim} - - -\devsubsubsec{dmxOutput\_t} -\label{dmxoutput} - -\begin{verbatim} -typedef enum -{ - DMX_OUT_DECODER, - DMX_OUT_TAP, - DMX_OUT_TS_TAP -} dmxOutput_t; -\end{verbatim} -/* Output multiplexed into a new TS */ -/* (to be retrieved by reading from the */ -/* logical DVR device). */ - - -\devsubsubsec{dmxInput\_t} -\label{dmxinput} - -\begin{verbatim} -typedef enum -{ - DMX_IN_FRONTEND, /* Input from a front-end device. */ - DMX_IN_DVR /* Input from the logical DVR device. */ -} dmxInput_t; -\end{verbatim} - - -\devsubsubsec{dmxPesType\_t} -\label{dmxpestype} - -\begin{verbatim} -typedef enum -{ - DMX_PES_AUDIO, - DMX_PES_VIDEO, - DMX_PES_TELETEXT, - DMX_PES_SUBTITLE, - DMX_PES_PCR, - DMX_PES_OTHER -} dmxPesType_t; -\end{verbatim} - - -\devsubsubsec{dmxEvent\_t} -\label{dmxeventt} - -\begin{verbatim} -typedef enum -{ - DMX_SCRAMBLING_EV, - DMX_FRONTEND_EV -} dmxEvent_t; -\end{verbatim} - - -\devsubsubsec{dmxScramblingStatus\_t} -\label{dmxscramblingstatus} - -\begin{verbatim} -typedef enum -{ - DMX_SCRAMBLING_OFF, - DMX_SCRAMBLING_ON -} dmxScramblingStatus_t; -\end{verbatim} - - -\devsubsubsec{dmxFilter\_t} -\label{dmxfilter} - -\begin{verbatim} -typedef struct dmxFilter -{ - uint8_t filter[DMX_FILTER_SIZE]; - uint8_t mask[DMX_FILTER_SIZE]; -} dmxFilter_t; -\end{verbatim} - - -\devsubsubsec{dmxSctFilterParams} -\label{dmxsctfilterparams} - -\begin{verbatim} -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 -}; -\end{verbatim} - - -\devsubsubsec{dmxPesFilterParams} -\label{dmxpesfilterparams} - -\begin{verbatim} -struct dmxPesFilterParams -{ - dvb_pid_t pid; - dmxInput_t input; - dmxOutput_t output; - dmxPesType_t pesType; - uint32_t flags; -}; -\end{verbatim} - - -\devsubsubsec{dmxEvent} -\label{dmxevent} - -\begin{verbatim} -struct dmxEvent -{ - dmxEvent_t event; - time_t timeStamp; - union - { - dmxScramblingStatus_t scrambling; - } u; -}; -\end{verbatim} - -\clearpage - -\devsubsec{Demux Function Calls} -\function{open()}{ - int open(const char *deviceName, int flags);}{ - 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 functionality. When reading from - this device a transport stream containing the packets from all PES - filters set in the corresponding demux device (/dev/ost/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. - }{ - const char *deviceName & Name of demux device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDWR read/write access\\ - & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ - & \hspace{1em} (blocking mode is the default)\\ - }{ - 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.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call deactivates and deallocates a filter that was previously - allocated via the open() call. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\function{read()}{ - size\_t read(int fd, void *buf, size\_t count); - }{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - void *buf & Pointer to the buffer to be used for returned filtered data.\\ - size\_t count & Size of buf.\\ - }{ - 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.\\ -} - -\function{write()}{ - ssize\_t write(int fd, const void *buf, size\_t count); - }{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - void *buf & Pointer to the buffer containing the Transport Stream.\\ - size\_t count & Size of buf.\\ - }{ - 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.\\ -} - -\ifunction{DMX\_START}{ - int ioctl( int fd, int request = DMX\_START); - }{ - This ioctl call is used to start the actual filtering operation - defined via the ioctl calls DMX\_SET\_FILTER or DMX\_SET\_PES\_FILTER. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals DMX\_START for this command.\\ - }{ - 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.\\ -} - -\ifunction{DMX\_STOP}{ - int ioctl( int fd, int request = DMX\_STOP); - }{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals DMX\_STOP for this command.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ -} - -\ifunction{DMX\_SET\_FILTER}{ - int ioctl( int fd, int request = DMX\_SET\_FILTER, struct dmxSctFilterParams *params); - }{ - This ioctl call sets up a filter according to the filter and mask - parameters provided. A timeout may be defined stating number of seconds - to wait for a section to be loaded. A value of 0 means that no timeout - should be applied. Finally there is a flag field where it is possible to - state whether a section should be CRC-checked, whether the filter should - be a "one-shot" filter, i.e. if the filtering operation should be stopped - after the first section is received, and whether the filtering operation - should be started immediately (without waiting for a DMX\_START ioctl call). - If a filter was previously set-up, this filter will be canceled, and the - receive buffer will be flushed. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals DMX\_SET\_FILTER for this command.\\ - struct dmxSctFilterParams *params - & Pointer to structure containing filter parameters.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EINVAL & Invalid argument.\\ -} - -\ifunction{DMX\_SET\_PES\_FILTER}{ - int ioctl( int fd, int request = DMX\_SET\_PES\_FILTER, - struct dmxPesFilterParams *params); - }{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals DMX\_SET\_PES\_FILTER for this command.\\ - struct dmxPesFilterParams *params - & Pointer to structure containing filter parameters.\\ - }{ - 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.\\ -} - -\ifunction{DMX\_SET\_BUFFER\_SIZE}{ - int ioctl( int fd, int request = DMX\_SET\_BUFFER\_SIZE, unsigned long size); - }{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals DMX\_SET\_BUFFER\_SIZE for this command.\\ - unsigned long size & Size of circular buffer.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - ENOMEM & The driver was not able to allocate a buffer of the requested size.\\ -} - -\ifunction{DMX\_GET\_EVENT}{ - int ioctl( int fd, int request = DMX\_GET\_EVENT, struct dmxEvent *ev); - }{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals DMX\_GET\_EVENT for this command.\\ - struct dmxEvent *ev & Pointer to the location where the event is to be stored.\\ - }{ - 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.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/devices.tex b/dvb-spec/dvbapi/devices.tex deleted file mode 100644 index 9c561e853..000000000 --- a/dvb-spec/dvbapi/devices.tex +++ /dev/null @@ -1,12 +0,0 @@ -\input{video.tex} -\input{audio.tex} -\input{frontend.tex} -\input{sec.tex} -\input{demux.tex} -\input{ca.tex} -\input{kdapi.tex} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex deleted file mode 100644 index ad0251c01..000000000 --- a/dvb-spec/dvbapi/dvbapi.tex +++ /dev/null @@ -1,166 +0,0 @@ -\documentclass[10pt]{book} -\usepackage[dvips,colorlinks=true]{hyperref} - -\usepackage{times} - -%\usepackage[hang]{caption} -\usepackage{fancyheadings} -%\usepackage{lucidabr} -%\usepackage{fancybox} -\usepackage{array} -\usepackage{graphicx} -%\usepackage{latexsym} -%\usepackage{pstricks,pst-node,pst-tree} -%\usepackage{verbatim} -%\usepackage{rotating} -%\usepackage{pdftex} -%\usepackage{color} -%\usepackage{subfigure} -%\usepackage{wrapfig} - -\newcommand{\devsec}[1]{\chapter{#1}} -\newcommand{\devsubsec}[1]{\section{#1}} -\newcommand{\devsubsubsec}[1]{\subsection{#1}} -\newcommand{\function}[5]{ - \subsection{#1} - - \noindent DESCRIPTION - \medskip - - \begin{tabular}[h]{p{11cm}} - #3 - \end{tabular} - - \medskip - \noindent SYNOPSIS - \medskip - - \begin{tabular}[h]{p{11cm}} - {\tt #2} - \end{tabular} - - %\item[] -\medskip -\noindent PARAMETERS -\medskip - - \begin{tabular}[h]{p{3cm}p{8cm}} - #4 - \end{tabular} - - %\item[] -\medskip -\noindent ERRORS -\medskip - - \begin{tabular}[h]{p{3cm}p{8cm}} - #5 - \end{tabular} - - %\end{itemize} - -\medskip -} -\def\ifunction#1#2#3#4#5{\function{#1\index{#1}}{#2}{#3}{#4}{#5}} - -\newcommand{\kfunction}[5]{ - \subsection{#1} - \noindent DESCRIPTION - \medskip - - \begin{tabular}[h]{p{11cm}} - #3 - \end{tabular} - - \medskip - \noindent SYNOPSIS - \medskip - - \begin{tabular}[h]{p{11cm}} - {\tt #2} - \end{tabular} - - %\item[] -\medskip -\noindent PARAMETERS -\medskip - - \begin{tabular}[h]{p{3cm}p{8cm}} - #4 - \end{tabular} - - %\item[] -\medskip -\noindent RETURNS -\medskip - - \begin{tabular}[h]{p{3cm}p{8cm}} - #5 - \end{tabular} - - %\end{itemize} - -\medskip -} -\def\kifunction#1#2#3#4#5{\kfunction{#1\index{#1}}{#2}{#3}{#4}{#5}} - - -%\usepackage{index} -%\makeindex - - -\begin{document} - -\input{title.tex} - -\cleardoublepage - -\pagenumbering{roman} -\pagestyle{fancyplain} - - -\tableofcontents -%\listoffigures -%\listoftables - -\cleardoublepage - -\pagenumbering{arabic} - -\renewcommand{\chaptermark}[1]{\markboth{\uppercase{#1}}{}} -\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} -\lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} -\rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} -\cfoot{\copyright 2002 convergence GmbH} - -\input{intro.tex} - -\input{devices.tex} - -\input{examples.tex} - -\cleardoublepage - -\appendix - -\cleardoublepage - -\thispagestyle{plain}\chaptermark{Bibliography} -\addcontentsline{toc}{chapter}{Bibliography} -\bibliographystyle{bibsec} -\bibliography{main} - -\cleardoublepage - -\thispagestyle{plain}\chaptermark{Subject Index} -\addcontentsline{toc}{chapter}{Subject Index} -%\printindex - -\cleardoublepage - -\end{document} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: t -%%% End: diff --git a/dvb-spec/dvbapi/dvbstb.fig b/dvb-spec/dvbapi/dvbstb.fig deleted file mode 100644 index 0a6bbadc3..000000000 --- a/dvb-spec/dvbapi/dvbstb.fig +++ /dev/null @@ -1,59 +0,0 @@ -#FIG 3.2 -Landscape -Center -Metric -A4 -100.00 -Single --2 -1200 2 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1620 360 2520 360 2520 900 1620 900 1620 360 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 1260 1080 1620 630 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 2520 630 2880 630 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2880 360 3780 360 3780 900 2880 900 2880 360 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 4590 900 3330 1170 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 4590 900 4590 1170 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4140 360 5040 360 5040 900 4140 900 4140 360 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3780 630 4140 630 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 4140 1170 5040 1170 5040 1710 4140 1710 4140 1170 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 2880 1170 3780 1170 3780 1710 2880 1710 2880 1170 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1620 1170 2520 1170 2520 1710 1620 1710 1620 1170 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 0 0 1.00 60.00 120.00 - 1620 1440 1260 1080 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 1350 225 5175 225 5175 1845 1350 1845 1350 225 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 3240 1710 3960 2070 -2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 - 1 1 1.00 60.00 120.00 - 4590 1710 3960 2070 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 3510 2070 4410 2070 4410 2610 3510 2610 3510 2070 -2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 - 360 810 1260 810 1260 1350 360 1350 360 810 -4 0 0 50 0 0 12 0.0000 4 135 675 1755 675 Frontend\001 -4 0 0 50 0 0 12 0.0000 4 135 690 4275 675 Demuxer\001 -4 0 0 50 0 0 12 0.0000 4 135 450 4365 1485 Video\001 -4 0 0 50 0 0 12 0.0000 4 135 450 3105 1485 Audio\001 -4 0 0 50 0 0 12 0.0000 4 135 345 1890 1485 SEC\001 -4 0 0 50 0 0 12 0.0000 4 135 255 3195 675 CA\001 -4 0 0 50 0 0 12 0.0000 4 135 645 495 1125 Antenna\001 -4 0 0 50 0 0 12 0.0000 4 135 240 3870 2385 TV\001 diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex deleted file mode 100644 index 114579b80..000000000 --- a/dvb-spec/dvbapi/examples.tex +++ /dev/null @@ -1,366 +0,0 @@ -\chapter{Examples} -In this section we would like to present some examples for using the DVB API. - -\section{Tuning} -We will start with a generic tuning subroutine that uses the frontend -and SEC, as well as the demux devices. The example is given for QPSK -tuners, but can easily be adjusted for QAM. - -{\small -\begin{verbatim} -#include -#include -#include -#include -#include -#include -#include -#include - -#include -#include -#include -#include - -#define DMX "/dev/ost/demux" -#define FRONT "/dev/ost/frontend" -#define SEC "/dev/ost/sec" - -/* routine for checking if we have a signal and other status information*/ -int FEReadStatus(int fd, FrontendStatus *stat) -{ - int ans; - - if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ - perror("FE READ STATUS: "); - return -1; - } - - if (*stat & FE_HAS_POWER) - printf("FE HAS POWER\n"); - - if (*stat & FE_HAS_SIGNAL) - printf("FE HAS SIGNAL\n"); - - if (*stat & FE_SPECTRUM_INV) - printf("SPEKTRUM INV\n"); - - return 0; -} - - -/* tune qpsk */ -/* freq: frequency of transponder */ -/* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */ -/* diseqc: DiSEqC address of the used LNB */ -/* pol: Polarisation */ -/* srate: Symbol Rate */ -/* fec. FEC */ -/* lnb_lof1: local frequency of lower LNB band */ -/* lnb_lof2: local frequency of upper LNB band */ -/* lnb_slof: switch frequency of LNB */ - -int set_qpsk_channel(int freq, int vpid, int apid, int tpid, - int diseqc, int pol, int srate, int fec, int lnb_lof1, - int lnb_lof2, int lnb_slof) -{ - struct secCommand scmd; - struct secCmdSequence scmds; - struct dmxPesFilterParams pesFilterParams; - FrontendParameters frp; - struct pollfd pfd[1]; - FrontendEvent event; - int demux1, dmeux2, demux3, front, - - frequency = (uint32_t) freq; - symbolrate = (uint32_t) srate; - - if((front = open(FRONT,O_RDWR)) < 0){ - perror("FRONTEND DEVICE: "); - return -1; - } - - if((sec = open(SEC,O_RDWR)) < 0){ - perror("SEC DEVICE: "); - return -1; - } - - if (demux1 < 0){ - if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux2 < 0){ - if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux3 < 0){ - if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (freq < lnb_slof) { - frp.Frequency = (freq - lnb_lof1); - scmds.continuousTone = SEC_TONE_OFF; - } else { - frp.Frequency = (freq - lnb_lof2); - scmds.continuousTone = SEC_TONE_ON; - } - frp.Inversion = INVERSION_AUTO; - if (pol) scmds.voltage = SEC_VOLTAGE_18; - else scmds.voltage = SEC_VOLTAGE_13; - - scmd.type=0; - scmd.u.diseqc.addr=0x10; - scmd.u.diseqc.cmd=0x38; - scmd.u.diseqc.numParams=1; - scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) | - (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | - (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); - - scmds.miniCommand=SEC_MINI_NONE; - scmds.numCommands=1; - scmds.commands=&scmd; - if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ - perror("SEC SEND: "); - return -1; - } - - if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ - perror("SEC SEND: "); - return -1; - } - - frp.u.qpsk.SymbolRate = srate; - frp.u.qpsk.FEC_inner = fec; - - if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ - perror("QPSK TUNE: "); - return -1; - } - - pfd[0].fd = front; - pfd[0].events = POLLIN; - - if (poll(pfd,1,3000)){ - if (pfd[0].revents & POLLIN){ - printf("Getting QPSK event\n"); - if ( ioctl(front, FE_GET_EVENT, &event) - - == -EBUFFEROVERFLOW){ - perror("qpsk get event"); - return -1; - } - printf("Received "); - switch(event.type){ - case FE_UNEXPECTED_EV: - printf("unexpected event\n"); - return -1; - case FE_FAILURE_EV: - printf("failure event\n"); - return -1; - - case FE_COMPLETION_EV: - printf("completion event\n"); - } - } - } - - - pesFilterParams.pid = vpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pesType = DMX_PES_VIDEO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_vpid"); - return -1; - } - - pesFilterParams.pid = apid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pesType = DMX_PES_AUDIO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_apid"); - return -1; - } - - pesFilterParams.pid = tpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pesType = DMX_PES_TELETEXT; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("set_tpid"); - return -1; - } - - return has_signal(fds); -} - -\end{verbatim} -} -The program assumes that you are using a universal LNB and a standard -DiSEqC switch with up to 4 addresses. Of course, you could build in -some more checking if tuning was successful and maybe try to repeat -the tuning process. Depending on the external hardware, i.e. LNB and -DiSEqC switch, and weather conditions this may be necessary. - - -\section{The DVR device} -The following program code shows how to use the DVR device for -recording. - -{\small -\begin{verbatim} -#include -#include -#include -#include -#include -#include -#include -#include - -#include -#include -#include -#define DVR "/dev/ost/dvr" -#define AUDIO "/dev/ost/audio" -#define VIDEO "/dev/ost/video" - -#define BUFFY (188*20) -#define MAX_LENGTH (1024*1024*5) /* record 5MB */ - - -/* switch the demuxes to recording, assuming the transponder is tuned */ - -/* demux1, demux2: file descriptor of video and audio filters */ -/* vpid, apid: PIDs of video and audio channels */ - -int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) -{ - struct dmxPesFilterParams pesFilterParams; - - if (demux1 < 0){ - if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - if (demux2 < 0){ - if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) - < 0){ - perror("DEMUX DEVICE: "); - return -1; - } - } - - pesFilterParams.pid = vpid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pesType = DMX_PES_VIDEO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("DEMUX DEVICE"); - return -1; - } - pesFilterParams.pid = apid; - pesFilterParams.input = DMX_IN_FRONTEND; - pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pesType = DMX_PES_AUDIO; - pesFilterParams.flags = DMX_IMMEDIATE_START; - if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ - perror("DEMUX DEVICE"); - return -1; - } - return 0; -} - -/* start recording MAX_LENGTH , assuming the transponder is tuned */ - -/* demux1, demux2: file descriptor of video and audio filters */ -/* vpid, apid: PIDs of video and audio channels */ -int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) -{ - int i; - int len; - int written; - uint8_t buf[BUFFY]; - uint64_t length; - struct pollfd pfd[1]; - int dvr, dvr_out; - - /* open dvr device */ - if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ - perror("DVR DEVICE"); - return -1; - } - - /* switch video and audio demuxes to dvr */ - printf ("Switching dvr on\n"); - i = switch_to_record(demux1, demux2, vpid, apid); - printf("finished: "); - - printf("Recording %2.0f MB of test file in TS format\n", - MAX_LENGTH/(1024.0*1024.0)); - length = 0; - - /* open output file */ - if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT - |O_TRUNC, S_IRUSR|S_IWUSR - |S_IRGRP|S_IWGRP|S_IROTH| - S_IWOTH)) < 0){ - perror("Can't open file for dvr test"); - return -1; - } - - pfd[0].fd = dvr; - pfd[0].events = POLLIN; - - /* poll for dvr data and write to file */ - while (length < MAX_LENGTH ) { - if (poll(pfd,1,1)){ - if (pfd[0].revents & POLLIN){ - len = read(dvr, buf, BUFFY); - if (len < 0){ - perror("recording"); - return -1; - } - if (len > 0){ - written = 0; - while (written < len) - written += - write (dvr_out, - buf, len); - length += len; - printf("written %2.0f MB\r", - length/1024./1024.); - } - } - } - } - return 0; -} - -\end{verbatim} -} -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% TeX-master: t -%%% End: diff --git a/dvb-spec/dvbapi/fig2pstex b/dvb-spec/dvbapi/fig2pstex deleted file mode 100755 index bf62eb7ec..000000000 --- a/dvb-spec/dvbapi/fig2pstex +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/sh -f=`basename $1 .fig` -fig2dev -L pstex $f.fig $f.ps -fig2dev -L pstex_t -p $f.ps $f.fig $f.pst2 -./getbb $f.pst2 $f.ps > $f.pst -rm $f.pst2 \ No newline at end of file diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex deleted file mode 100644 index ceb2f93db..000000000 --- a/dvb-spec/dvbapi/frontend.tex +++ /dev/null @@ -1,630 +0,0 @@ -\devsec{DVB Frontend API} - -The DVB frontend device controls the tuner and DVB demodulator hardware. -It can be accessed through \texttt{/dev/ost/frontend}. -If you are using \texttt{devfs} you can use \texttt{/dev/dvb/card0/frontend}. -The frontend device will only be made visible through \texttt{devfs} -if the corresponding card actually has a frontend. Cards which support -the DVB API but, e.g., only can play back recordings, will not offer the -frontend device. - -\devsubsec{Frontend Data Types} - -\devsubsubsec{frontend status} -\label{frontendstatus} - -Several functions of the frontend device use the feStatus data -type defined by -\begin{verbatim} -typedef uint32_t feStatus; -\end{verbatim} -to indicate the current state and/or state changes of -the frontend hardware. - -\noindent -It can take on the values -\begin{verbatim} -#define FE_HAS_POWER 1 -#define FE_HAS_SIGNAL 2 -#define FE_SPECTRUM_INV 4 -#define FE_HAS_LOCK 8 -#define FE_HAS_CARRIER 16 -#define FE_HAS_VITERBI 32 -#define FE_HAS_SYNC 64 -#define TUNER_HAS_LOCK 128 -\end{verbatim} -which can be ORed together and have the following meaning: - -\medskip - -\begin{tabular}{lp{11cm}} -FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ -FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ -FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ -FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ -FE\_HAS\_CARRIER & carrier detected in signal\\ -FE\_HAS\_VITERBI & lock at viterbi decoder stage\\ -FE\_HAS\_SYNC & TS sync bytes detected \\ -TUNER\_HAS\_LOCK & the tuner has a frequency lock -\end{tabular} - - -\devsubsubsec{frontend parameters} -\label{frontendparameters} - -The kind of parameters passed to the frontend device for tuning -depend on the kind of hardware you are using. -All kinds of parameters are combined as a union in the -FrontendParameters structure: -\begin{verbatim} -typedef struct { - __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ - /* intermediate frequency in kHz for QPSK */ - SpectralInversion Inversion; /* spectral inversion */ - union { - QPSKParameters qpsk; - QAMParameters qam; - OFDMParameters ofdm; - } u; -} FrontendParameters; -\end{verbatim} - -For satellite QPSK frontends you have to use QPSKParameters defined by -\begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - CodeRate FEC_inner; /* forward error correction (see above) */ -} QPSKParameters; -\end{verbatim} -for cable QAM frontend you use the QAMParameters structure -\begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - CodeRate FEC_outer; /* forward error correction (see above) */ - CodeRate FEC_inner; /* forward error correction (see above) */ - Modulation QAM; /* modulation type (see above) */ -} QAMParameters; -\end{verbatim} -DVB-T frontends are supported by the OFDMParamters structure -\begin{verbatim} -typedef struct { - BandWidth bandWidth; - CodeRate HP_CodeRate; /* high priority stream code rate */ - CodeRate LP_CodeRate; /* low priority stream code rate */ - Modulation Constellation; /* modulation type (see above) */ - TransmitMode TransmissionMode; - GuardInterval guardInterval; - Hierarchy HierarchyInformation; -} OFDMParameters; -\end{verbatim} - -In the case of QPSK frontends the Frequency field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator -frequency (LOF) of the LNB. -The intermediate frequency has to be specified in units of kHz. -For QAM and OFDM frontends the Frequency specifies the absolute frequency -and is given in Hz. - -The Inversion field can take one of these values: -\begin{verbatim} -typedef enum { - INVERSION_OFF, - INVERSION_ON, - INVERSION_AUTO -} SpectralInversion; -\end{verbatim} -It indicates if spectral inversion should be presumed or not. -In the automatic setting (\verb INVERSION_AUTO) the hardware will -try to figure out the correct setting by itself. - -\noindent -The possible values for the FEC\_inner field are -\begin{verbatim} -enum { - FEC_AUTO, - FEC_1_2, - FEC_2_3, - FEC_3_4, - FEC_5_6, - FEC_7_8, - FEC_NONE -}; -\end{verbatim} -which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., -no error correction or auto detection. - -\noindent -For cable and terrestrial frontends (QAM and OFDM) one also has to -specify the quadrature modulation mode which can be one of the following: -\begin{verbatim} -typedef enum -{ QPSK, - QAM_16, - QAM_32, - QAM_64, - QAM_128, - QAM_256 -} QAM_TYPE; -\end{verbatim} - -Finally, there are several more parameters for OFDM: -\begin{verbatim} -typedef enum { - TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K -} TransmitMode; -\end{verbatim} - -\begin{verbatim} -typedef enum { - BANDWIDTH_8_MHZ, - BANDWIDTH_7_MHZ, - BANDWIDTH_6_MHZ -} BandWidth; -\end{verbatim} - -\begin{verbatim} -typedef enum { - GUARD_INTERVAL_1_32, - GUARD_INTERVAL_1_16, - GUARD_INTERVAL_1_8, - GUARD_INTERVAL_1_4 -} GuardInterval; -\end{verbatim} - -\begin{verbatim} -typedef enum { - HIERARCHY_NONE, - HIERARCHY_1, - HIERARCHY_2, - HIERARCHY_4 -} Hierarchy; -\end{verbatim} - - -\devsubsubsec{frontend events} -\label{frontendevents} - -\begin{verbatim} -enum { - FE_UNEXPECTED_EV, - FE_COMPLETION_EV, - FE_FAILURE_EV -}; -\end{verbatim} - -\begin{verbatim} -typedef struct { - EventType type; /* type of event, FE_UNEXPECTED_EV, ... */ - long timestamp; /* time in seconds since 1970-01-01 */ - - union { - struct { - FrontendStatus previousStatus; /* status before event */ - FrontendStatus currentStatus; /* status during event */ - } unexpectedEvent; - FrontendParameters completionEvent; /* parameters for which the - tuning succeeded */ - FrontendStatus failureEvent; /* status at failure (e.g. no lock) */ - } u; -} FrontendEvent; -\end{verbatim} - -\begin{verbatim} -struct qpskRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qamRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qpskFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -struct qamFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - FE_POWER_ON, - FE_POWER_STANDBY, - FE_POWER_SUSPEND, - FE_POWER_OFF -} powerState_t; -\end{verbatim} - - -\clearpage - - -\devsubsec{Frontend Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - This system call opens a named frontend device (e.g. /dev/ost/qpskfe - for a satellite frontend or /dev/ost/qamfe for a cable frontend) - 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. - - }{ - const char *deviceName & Name of specific video device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ - & \hspace{1em} (blocking mode is the default)\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EINTERNAL & Internal error.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\ifunction{OST\_SELFTEST}{ - int ioctl(int fd, int request = OST\_SELFTEST);}{ - This ioctl call initiates an automatic self-test of the front-end hardware. - This call requires read/write access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SELFTEST for this command.\\ - }{ - -1& Self test failure.\\ -} - -\ifunction{OST\_SET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_SET\_POWER\_STATE, uint32\_t state);}{ - 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 supports 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: \\ - \begin{center} - \begin{tabular}[h]{cll} - number of low-power & requested state & resulting state\\ - states supported &&\\ - \\ - 1 & standby & suspend \\ - 1 & suspend & suspend \\ - 0 & standby & on \\ - 0 & suspend & on - \end{tabular} - \end{center}\\ - 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.) - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SET\_POWER\_STATE for this command.\\ - uint32\_t state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - 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\\ - \end{tabular} - }{ - 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. -} - -\ifunction{FE\_GET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_GET\_POWER\_STATE, uint32\_t *state);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_GET\_POWER\_STATE for this command.\\ - uint32\_t *state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - 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\\ - \end{tabular} - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINVAL& Illegal state, or not available on this device.\\ - EFAULT& state points to invalid address.\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_READ\_STATUS}{ - int ioctl(int fd, int request = FE\_READ\_STATUS, feStatus *status);}{ - This ioctl call returns status information about the front-end. - This call only requires read-only access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_READ\_STATUS for this command.\\ - struct feStatus *status&Points to the location where the front-end - status word is to be stored. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& status points to invalid address.\\ -} - -\ifunction{FE\_READ\_BER}{ - int ioctl(int fd, int request = FE\_READ\_BER, uint32\_t *ber);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_READ\_BER for this command.\\ - uint32\_t *ber & 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\cdot 10^{-6}$, or 1 error in 400000 bits. - }{ - 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. -} - -\ifunction{FE\_READ\_SNR}{ - int ioctl(int fd, int request = FE\_READ\_SNR, int32\_t *snr);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_READ\_SNR for this command.\\ - int32\_t *snr& 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. -}{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& snr 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. -} - -\ifunction{FE\_READ\_SIGNAL\_STRENGTH}{ - int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int32\_t *strength); -}{ -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. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals FE\_READ\_SIGNAL\_STRENGTH for this command.\\ -int32\_t *strength & 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. -}{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& status 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. -} - -\ifunction{FE\_READ\_UNCORRECTED\_BLOCKS}{ - int ioctl( int fd, int request = FE\_READ\_UNCORRECTED\_BLOCKS, uint32\_t *ublocks); }{ - This ioctl call returns the number of uncorrected blocks detected by - the device driver during its lifetime. - For meaningful measurements, the increment in - block count during a specific time interval should be calculated. - For this command, read-only access to the device is sufficient.\\ - Note that the counter will wrap to zero after its maximum count has - been reached. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals FE\_READ\_UNCORRECTED\_BLOCKS for this command.\\ -uint32\_t *ublocks & The total number of uncorrected blocks seen -by the driver so far. -}{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& ublocks points to invalid address.\\ - ENOSYS& Function not available for this device. -} - - -\ifunction{FE\_GET\_NEXT\_FREQUENCY}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_FREQUENCY, uint32\_t *freq);}{ - 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 efficient 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.\\ - Note that scanning may still be excruciatingly slow on some hardware, for - other reasons than a non-optimal scanning step size. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_FREQUENCY for this command.\\ - uint32\_t *freq& Input: a given frequency \\ - & Output: the frequency corresponding to - the next higher frequency setting.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& freq points to invalid address.\\ - EINVAL& Maximum supported frequency reached.\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_GET\_NEXT\_SYMBOL\_RATE}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_SYMBOL\_RATE, uint32\_t *symbolRate); - }{ - 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 efficient 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_SYMBOL\_RATE for this command.\\ - uint32\_t *symbolRate& Input: a given symbol rate \\ - & Output: the symbol rate corresponding to - the next higher symbol rate.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& symbolRate points to invalid address.\\ - EINVAL& Maximum supported symbol rate reached.\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_SET\_FRONTEND}{ - int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct FrontendParameters *p);}{ - This ioctl call starts a tuning operation using specified parameters. - The result of this call will be successful if the parameters were valid and - the tuning could be initiated. - The result of the tuning operation in itself, however, will arrive - asynchronously as an event (see documentation for FE\_GET\_EVENT - and FrontendEvent.) - If a new FE\_SET\_FRONTEND operation is initiated before the previous - one was completed, - the previous operation will be aborted in favor of the new one. - This command requires read/write access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_SET\_FRONTEND for this command.\\ - struct FrontendParameters *p& Points to parameters for tuning operation.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& p points to invalid address.\\ - EINVAL& Maximum supported symbol rate reached.\\ -} - -\ifunction{FE\_GET\_EVENT}{ - int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct qpskEvent *ev);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals QPSK\_GET\_EVENT for this command.\\ - struct qpskEvent *ev&Points to the location where the event, if any, is to be stored. - }{ - 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.\\ -} - -\ifunction{FE\_GET\_INFO}{ - int ioctl(int fd, int request = FE\_GET\_INFO, struct FrontendInfo *info);}{ - This ioctl call returns information about the front-end. - This call only requires read-only access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_INFO for this command.\\ - struct qpskFrontendInfo *info & Points to the location where the front-end - information is to be stored. - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& info points to invalid address.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/getbb b/dvb-spec/dvbapi/getbb deleted file mode 100755 index 004714d3a..000000000 --- a/dvb-spec/dvbapi/getbb +++ /dev/null @@ -1,12 +0,0 @@ -#!/bin/sh -f=`grep BoundingBox $2 | cut -d' ' -f2,3,4,5` -g=`\ -echo $2" llx=";(echo $f|cut -d' ' -f1 );\ -echo " lly=";(echo $f|cut -d' ' -f2 );\ -echo " urx=";(echo $f|cut -d' ' -f3 );\ -echo " ury=";(echo $f|cut -d' ' -f4 );\ -echo " rwi=";(echo $f|cut -d' ' -f3 );\ -echo "0" -` -h=`echo $g| sed "s/= /=/g" | sed "s/ 0/0/g"` -cat $1 | sed "s/psfile=$2/psfile=$h/" diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex deleted file mode 100644 index 1d859fadb..000000000 --- a/dvb-spec/dvbapi/intro.tex +++ /dev/null @@ -1,183 +0,0 @@ -\chapter{Introduction} -%\addcontentsline{toc}{part}{Introduction} -%\chaptermark{Introduction} -\section{What you need to know} -The reader of this document is required to have some knowledge in the -area of digital video broadcasting (DVB) and should be familiar with -part I of ISO/IEC 13818, i.e you should know what a -program/transport stream (PS/TS) is and what is meant by a packetized elementary -stream (PES) or an I-frame. - -It is also necessary to know how to access unix/linux devices and how -to use ioctl calls. This also includes the knowledge of C or C++. -\section{History} - -The first API for DVB cards we used at Convergence in late 1999 -was an extension of the Video4Linux API which was primarily -developed for frame grabber cards. -As such it was not really well suited to be used for DVB cards and -their new features like recording MPEG streams and filtering several -section and PES data streams at the same time. - -In early 2000, we were approached by Nokia with a proposal for a new -standard Linux DVB API. -As a commitment to the development of terminals based on open standards, -Nokia and Convergence made it available to all Linux developers and -published it on \texttt{http://www.linuxtv.org/} in September 2000. -Convergence is the maintainer of the Linux DVB API. -Together with the LinuxTV community (i.e. you, the reader of this document), -the Linux DVB API will be constantly reviewed and improved upon. -With the Linux driver for the Siemens/Hauppauge DVB PCI card Convergence -provides a first implementation of the Linux DVB API. - - -\section{Overview} - -\begin{figure}[htbp] - \begin{center} - \includegraphics{dvbstb.ps} - \caption{Components of a DVB card/STB} - \label{fig:dvbstb} - \end{center} -\end{figure} - - -A DVB PCI card or DVB set-top-box (STB) usually consists of the following -main hardware components: -\begin{itemize} -\item Frontend consisting of tuner and DVB demodulator - -Here the raw signal reaches the DVB hardware from a satellite dish or antenna -or directly from cable. The frontend down-converts and demodulates -this signal into an MPEG transport stream (TS). - -\item SEC for controlling external hardware like LNBs and antennas - -This part of the hardware can send signals back through the satellite -cable to control the polarization of the LNB, to switch between -different LNBs or even to control the movements of a dish rotor. - - -\item Conditional Access (CA) hardware like CI adapters and smartcard slots - -The complete TS is passed through the CA hardware. Programs to which -the user has access (controlled by the smart card) are decoded in real -time and re-inserted into the TS. - -\item Demultiplexer which filters the incoming DVB stream - -The demultiplexer splits the TS into its components like audio and video -streams. Besides usually several of such audio and video streams it also -contains data streams with information about the programs offered in this -or other streams of the same provider. - -\item MPEG2 audio and video decoder - -The main targets of the demultiplexer are the MPEG2 audio and video -decoders. After decoding the pass on the uncompressed audio -and video to the computer screen or (through a PAL/NTSC encoder) to -a TV set. -\end{itemize} -Figure \ref{fig:dvbstb} shows a crude schematic of the control and data flow -between those components. - -On a DVB PCI card not all of these have to be present since some -functionality can be provided by the main CPU of the PC (e.g. MPEG picture -and sound decoding) or is not needed (e.g. for data-only uses like -``internet over satellite''). -Also not every card or STB provides conditional access hardware. - -\section{Linux DVB Devices} - -The Linux DVB API lets you control these hardware components -through currently six Unix-style character devices for -video, audio, frontend, SEC, demux and CA. -The video and audio devices control the MPEG2 decoder hardware, -the frontend device the tuner and the DVB demodulator. -External hardware like DiSEqC switches and rotors can be controlled -through the SEC device. -The demux device gives you control over the PES and section filters -of the hardware. If the hardware does not support filtering these filters -can be implemented in software. -Finally, the CA device controls all the conditional access capabilities -of the hardware. It can depend on the individual security requirements -of the platform, if and how many of the CA functions are made available -to the application through this device. - -All devices can be found in the \texttt{/dev} tree under -\texttt{/dev/ost}, where OST stands for Open Standards Terminal. -The individual devices are called -\begin{itemize} -\item \texttt{/dev/ost/audio}, -\item \texttt{/dev/ost/video}, -\item \texttt{/dev/ost/frontend}, -\item \texttt{/dev/ost/sec}, -\item \texttt{/dev/ost/demux}, -\item \texttt{/dev/ost/ca}, -\end{itemize} -but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of -these devices. - -If more than one card is present in the system the other cards -can be accessed through the corresponding devices with the -card's number appended. \texttt{/dev/ost/demux0} (which -is identical to \texttt{/dev/ost/demux}) would, e.g., control the -demultiplexer of the first card, while \texttt{/dev/ost/demux1} -would control the demultiplexer of the second card, and so on. - -More details about the data structures and function calls of -all the devices are described in the following chapters. - - -\section{DVB Devices with Devfs} - -Recent Linux kernel versions support a special file system called -\textsl{devfs} which is a replacement for the traditional -device directory. -With devfs a Linux DVB driver will only create those device file entries -which actually exist. -It also makes dealing with more complex DVB hardware much easier. -The device structure described above is not well suited to deal -with multiple DVB cards with more than one frontend or demultiplexer. -Consider, e.g., two DVB cards, one with two frontends and -one demultiplexer, the other with one frontend and two demultiplexers. -If we just assign them consecutive numbers, there would be a demultiplexer -and a frontend which do not belong to the same card but have -the same number. - -With \textsl{devfs} we propose a different scheme for the device names. -The root directory for all DVB cards will be \texttt{/dev/dvb}. -Each card gets assigned a sub-directory with the name \texttt{/dev/card0}, -\texttt{/dev/card1}, etc. -The files created in these sub-directories will correspond directly to the -hardware actually present on the card. -Thus, if the first card has one QAM frontend, one demultiplexer -and otherwise no other hardware, -only \texttt{/dev/dvb/card0/qamfe0} and \texttt{/dev/dvb/card0/demux0} -will be created. -When a second DVB-S card with one frontend (including SEC) device, -two demultiplexers and an MPEG2 audio/video decoder is added, the -complete \texttt{/dev/dvb} tree will look like this: - -\begin{verbatim} -/dev/dvb/card0/frontend0 - demux0 - -/dev/dvb/card1/video0 - audio0 - demux0 - demux1 - frontend0 - sec0 -\end{verbatim} - - -\section{Using the Devices} - -\dots - - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex deleted file mode 100644 index 59490299b..000000000 --- a/dvb-spec/dvbapi/kdapi.tex +++ /dev/null @@ -1,1007 +0,0 @@ -\devsec{Kernel Demux API} - -The kernel demux API - -\devsubsec{Kernel Demux Data Types} - -\devsubsubsec{dmx\_success\_t} -\label{dmxsuccesst} - -\begin{verbatim} -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; -\end{verbatim} - - -\devsubsubsec{TS filter types} -\label{tsfiltertypes} - -\begin{verbatim} -/*--------------------------------------------------------------------------*/ -/* TS packet reception */ -/*--------------------------------------------------------------------------*/ - -/* TS filter type for set_type() */ - -#define TS_PACKET 1 /* send TS packets (188 bytes) to callback (default) */ -#define TS_PAYLOAD_ONLY 2 /* in case TS_PACKET is set, only send the TS - payload (<=184 bytes per packet) to callback */ -#define TS_DECODER 4 /* send stream to built-in decoder (if present) */ -\end{verbatim} - - -\devsubsubsec{dmx\_ts\_pes\_t} -\label{dmxtspest} - -The structure -\begin{verbatim} -typedef enum -{ - DMX_TS_PES_AUDIO, /* also send packets to audio decoder (if it exists) */ - DMX_TS_PES_VIDEO, /* ... */ - DMX_TS_PES_TELETEXT, - DMX_TS_PES_SUBTITLE, - DMX_TS_PES_PCR, - DMX_TS_PES_OTHER, -} dmx_ts_pes_t; -\end{verbatim} -describes the PES type for filters which write to -a built-in decoder. -The correspond (and should be kept identical) to the types in -the demux device. - -\begin{verbatim} -struct dmx_ts_feed_s { - int is_filtering; /* Set to non-zero when filtering in progress */ - struct dmx_demux_s* parent; /* Back-pointer */ - void* priv; /* Pointer to private data of the API client */ - int (*set) (struct dmx_ts_feed_s* feed, - __u16 pid, - size_t callback_length, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (*start_filtering) (struct dmx_ts_feed_s* feed); - int (*stop_filtering) (struct dmx_ts_feed_s* feed); - int (*set_type) (struct dmx_ts_feed_s* feed, - int type, - dmx_ts_pes_t pes_type); -}; - -typedef struct dmx_ts_feed_s dmx_ts_feed_t; -\end{verbatim} - -\begin{verbatim} -/*--------------------------------------------------------------------------*/ -/* PES packet reception (not supported yet) */ -/*--------------------------------------------------------------------------*/ - -typedef struct dmx_pes_filter_s { - struct dmx_pes_s* parent; /* Back-pointer */ - void* priv; /* Pointer to private data of the API client */ -} dmx_pes_filter_t; -\end{verbatim} - -\begin{verbatim} -typedef struct dmx_pes_feed_s { - int is_filtering; /* Set to non-zero when filtering in progress */ - struct dmx_demux_s* parent; /* Back-pointer */ - void* priv; /* Pointer to private data of the API client */ - int (*set) (struct dmx_pes_feed_s* feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - struct timespec timeout); - int (*start_filtering) (struct dmx_pes_feed_s* feed); - int (*stop_filtering) (struct dmx_pes_feed_s* feed); - int (*allocate_filter) (struct dmx_pes_feed_s* feed, - dmx_pes_filter_t** filter); - int (*release_filter) (struct dmx_pes_feed_s* feed, - dmx_pes_filter_t* filter); -} dmx_pes_feed_t; -\end{verbatim} - - -\label{sectionfilter} -\begin{verbatim} -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; -\end{verbatim} - -\begin{verbatim} -struct dmx_section_feed_s { - int is_filtering; /* Set to non-zero when filtering in progress */ - struct dmx_demux_s* parent; /* Back-pointer */ - void* priv; /* Pointer to private data of the API client */ - int (*set) (struct dmx_section_feed_s* feed, - __u16 pid, - size_t circular_buffer_size, - int descramble, - int check_crc); - int (*allocate_filter) (struct dmx_section_feed_s* feed, - dmx_section_filter_t** filter); - int (*release_filter) (struct dmx_section_feed_s* feed, - dmx_section_filter_t* filter); - int (*start_filtering) (struct dmx_section_feed_s* feed); - int (*stop_filtering) (struct dmx_section_feed_s* feed); -}; -typedef struct dmx_section_feed_s dmx_section_feed_t; - -/*--------------------------------------------------------------------------*/ -/* Callback functions */ -/*--------------------------------------------------------------------------*/ - -typedef int (*dmx_ts_cb) ( __u8 * buffer1, - size_t buffer1_length, - __u8 * buffer2, - size_t buffer2_length, - dmx_ts_feed_t* source, - dmx_success_t success); - -typedef int (*dmx_section_cb) ( __u8 * buffer1, - size_t buffer1_len, - __u8 * buffer2, - size_t buffer2_len, - dmx_section_filter_t * source, - dmx_success_t success); - -typedef int (*dmx_pes_cb) ( __u8 * buffer1, - size_t buffer1_len, - __u8 * buffer2, - size_t buffer2_len, - dmx_pes_filter_t* source, - dmx_success_t success); - -/*--------------------------------------------------------------------------*/ -/* DVB Front-End */ -/*--------------------------------------------------------------------------*/ - -typedef enum { - DMX_OTHER_FE = 0, - DMX_SATELLITE_FE, - DMX_CABLE_FE, - DMX_TERRESTRIAL_FE, - DMX_LVDS_FE, - DMX_ASI_FE, /* DVB-ASI interface */ - DMX_MEMORY_FE -} dmx_frontend_source_t; - -typedef struct { - /* The following char* fields point to NULL terminated strings */ - char* id; /* Unique front-end identifier */ - char* vendor; /* Name of the front-end vendor */ - char* model; /* Name of the front-end model */ - struct list_head connectivity_list; /* List of front-ends that can - be connected to a particular - demux */ - void* priv; /* Pointer to private data of the API client */ - dmx_frontend_source_t source; -} dmx_frontend_t; - -/*--------------------------------------------------------------------------*/ -/* MPEG-2 TS Demux */ -/*--------------------------------------------------------------------------*/ - -/* - * Flags OR'ed in the capabilites field of struct dmx_demux_s. - */ - -#define DMX_TS_FILTERING 1 -#define DMX_PES_FILTERING 2 -#define DMX_SECTION_FILTERING 4 -#define DMX_MEMORY_BASED_FILTERING 8 /* write() available */ -#define DMX_CRC_CHECKING 16 -#define DMX_TS_DESCRAMBLING 32 -#define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 -#define DMX_MAC_ADDRESS_DESCRAMBLING 128 -\end{verbatim} - -\devsubsubsec{demux\_demux\_t} -\label{demuxdemuxt} - -\begin{verbatim} -/* - * DMX_FE_ENTRY(): Casts elements in the list of registered - * front-ends from the generic type struct list_head - * to the type * dmx_frontend_t - *. -*/ - -#define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) - -struct dmx_demux_s { - /* The following char* fields point to NULL terminated strings */ - char* id; /* Unique demux identifier */ - char* vendor; /* Name of the demux vendor */ - char* model; /* Name of the demux model */ - __u32 capabilities; /* Bitfield of capability flags */ - dmx_frontend_t* frontend; /* Front-end connected to the demux */ - struct list_head reg_list; /* List of registered demuxes */ - void* priv; /* Pointer to private data of the API client */ - int users; /* Number of users */ - int (*open) (struct dmx_demux_s* demux); - int (*close) (struct dmx_demux_s* demux); - int (*write) (struct dmx_demux_s* demux, const char* buf, size_t count); - int (*allocate_ts_feed) (struct dmx_demux_s* demux, - dmx_ts_feed_t** feed, - dmx_ts_cb callback); - int (*release_ts_feed) (struct dmx_demux_s* demux, - dmx_ts_feed_t* feed); - int (*allocate_pes_feed) (struct dmx_demux_s* demux, - dmx_pes_feed_t** feed, - dmx_pes_cb callback); - int (*release_pes_feed) (struct dmx_demux_s* demux, - dmx_pes_feed_t* feed); - int (*allocate_section_feed) (struct dmx_demux_s* demux, - dmx_section_feed_t** feed, - dmx_section_cb callback); - int (*release_section_feed) (struct dmx_demux_s* demux, - dmx_section_feed_t* feed); - int (*descramble_mac_address) (struct dmx_demux_s* demux, - __u8* buffer1, - size_t buffer1_length, - __u8* buffer2, - size_t buffer2_length, - __u16 pid); - int (*descramble_section_payload) (struct dmx_demux_s* demux, - __u8* buffer1, - size_t buffer1_length, - __u8* buffer2, size_t buffer2_length, - __u16 pid); - int (*add_frontend) (struct dmx_demux_s* demux, - dmx_frontend_t* frontend); - int (*remove_frontend) (struct dmx_demux_s* demux, - dmx_frontend_t* frontend); - struct list_head* (*get_frontends) (struct dmx_demux_s* demux); - int (*connect_frontend) (struct dmx_demux_s* demux, - dmx_frontend_t* frontend); - int (*disconnect_frontend) (struct dmx_demux_s* demux); - - - /* added because js cannot keep track of these himself */ - int (*get_pes_pids) (struct dmx_demux_s* demux, __u16 *pids); -}; -typedef struct dmx_demux_s dmx_demux_t; -\end{verbatim} - - -\devsubsubsec{Demux directory} -\label{demuxdir} - -\begin{verbatim} -/* - * 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); -\end{verbatim} - -\clearpage - -\devsubsec{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. - -\kifunction{dmx\_register\_demux()}{ - int dmx\_register\_demux ( dmx\_demux\_t *demux ) - }{ - 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(), - }{ - dmx\_demux\_t* demux & Pointer to the demux structure. - }{ - 0 & The function was completed without errors.\\ - -EEXIST & A demux with the same value of the id field - already stored in the directory.\\ - -ENOSPC & No space left in the directory. -} - -\kifunction{dmx\_unregister\_demux()}{ - int dmx\_unregister\_demux ( dmx\_demux\_t *demux ) - }{ - 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. - }{ - dmx\_demux\_t* demux & Pointer to the demux structure which is to be unregistered. - }{ - 0 & The function was completed without errors.\\ - ENODEV & The specified demux is not registered in the demux directory.\\ - EBUSY & The specified demux is currently in use. -} - -\kifunction{dmx\_get\_demuxes()}{ - struct list\_head *dmx\_get\_demuxes () - }{ - 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. - }{ - none - }{ - struct list\_head * & - A list of demux interfaces, or NULL in the case of an empty list. -} - -\clearpage - -\devsubsec{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 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 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. - -\kfunction{open()}{ - int open ( demux\_t* demux ); - }{ - 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. - }{ - demux\_t* demux & Pointer to the demux API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EUSERS & Maximum usage count reached.\\ - -EINVAL & Bad parameter. -} - -\kfunction{close()}{ - int close(demux\_t* demux); - }{ - 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. - }{ - demux\_t* demux & Pointer to the demux API and instance data. - }{ - 0 & The function was completed without errors.\\ - -ENODEV & The demux was not in use.\\ - -EINVAL & Bad parameter. -} - -\kfunction{write()}{ - int write(demux\_t* demux, const char* buf, size\_t count); - }{ - This function provides the demux driver with a memory buffer containing TS - packets. Instead of receiving TS packets from the DVB front-end, the demux - driver software will read packets from memory. Any clients of this demux - with active TS, PES or Section filters will receive filtered data via the Demux - callback API (see 0). The function returns when all the data in the buffer has - been consumed by the demux. - Demux hardware typically cannot read TS from memory. If this is the case, - memory-based filtering has to be implemented entirely in software. - }{ - demux\_t* demux & Pointer to the demux API and instance data.\\ - const char* buf & Pointer to the TS data in kernel-space memory.\\ - size\_t length & Length of the TS data. - }{ - 0 & The function was completed without errors.\\ - -ENOSYS & The command is not implemented.\\ - -EINVAL & Bad parameter. -} - -\kifunction{allocate\_ts\_feed()}{ - int allocate\_ts\_feed(dmx\_demux\_t* demux, - dmx\_ts\_feed\_t** feed, dmx\_ts\_cb callback); - }{ - 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. - }{ - demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_ts\_feed\_t** feed & Pointer to the TS feed API and instance data.\\ - dmx\_ts\_cb callback & Pointer to the callback function for - passing received TS packet - }{ - 0 & The function was completed without errors.\\ - -EBUSY & No more TS feeds available.\\ - -ENOSYS & The command is not implemented.\\ - -EINVAL & Bad parameter. -} - -\kifunction{release\_ts\_feed()}{ - int release\_ts\_feed(dmx\_demux\_t* demux, dmx\_ts\_feed\_t* feed); - }{ - Releases the resources allocated with allocate\_ts\_feed(). Any filtering in progress - on the TS feed should be stopped before calling this function. - }{ - demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{allocate\_section\_feed()}{ - int allocate\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t **feed, - dmx\_section\_cb callback); - }{ - 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. - }{ - demux\_t *demux & Pointer to the demux API and instance data.\\ - dmx\_section\_feed\_t **feed & Pointer to the section feed API and instance data.\\ - dmx\_section\_cb callback & Pointer to the callback function for - passing received sections. - }{ - 0 & The function was completed without errors.\\ - -EBUSY & No more section feeds available.\\ - -ENOSYS & The command is not implemented.\\ - -EINVAL & Bad parameter. -} - - -\kifunction{release\_section\_feed()}{ - int release\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t *feed); - }{ - 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. - }{ - demux\_t *demux & Pointer to the demux API and instance data.\\ - dmx\_section\_feed\_t *feed & Pointer to the section feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{descramble\_mac\_address()}{ - int descramble\_mac\_address(dmx\_demux\_t* demux, - \_\_u8 *buffer1, size\_t buffer1\_length, - \_\_u8 *buffer2, size\_t buffer2\_length, \_\_u16 pid); - }{ - This function runs a descrambling algorithm on the destination MAC address field of a - DVB Datagram Section, replacing the original address with its un-encrypted version. - Otherwise, the description on the function descramble\_section\_payload() applies - also to this function. - }{ - dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ - \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ - size\_t buffer1\_length & Length of the section data, including headers and CRC, - in buffer1.\\ - \_\_u8* buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a - non-NULL value if the section wraps - past the end of a circular buffer.\\ - size\_t buffer2\_length & Length of the section data, - including headers and CRC, in buffer2.\\ - \_\_u16 pid & The PID on which the section was received. Useful for obtaining the - descrambling key, e.g. from a DVB Common Access facility. - }{ - 0 & The function was completed without errors.\\ - -ENOSYS & No descrambling facility available.\\ - -EINVAL & Bad parameter. -} - -\kifunction{descramble\_section\_payload()}{ - int descramble\_section\_payload(dmx\_demux\_t* demux, - \_\_u8 *buffer1, size\_t buffer1\_length, \_\_u8 *buffer2, size\_t - buffer2\_length, \_\_u16 pid); - }{ - This function runs a descrambling algorithm on the payload of a DVB Datagram - Section, replacing the original payload with its un-encrypted version. - The function will - be called from the demux API implementation; the API client need - not call this function directly. - Section-level scrambling algorithms are currently standardized only for DVB-RCC - (return channel over 2-directional cable TV network) systems. For all other DVB - networks, encryption schemes are likely to be proprietary to each data broadcaster. - Thus, it is expected that this function pointer will have the value of NULL - (i.e., function not available) in most demux API implementations. - Nevertheless, it should be possible - to use the function pointer as a hook for dynamically adding a ``plug-in'' - descrambling facility to a demux driver.\\ - 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. - }{ - dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ - \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ - size\_t buffer1\_length & Length of the section data, including headers and CRC, in - buffer1.\\ - \_\_u8 *buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a - non-NULL value if the section wraps - past the end of a circular buffer.\\ - size\_t buffer2\_length & Length of the section data, including headers and CRC, in - buffer2.\\ - \_\_u16 pid & The PID on which the section was received. Useful for obtaining the - descrambling key, e.g. from a DVB Common Access facility. - }{ - 0 & The function was completed without errors.\\ - -ENOSYS & No descrambling facility available.\\ - -EINVAL & Bad parameter. -} - -\kifunction{add\_frontend()}{ - int add\_frontend(dmx\_demux\_t *demux, dmx\_frontend\_t *frontend); - }{ - 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(). - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_frontend\_t* frontend & Pointer to the front-end instance data. - }{ - 0 & The function was completed without errors.\\ - -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 parameter. -} - -\kifunction{remove\_frontend()}{ - int remove\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); - }{ - Indicates that the given front-end, registered by a call to add\_frontend(), can no - longer be connected as a TS source by this demux. The function should be called - when a front-end driver or a demux driver is removed from the system. If the front-end - is in use, the function fails with the return value of -EBUSY. - After successfully calling this function, the caller can free the memory of - the frontend struct if it was dynamically allocated before the add\_frontend() - operation. - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_frontend\_t* frontend & Pointer to the front-end instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter.\\ - -EBUSY & The front-end is in use, i.e. a call to - connect\_frontend() has not been followed by - a call to disconnect\_frontend(). -} - -\kifunction{get\_frontends()}{ - struct list\_head* get\_frontends(dmx\_demux\_t* demux); - }{ - 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. - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data. - }{ - dmx\_demux\_t* & A list of front-end interfaces, or NULL in the case of an empty list. -} - - -\kifunction{connect\_frontend()}{ - int connect\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); - }{ - 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(). - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ - dmx\_frontend\_t* frontend & Pointer to the front-end instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter.\\ - -EBUSY & The front-end is in use. -} - -\kifunction{disconnect\_frontend()}{ - int disconnect\_frontend(dmx\_demux\_t* demux); - }{ - Disconnects the demux and a front-end previously connected by a - connect\_frontend() call. - }{ - dmx\_demux\_t* demux & Pointer to the demux API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\clearpage - -\devsubsec{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. - -\kifunction{dmx\_ts\_cb()}{ - 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); - }{ - 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. \\ - Any TS packets that match the filter settings are copied to a circular buffer. - The filtered TS packets are delivered to the client using this callback - function. The size of the circular buffer is controlled by the - circular\_buffer\_size parameter of the set() function in the TS Feed API. It is - expected that the buffer1 and buffer2 callback parameters point to addresses - within the circular buffer, but other implementations are also - possible. Note that the called party should not try to free the memory the - buffer1 and buffer2 parameters point to.\\ - When this function is called, the buffer1 parameter typically points to the - start of the first undelivered TS packet within a circular buffer. The buffer2 - buffer parameter is normally NULL, except when the received TS packets have - crossed the last address of the circular buffer and "wrapped" to the beginning - of the buffer. In the latter case the buffer1 parameter would contain an - address within the circular buffer, while the buffer2 parameter would contain - the first address of the circular buffer.\\ - The number of bytes delivered with this function (i.e. buffer1\_length + - buffer2\_length) is usually equal to the value of callback\_length parameter given - in the set() function, with one exception: if a timeout occurs before receiving - callback\_length bytes of TS data, any undelivered packets are immediately - delivered to the client by calling this function. The timeout duration is - controlled by the set() function in the TS Feed API.\\ - If a TS packet is received with errors that could not be fixed by the TS-level - forward error correction (FEC), the Transport\_error\_indicator flag of the TS - packet header should be set. The TS packet should not be discarded, as the - error can possibly be corrected by a higher layer protocol. - If the called party is slow in processing the callback, it is possible that - the circular buffer eventually fills up. If this happens, the demux driver - should discard any TS packets received while the buffer is full. The error - should be indicated to the client on the next callback by setting the success - parameter to the value of DMX\_OVERRUN\_ERROR.\\ - The type of data returned to the callback can be selected by the - new function int (*set\_type) (struct dmx\_ts\_feed\_s* feed, int type, - dmx\_ts\_pes\_t pes\_type) which is part of the dmx\_ts\_feed\_s struct - (also cf. to the include file ost/demux.h) - The type parameter decides if the raw TS packet (TS\_PACKET) or just the - payload (TS\_PACKET|TS\_PAYLOAD\_ONLY) should be returned. - If additionally the TS\_DECODER bit is set the stream will also be sent - to the hardware MPEG decoder. In this case, the second flag decides - as what kind of data the stream should be interpreted. - The possible choices are one of DMX\_TS\_PES\_AUDIO, DMX\_TS\_PES\_VIDEO, - DMX\_TS\_PES\_TELETEXT, DMX\_TS\_PES\_SUBTITLE, DMX\_TS\_PES\_PCR, or - DMX\_TS\_PES\_OTHER. - }{ - \_\_u8* buffer1 & Pointer to the start of the filtered TS packets.\\ - size\_t buffer1\_length & Length of the TS data in buffer1.\\ - \_\_u8* buffer2 & Pointer to the tail of the filtered TS packets, or NULL.\\ - size\_t buffer2\_length & Length of the TS data in buffer2.\\ - dmx\_ts\_feed\_t* source & Indicates which TS feed is the source of the callback.\\ - dmx\_success\_t success & Indicates if there was an error in TS reception. - }{ - 0 & Continue filtering.\\ - -1& Stop filtering - has the same effect as a call - to stop\_filtering() on the TS Feed API. -} - -\kifunction{dmx\_section\_cb()}{ - 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); - }{ - This function, provided by the client of the demux API, is called from the demux code. - The function is only called when filtering of sections has been enabled using the - function start\_filtering() of the section feed API. - When the demux driver has received a complete section that matches at least one - section filter, the client is notified via this callback function. Normally this function is - called for each received section; however, it is also possible to deliver multiple sections - with one callback, for example when the system load is high. - If an error occurs while receiving a section, this function should be called with the - corresponding error type set in the success field, whether or not there is data to - deliver. - The Section Feed implementation should maintain a circular buffer for received sections. - However, this is not necessary if the Section Feed API is implemented as a client of - the TS Feed API, because the TS Feed implementation then buffers the - received data. - The size of the circular buffer can be configured using the set() function in the - Section Feed API. If there is no room in the circular buffer when a new section is - received, the section must be discarded. If this happens, the value of the success - parameter should be DMX\_OVERRUN\_ERROR on the next callback. - }{ - \_\_u8* buffer1 & Pointer to the start of the filtered section, e.g. - within the circular buffer of the demux driver.\\ - size\_t buffer1\_length & 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 circular - buffer.\\ - size\_t buffer2\_length & Length of the filtered section data in buffer2, - including headers and CRC.\\ - dmx\_section\_filter\_t* filter & Indicates the filter that triggered the callback.\\ - dmx\_success\_t success & Indicates if there was an error in section reception. - }{ - 0 & Continue filtering.\\ - -1& Stop filtering - has the same effect as a call - to stop\_filtering() on the Section Feed API. -} - -\clearpage - -\devsubsec{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. - -\kifunction{set()}{ - int set ( dmx\_ts\_feed\_t* feed, \_\_u16 pid, size\_t callback\_length, - size\_t circular\_buffer\_size, int descramble, struct timespec timeout); - }{ - This function sets the parameters of a TS feed. - Any filtering in progress on the TS feed - must be stopped before calling this function. - }{ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data.\\ - \_\_u16 pid & PID value to filter. Only the TS packets carrying the specified PID will - be passed to the API client.\\ - size\_t callback\_length & 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 circular\_buffer\_size & Size of the circular buffer for the filtered TS packets.\\ - int descramble & If non-zero, descramble the filtered TS packets.\\ - struct timespec timeout & Maximum time to wait before - delivering received TS packets to the client. - }{ - 0 & The function was completed without errors.\\ - -ENOMEM & Not enough memory for the requested buffer size.\\ - -ENOSYS & No descrambling facility available for TS.\\ - -EINVAL & Bad parameter. -} - - -\kifunction{start\_filtering()}{ - int start\_filtering(dmx\_ts\_feed\_t* feed); - }{ - 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(). - }{ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{stop\_filtering()}{ - int stop\_filtering(dmx\_ts\_feed\_t* feed); - }{ - Stops filtering TS packets on this TS feed. - }{ - dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\clearpage - -\devsubsec{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. - - -\kifunction{set()}{ - int set(dmx\_section\_feed\_t* feed, \_\_u16 pid, size\_t circular\_buffer\_size, - int descramble, int check\_crc); - }{ - This function sets the parameters of a section feed. Any filtering in progress on the - section feed must be stopped before calling this function. - If descrambling is enabled, the payload\_scrambling\_control and - address\_scrambling\_control fields of received DVB datagram sections should be - observed. If either one is non-zero, the section should be descrambled either in - hardware or using the functions descramble\_mac\_address() and - descramble\_section\_payload() of the demux API. Note that according to the - MPEG-2 Systems specification, only the payloads of private sections can be - scrambled while the rest of the section data must be sent in the clear. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - \_\_u16 pid & PID value to filter; only the TS packets - carrying the specified PID will be accepted.\\ - size\_t circular\_buffer\_size & Size of the circular buffer for filtered sections.\\ - int descramble & If non-zero, descramble any sections that are scrambled.\\ - int check\_crc & If non-zero, check the CRC values of filtered sections. - }{ - 0 & The function was completed without errors.\\ - -ENOMEM & Not enough memory for the requested buffer size.\\ - -ENOSYS & No descrambling facility available for sections.\\ - -EINVAL & Bad parameters. -} - -\kifunction{allocate\_filter()}{ - int allocate\_filter(dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t** filter); - }{ - This function is used to allocate a section filter on the demux. - It should only be called when no filtering is in progress on this section feed. - If a filter cannot be allocated, the function fails with -ENOSPC. - See in section \ref{sectionfilter} for the format of the section filter. \\ - 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. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - dmx\_section\_filter\_t** filter & Pointer to the allocated filter. - }{ - 0 & The function was completed without errors.\\ - -ENOSPC & No filters of given type and length available.\\ - -EINVAL & Bad parameters. -} - -\kifunction{release\_filter()}{ - int release\_filter ( dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t* filter); - }{ - 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. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - dmx\_section\_filter\_t* filter & I/O Pointer to the instance data of a section filter. - }{ - 0 & The function was completed without errors.\\ - -ENODEV & No such filter allocated.\\ - -EINVAL & Bad parameter. -} - -\kifunction{start\_filtering()}{ - int start\_filtering ( dmx\_section\_feed\_t* feed ); - }{ - 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(). - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - -\kifunction{stop\_filtering()}{ - int stop\_filtering ( dmx\_section\_feed\_t* feed ); - }{ - 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. - }{ - dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data. - }{ - 0 & The function was completed without errors.\\ - -EINVAL & Bad parameter. -} - - - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex deleted file mode 100644 index 88342c3a6..000000000 --- a/dvb-spec/dvbapi/sec.tex +++ /dev/null @@ -1,282 +0,0 @@ -\devsec{DVB SEC API} - -The DVB SEC device controls the Satellite Equipment Control of -the DVB hardware, i.e. DiSEqC and V-SEC. -It is accessed through \texttt{/dev/ost/sec}. - -\devsubsec{SEC Data Types} - -\devsubsubsec{secDiseqcCmd} -\label{secdiseqccmd} - -\begin{verbatim} -struct secDiseqcCmd { - uint8_t addr; - uint8_t cmd; - uint8_t numParams; - uint8_t params[SEC_MAX_DISEQC_PARAMS]; -}; -\end{verbatim} - - -\devsubsubsec{secVoltage} -\label{secvoltage} - -\begin{verbatim} -typedef uint32_t secVoltage; -\end{verbatim} -\begin{verbatim} -enum { - SEC_VOLTAGE_OFF, - SEC_VOLTAGE_LT, - SEC_VOLTAGE_13, - SEC_VOLTAGE_13_5, - SEC_VOLTAGE_18, - SEC_VOLTAGE_18_5 -}; -\end{verbatim} - - -\devsubsubsec{secToneMode} -\label{sectonemode} - -\begin{verbatim} -typedef uint32_t secToneMode; -\end{verbatim} -\begin{verbatim} -typedef enum { - SEC_TONE_ON, - SEC_TONE_OFF -} secToneMode_t; -\end{verbatim} - - -\devsubsubsec{secMiniCmd} -\label{secminicmd} - -\begin{verbatim} -typedef uint32_t secMiniCmd; -\end{verbatim} -\begin{verbatim} -typedef enum { - SEC_MINI_NONE, - SEC_MINI_A, - SEC_MINI_B -} secMiniCmd_t; -\end{verbatim} -\begin{verbatim} -struct secStatus { - int32_t busMode; - secVoltage selVolt; - secToneMode contTone; -}; -\end{verbatim} - -\begin{verbatim} -enum { - SEC_BUS_IDLE, - SEC_BUS_BUSY, - SEC_BUS_OFF, - SEC_BUS_OVERLOAD -}; -\end{verbatim} - - -\devsubsubsec{secCommand} -\label{seccommand} - -\begin{verbatim} -struct secCommand { - int32_t type; - union { - struct secDiseqcCmd diseqc; - uint8_t vsec; - uint32_t pause; - } u; -}; -\end{verbatim} - - -\devsubsubsec{secCmdSequence} -\label{seccmdsequence} - -\begin{verbatim} -struct secCmdSequence { - secVoltage voltage; - secMiniCmd miniCommand; - secToneMode continuousTone; - - uint32_t numCommands; - struct secCommand* commands; -}; -\end{verbatim} - -\begin{verbatim} -enum { - SEC_CMDTYPE_DISEQC, - SEC_CMDTYPE_VSEC, - SEC_CMDTYPE_PAUSE -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - SEC_DISEQC_SENT, - SEC_VSEC_SENT, - SEC_PAUSE_COMPLETE, - SEC_CALLBACK_ERROR -} secCallback_t; -\end{verbatim} - -\clearpage - -\devsubsec{SEC Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - This system call opens a named SEC device for subsequent use. - If the device is opened in read-only mode, only status and statistics - monitoring is allowed. If the device is opened in read/write mode, all - types of operations can be performed. - Any number of applications can have simultaneous access to the device. - }{ - const char *deviceName & Name of specific SEC device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & The optional flag O\_NONBLOCK is not supported. If O\_NONBLOCK is set, - open() and most other subsequent calls to the device will return -1 and - set errno to EWOULDBLOCK. - The communication with the peripheral devices is sequential by nature, - so it is probably preferable to use the device in synchronous mode. - This is the motivation for not going through the extra effort of - implementing asynchronous operation of the device. - }{ - ENODEV & Device driver not loaded/available.\\ - EFAULT & deviceName does not refer to a valid memory area.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call closes a previously opened SEC device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\ifunction{SEC\_GET\_STATUS}{ - int ioctl(int fd, int request = SEC\_GET\_STATUS, struct secStatus* status);}{ - This call gets the status of the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_GET\_STATUS for this command.\\ - struct secStatus* status & The status of the device.\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EFAULT & status is an invalid pointer.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ - EPERM & File not opened with read permissions.\\ - EINTERNAL & Internal error in the device driver.\\ -} - -\ifunction{SEC\_RESET\_OVERLOAD}{ - int ioctl(int fd, int request = SEC\_RESET\_OVERLOAD);}{ - If the bus has been automatically powered off due to power overload, this - ioctl call restores the power to the bus. The call requires read/write - access to the device. - This call has no effect if the device is manually powered off. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_RESET\_OVERLOAD for this command.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EPERM & Permission denied (needs read/write access).\\ - EINTERNAL & Internal error in the device driver.\\ -} - -\ifunction{SEC\_SEND\_SEQUENCE}{ -int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); -}{ -This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC -commands. The first version of the SEC device does not support V-SEC -signaling and it aborts the operation with an error code if a V-SEC -command is detected in the input data.\\ -\begin{itemize} -\item[$\bullet$] The call will fail with errno set to EBUSOVERLOAD if the bus is -overloaded. If the bus is overloaded, SEC\_RESET\_OVERLOAD can be -called and the operation can be retried. -\item[$\bullet$] If seq.numCommands equals 0 and seq.miniCommand equals SEC\_MINI\_NONE, -the bus voltage will be switched and the continuous 22kHz tone -generation enabled/disabled immediately. -\end{itemize}\\ -This operation is atomic. If several processes calls this ioctl -simultaneously, the operations will be serialized so a complete sequence -is sent at a time. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_SEND\_SEQUENCE for this command.\\ - struct secCmdSequence *seq & Pointer to the command sequence to be transmitted.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EFAULT & Seq points to an invalid address.\\ - EINVAL & The data structure referred to by seq is invalid in some way.\\ - EPERM & Permission denied (needs read/write access).\\ - EINTERNAL & Internal error in the device driver.\\ - EBUSMODE & The device is not prepared for transmission - (e.g. it might be manually powered off).\\ - EBUSOVERLOAD & Bus overload has occurred.\\ -} - - -\ifunction{SEC\_SET\_TONE}{ -int ioctl(int fd, int request = SEC\_SET\_TONE, secToneMode tone); -}{ -This call is used to set the generation of the continuous 22kHz tone. -The possibility to just change the tone mode is already provided by -ioctl SEC\_SEND\_SEQUENCE, but SEC\_SET\_TONE is an easier to use interface. -To keep the transmission of a command sequence as -an atomic operation, SEC\_SET\_TONE will block if a transmission is in -progress. This call requires read/write permissions. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals SEC\_SET\_TONE for this command.\\ -secToneMode tone & The requested tone generation mode (on/off).\\ -}{ -ENODEV & Device driver not loaded/available.\\ -EBUSY & Device or resource busy.\\ -EINVAL & Invalid argument.\\ -EPERM & File not opened with read permissions.\\ -EINTERNAL & Internal error in the device driver.\\ -} - - -\ifunction{SEC\_SET\_VOLTAGE}{ -int ioctl(int fd, int request = SEC\_SET\_VOLTAGE, secVoltage voltage); -}{ -This call is used to set the bus voltage. The possibility to just change -the bus voltage is already provided by ioctl SEC\_SEND\_SEQUENCE, but -SEC\_SET\_VOLTAGE is an easier to use interface. -To keep the transmission of a command sequence as -an atomic operation, SEC\_SET\_VOLTAGE will block if a transmission is in -progress. -This call requires read/write permissions. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals SEC\_SET\_VOLTAGE for this command.\\ -secVoltage voltage & The requested bus voltage.\\ -}{ -ENODEV & Device driver not loaded/available.\\ -EBUSY & Device or resource busy.\\ -EINVAL & Invalid argument.\\ -EPERM & File not opened with read permissions.\\ -EINTERNAL & Internal error in the device driver.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex deleted file mode 100644 index 574464d23..000000000 --- a/dvb-spec/dvbapi/title.tex +++ /dev/null @@ -1,24 +0,0 @@ -\pagenumbering{arabic} -\pagestyle{empty} -\title{\huge\textbf{LINUX DVB API}} - -\author{ -\includegraphics{cimlogo.psi}\\ - Convergence integrated media GmbH\\\\ - Dr. Ralph J.K. Metzler\\ - \texttt{}\\\\ - Dr. Marcus O.C. Metzler\\ - \texttt{} -% Rosenthalerstr. 51\\ -% 10178 Berlin\\Germany -} -\date{02/14/2002\\V 0.9.4} -\maketitle - -\newpage - -%\end{titlepage} -% Local Variables: -% mode: latex -% TeX-master: "dvbapi" -% End: diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex deleted file mode 100644 index 2659db238..000000000 --- a/dvb-spec/dvbapi/video.tex +++ /dev/null @@ -1,686 +0,0 @@ -\devsec{DVB Video Device} - -The DVB video device controls the MPEG2 video decoder of the DVB hardware. -It can be accessed through \texttt{/dev/ost/video}. -The include file \texttt{ost/video.h} defines the data types and lists -all I/O calls. Please note that some DVB cards don't have their own -MPEG decoder, which results in the omission of the audio and video -device as well as the video4linux device. - -\devsubsec{Video Data Types} - -\devsubsubsec{videoFormat\_t} -\label{videoformat} - -The \texttt{videoFormat\_t} data type defined by -\begin{verbatim} -typedef enum { - VIDEO_FORMAT_4_3, - VIDEO_FORMAT_16_9 -} videoFormat_t; -\end{verbatim} -is used in the VIDEO\_SET\_FORMAT function (\ref{videosetformat}) to -tell the driver which aspect ratio the output hardware (e.g. TV) has. -It is also used in the data structures videoStatus (\ref{videostatus}) -returned by VIDEO\_GET\_STATUS (\ref{videogetstatus}) and -videoEvent (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) -which report about the display format of the current video stream. - -\devsubsubsec{videoDisplayFormat\_t} -\label{videodispformat} - -In case the display format of the video stream and of the -display hardware differ the application has to specify how to handle -the cropping of the picture. -This can be done using the VIDEO\_SET\_DISPLAY\_FORMAT call -(\ref{videosetdisplayformat}) which accepts -\begin{verbatim} -typedef enum { - VIDEO_PAN_SCAN, - VIDEO_LETTER_BOX, - VIDEO_CENTER_CUT_OUT -} videoDisplayFormat_t; -\end{verbatim} -as argument. - - -\devsubsubsec{video stream source} -\label{videostreamsource} -The video stream source is set through the VIDEO\_SELECT\_SOURCE -call and can take the following values, depending on whether we are -replaying from an internal (demuxer) or external (user write) source. -\begin{verbatim} -typedef enum { - VIDEO_SOURCE_DEMUX, - VIDEO_SOURCE_MEMORY -} videoStreamSource_t; -\end{verbatim} -VIDEO\_SOURCE\_DEMUX selects the demultiplexer (fed -either by the frontend or the DVR device) as the source of -the video stream. -If VIDEO\_SOURCE\_MEMORY is selected the stream -comes from the application through the \texttt{write()} -system call. - -\devsubsubsec{video play state} -\label{videoplaystate} -The following values can be returned by the VIDEO\_GET\_STATUS call -representing the state of video playback. -\begin{verbatim} -typedef enum { - VIDEO_STOPPED, - VIDEO_PLAYING, - VIDEO_FREEZED -} videoPlayState_t; -\end{verbatim} - - -\devsubsubsec{video event} -\label{videoevent} -The following is the structure of a video event as it is returned by -the VIDEO\_GET\_EVENT call. -\begin{verbatim} -struct videoEvent { - int32_t type; - time_t timestamp; - union { - videoFormat_t videoFormat; - } u; -}; -\end{verbatim} - -\devsubsubsec{video status} -\label{videostatus} -The VIDEO\_GET\_STATUS call returns the following structure informing -about various states of the playback operation. -\begin{verbatim} -struct videoStatus { - boolean videoBlank; - videoPlayState_t playState; - videoStreamSource_t streamSource; - videoFormat_t videoFormat; - videoDisplayFormat_t displayFormat; -}; -\end{verbatim} -If videoBlank is set video will be blanked out if the channel is changed or -if playback is stopped. Otherwise, the last picture will be displayed. -playState indicates if the video is currently frozen, stopped, or -being played back. The streamSource corresponds to the seleted source -for the video stream. It can come either from the demultiplexer or from memory. -The videoFormat indicates the aspect ratio (one of 4:3 or 16:9) -of the currently played video stream. -Finally, displayFormat corresponds to the selected cropping mode in case the -source video format is not the same as the format of the output device. - - -\devsubsubsec{video display still picture} -\label{videostill} -An I-frame displayed via the VIDEO\_STILLPICTURE call is passed on -within the following structure. -\begin{verbatim} -/* pointer to and size of a single iframe in memory */ -struct videoDisplayStillPicture { - char *iFrame; - int32_t size; -}; -\end{verbatim} - -\devsubsubsec{video capabilities} -\label{videocaps} -A call to VIDEO\_GET\_CAPABILITIES returns an unsigned integer with -the following bits set according to the hardwares capabilities. -\begin{verbatim} -/* bit definitions for capabilities: */ -/* can the hardware decode MPEG1 and/or MPEG2? */ -#define VIDEO_CAP_MPEG1 1 -#define VIDEO_CAP_MPEG2 2 -/* can you send a system and/or program stream to video device? - (you still have to open the video and the audio device but only - send the stream to the video device) */ -#define VIDEO_CAP_SYS 4 -#define VIDEO_CAP_PROG 8 -/* can the driver also handle SPU, NAVI and CSS encoded data? - (CSS API is not present yet) */ -#define VIDEO_CAP_SPU 16 -#define VIDEO_CAP_NAVI 32 -#define VIDEO_CAP_CSS 64 -\end{verbatim} - - -\devsubsubsec{video system} -\label{videosys} -A call to VIDEO\_SET\_SYSTEM sets the desired video system for TV -output. The following system types can be set: - -\begin{verbatim} -typedef enum { - VIDEO_SYSTEM_PAL, - VIDEO_SYSTEM_NTSC, - VIDEO_SYSTEM_PALN, - VIDEO_SYSTEM_PALNc, - VIDEO_SYSTEM_PALM, - VIDEO_SYSTEM_NTSC60, - VIDEO_SYSTEM_PAL60, - VIDEO_SYSTEM_PALM60 -} videoSystem_t; -\end{verbatim} - - - -\devsubsubsec{video highlights} -\label{vhilite} -Calling the ioctl VIDEO\_SET\_HIGHLIGHTS posts the SPU highlight -information. The call expects the following format for that information: - -\begin{verbatim} -typedef -struct videoHighlight { - boolean active; /* 1=show highlight, 0=hide highlight */ - uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ - /* 3- 0 Background pixel contrast */ - uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */ - /* 3- 0 Emphasis pixel-1 contrast */ - uint8_t color1; /* 7- 4 Pattern pixel color */ - /* 3- 0 Background pixel color */ - uint8_t color2; /* 7- 4 Emphasis pixel-2 color */ - /* 3- 0 Emphasis pixel-1 color */ - uint32_t ypos; /* 23-22 auto action mode */ - /* 21-12 start y */ - /* 9- 0 end y */ - uint32_t xpos; /* 23-22 button color number */ - /* 21-12 start x */ - /* 9- 0 end x */ -} videoHighlight_t; -\end{verbatim} - - -\devsubsubsec{video SPU} -\label{videospu} -Calling VIDEO\_SET\_SPU deactivates or activates SPU decoding, -according to the following format: -\begin{verbatim} -typedef -struct videoSPU { - boolean active; - int streamID; -} videoSPU_t; -\end{verbatim} - - -\devsubsubsec{video SPU palette} -\label{vspupal} -The following structure is used to set the SPU palette by calling VIDEO\_SPU\_PALETTE: -\begin{verbatim} -typedef -struct videoSPUPalette{ /* SPU Palette information */ - int length; - uint8_t *palette; -} videoSPUPalette_t; -\end{verbatim} - -\devsubsubsec{video NAVI pack} -\label{videonavi} -In order to get the navigational data the following structure has to -be passed to the ioctl VIDEO\_GET\_NAVI: -\begin{verbatim} -typedef -struct videoNaviPack{ - int length; /* 0 ... 1024 */ - uint8_t data[1024]; -} videoNaviPack_t; -\end{verbatim} - - -\devsubsubsec{video attributes} -\label{vattrib} -The following attributes can be set by a call to VIDEO\_SET\_ATTRIBUTES: -\begin{verbatim} -typedef uint16_t videoAttributes_t; -/* bits: descr. */ -/* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ -/* 13-12 TV system (0=525/60, 1=625/50) */ -/* 11-10 Aspect ratio (0=4:3, 3=16:9) */ -/* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */ -/* 7 line 21-1 data present in GOP (1=yes, 0=no) */ -/* 6 line 21-2 data present in GOP (1=yes, 0=no) */ -/* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */ -/* 2 source letterboxed (1=yes, 0=no) */ -/* 0 film/camera mode (0=camera, 1=film (625/50 only)) */ -\end{verbatim} - - -\clearpage - -\devsubsec{Video Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - 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 attempts to - open the device in this mode will fail, and an error-code will be returned. - If the Video Device is opened in O\_RDONLY mode, the only ioctl call that can - be used is VIDEO\_GET\_STATUS. All other call will return an error code. - }{ - const char *deviceName & Name of specific video device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ - & \hspace{1em} (blocking mode is the default)\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EINTERNAL & Internal error.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call closes a previously opened video device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\function{write()}{ - size\_t write(int fd, const void *buf, size\_t count);}{ - This system call can only be used if VIDEO\_SOURCE\_MEMORY is selected in the - ioctl call VIDEO\_SELECT\_SOURCE. The data provided shall be in PES - format, unless the capability allows other formats. - If O\_NONBLOCK is not specified the function will block until buffer space is - available. The amount of data to be transferred is implied by count. - }{ - 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.\\ - }{ - 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.\\ -} - - -\ifunction{VIDEO\_STOP}{ - int ioctl(fd, int request = VIDEO\_STOP, boolean mode);}{ - 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. -}{ -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.\\ -}{ -EBADF& fd is not a valid open file descriptor \\ -EINTERNAL & Internal error, possibly in the communication with - the DVB subsystem.\\ -} - -\ifunction{VIDEO\_PLAY}{ - int ioctl(fd, int request = VIDEO\_PLAY);}{ - This ioctl call asks the Video Device to start playing a video stream - from the selected source. -}{ -int fd & File descriptor returned by a previous call to open(). \\ -int request & Equals VIDEO\_PLAY for this command. \\ -}{ -EBADF& fd is not a valid open file descriptor \\ -EINTERNAL & Internal error, possibly in the communication with - the DVB subsystem.\\ -} - - -\ifunction{VIDEO\_FREEZE}{ - int ioctl(fd, int request = VIDEO\_FREEZE);}{ - This ioctl call suspends the live video stream being played. - Decoding and playing are frozen. It is then possible to restart - the decoding and playing process of the video stream using the - VIDEO\_CONTINUE command. If VIDEO\_SOURCE\_MEMORY is selected in the - ioctl call VIDEO\_SELECT\_SOURCE, the DVB subsystem will not decode - any more data until the ioctl call VIDEO\_CONTINUE or VIDEO\_PLAY is - performed. -}{ -int fd & File descriptor returned by a previous call to open(). \\ -int request & Equals VIDEO\_FREEZE for this command. \\ -}{ -EBADF& fd is not a valid open file descriptor \\ -EINTERNAL & Internal error, possibly in the communication with - the DVB subsystem.\\ -} - -\ifunction{VIDEO\_CONTINUE}{ - int ioctl(fd, int request = VIDEO\_CONTINUE);}{ - This ioctl call restarts decoding and playing processes of the video - stream which was played before a call to VIDEO\_FREEZE was made. - }{ - int fd & File descriptor returned by a previous call to open(). \\ - int request & Equals VIDEO\_CONTINUE for this command. \\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error, possibly in the communication with - the DVB subsystem.\\ - } - - -\ifunction{VIDEO\_SELECT\_SOURCE}{ - int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, videoStreamSource\_t source);}{ - This ioctl call informs the video device which source shall be used - for the input data. The possible sources are demux or memory. If - memory is selected, the data is fed to the video device through - the write command. - }{ - 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.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ -} - -\ifunction{VIDEO\_SET\_BLANK}{ - int ioctl(fd, int request = VIDEO\_SET\_BLANK, boolean mode);}{ - This ioctl call asks the Video Device to blank out the picture. -}{ -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.\\ -}{ -EBADF& fd is not a valid open file descriptor \\ -EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ -EINVAL & Illegal input parameter\\ -} - -\ifunction{VIDEO\_GET\_STATUS}{ -\label{videogetstatus} - int ioctl(fd, int request = VIDEO\_GET\_STATUS, struct videoStatus *status);}{ - This ioctl call asks the Video Device to return the current status of the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request& Equals VIDEO\_GET\_STATUS for this command.\\ - struct videoStatus *status & Returns the current status of the Video Device.\\ -}{ -EBADF& fd is not a valid open file descriptor \\ -EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ -EFAULT & status points to invalid address\\ -} - -\ifunction{VIDEO\_GET\_EVENT}{ -\label{videogetevent} - int ioctl(fd, int request = VIDEO\_GET\_EVENT, struct videoEvent *ev);}{ - 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. - }{ - 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.\\ -}{ -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.\\ -} - -\ifunction{VIDEO\_SET\_DISPLAY\_FORMAT}{ -\label{videosetdisplayformat} - int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, videoDisplayFormat\_t format);}{ - This ioctl call asks the Video Device to select the video format to be applied - by the MPEG chip on the video. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_DISPLAY\_FORMAT for this command.\\ - videoDisplayFormat\_t format & Selects the video format to be used.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error.\\ - EINVAL & Illegal parameter format.\\ -} - -\ifunction{VIDEO\_STILLPICTURE}{ - int ioctl(fd, int request = VIDEO\_STILLPICTURE, struct videoDisplayStillPicture *sp);}{ - 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. - }{ - 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.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error.\\ - EFAULT & sp points to an invalid iframe.\\ -} - -\ifunction{VIDEO\_FAST\_FORWARD}{ - int ioctl(fd, int request = VIDEO\_FAST\_FORWARD, int nFrames);}{ - This ioctl call asks the Video Device to skip decoding of N number of I-frames. - This call can only be used if VIDEO\_SOURCE\_MEMORY is selected. - }{ - 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.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error.\\ - EPERM & Mode VIDEO\_SOURCE\_MEMORY not selected.\\ - EINVAL & Illegal parameter format.\\ -} - -\ifunction{VIDEO\_SLOWMOTION}{ - int ioctl(fd, int request = VIDEO\_SLOWMOTION, int nFrames);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SLOWMOTION for this command.\\ - int nFrames & The number of times to repeat each frame.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINTERNAL & Internal error.\\ - EPERM & Mode VIDEO\_SOURCE\_MEMORY not selected.\\ - EINVAL & Illegal parameter format.\\ -} - -\ifunction{VIDEO\_GET\_CAPABILITIES}{ - int ioctl(fd, int request = VIDEO\_GET\_CAPABILITIES, unsigned int *cap);}{ - This ioctl call asks the video device about its decoding capabilities. - On success it returns and integer which has bits set according to the - defines in section \ref{videocaps}. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_GET\_CAPABILITIES for this command.\\ - unsigned int *cap & Pointer to a location where to store the - capability information.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EFAULT & cap points to an invalid iframe.\\ -} - -\ifunction{VIDEO\_SET\_ID}{ - int ioctl(int fd, int request = VIDEO\_SET\_ID, int id);}{ - This ioctl selects which sub-stream is to be decoded if a program or - system stream is sent to the video device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_ID for this command.\\ - int id& video sub-stream id - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINTERNAL & Internal error.\\ - EINVAL & Invalid sub-stream id. -} - -\ifunction{VIDEO\_CLEAR\_BUFFER}{ - int ioctl(fd, int request = VIDEO\_CLEAR\_BUFFER);}{ - This ioctl call clears all video buffers in the driver and - in the decoder hardware. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_CLEAR\_BUFFER for this command.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ -} - -\ifunction{VIDEO\_SET\_STREAMTYPE}{ - int ioctl(fd, int request = VIDEO\_SET\_STREAMTYPE, int type);}{ - This ioctl tells the driver which kind of stream to expect - being written to it. If this call is not used the default of video PES - is used. Some drivers might not support this call and always expect PES. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_STREAMTYPE for this command.\\ - int type & stream type\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& type is not a valid or supported stream type.\\ -} - -\ifunction{VIDEO\_SET\_FORMAT}{ -\label{videosetformat} - int ioctl(fd, int request = VIDEO\_SET\_FORMAT, videoFormat\_t format); -}{ - This ioctl sets the screen format (aspect ratio) of the connected - output device (TV) so that the output of the decoder can - be adjusted accordingly. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_FORMAT for this command.\\ - videoFormat\_t format& video format of TV as defined in section \ref{videoformat}.\\ - }{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& format is not a valid video format.\\ -} - -\ifunction{VIDEO\_SET\_SYSTEM}{ -\label{videosetsystem} - int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , videoSystem\_t system); -}{ - This ioctl sets the television output format. The format (see section - \ref{videosys}) may vary from the color format of the displayed MPEG - stream. If the hardware is not able to display the requested format - the call will return an error. -}{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_FORMAT for this command.\\ - videoSystem\_t system& video system of TV output.\\ -}{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& system is not a valid or supported video system.\\ -} - -\ifunction{VIDEO\_SET\_HIGHLIGHT}{ -\label{videosethighlight} - int ioctl(fd, int request = VIDEO\_SET\_HIGHLIGHT ,videoHighlight\_t *vhilite) -}{ - This ioctl sets the SPU highlight information for the menu access of - a DVD. -}{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_HIGHLIGHT for this command.\\ - videoHighlight\_t *vhilite& SPU Highlight information according to - section \ref{vhilite}.\\ -}{ - EBADF& fd is not a valid open file descriptor. \\ - EINVAL& input is not a valid highlight setting.\\ -} - - -\ifunction{VIDEO\_SET\_SPU}{ -\label{videosetspu} - int ioctl(fd, int request = VIDEO\_SET\_SPU , videoSPU\_t *spu) -}{ - This ioctl activates or deactivates SPU decoding in a DVD input - stream. It can only be used, if the driver is able to handle a DVD - stream. -}{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_SPU for this command.\\ - videoSPU\_t *spu& SPU decoding (de)activation and subid setting - according to section \ref{videospu}.\\ -}{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& input is not a valid spu setting or driver cannot handle SPU.\\ -} - - -\ifunction{VIDEO\_SET\_SPU\_PALETTE}{ -\label{videosetspupalette} - int ioctl(fd, int request = VIDEO\_SET\_SPU\_PALETTE ,videoSPUPalette\_t *palette ) -}{ - This ioctl sets the SPU color palette. -}{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_SPU\_PALETTE for this command.\\ - videoSPUPalette\_t *palette& SPU palette according to section \ref{vspupal}.\\ -}{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& input is not a valid palette or driver doesn't handle SPU.\\ -} - - - -\ifunction{VIDEO\_GET\_NAVI}{ -\label{videosetnavi} - int ioctl(fd, int request = VIDEO\_GET\_NAVI , videoNaviPack\_t *navipack) -}{ - This ioctl returns navigational information from the DVD stream. This is - especially needed if an encoded stream has to be decoded by the hardware. -}{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_GET\_NAVI for this command.\\ - videoNaviPack\_t *navipack& PCI or DSI pack (private stream 2) - according to section \ref{videonavi}.\\ -}{ - EBADF& fd is not a valid open file descriptor \\ - EFAULT& driver is not able to return navigational information\\ -} - - -\ifunction{VIDEO\_SET\_ATTRIBUTES}{ -\label{videosetattributes} - int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,videoAttributes\_t - vattr) -}{ - This ioctl is intended for DVD playback and allows you to set - certain information about the stream. Some hardware may not need - this information, but the call also tells the hardware to prepare - for DVD playback. -}{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals VIDEO\_SET\_ATTRIBUTE for this command.\\ - videoAttributes\_t vattr& video attributes according to section \ref{vattrib}.\\ -}{ - EBADF& fd is not a valid open file descriptor \\ - EINVAL& input is not a valid attribute setting.\\ -} - - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: -- cgit v1.2.3 From 5a523e605b9b6d1ae50d0707c1874c5b7f0959cc Mon Sep 17 00:00:00 2001 From: holger Date: Thu, 10 Oct 2002 16:22:27 -0300 Subject: the new HEAD --- dvb-spec/HOWTO-use-the-frontend-api | 189 +++++++ dvb-spec/README.CABLE | 5 + dvb-spec/README.EON | 7 + dvb-spec/README.valgrind | 13 + dvb-spec/channel | 104 ++++ dvb-spec/dvbapi/.cvsignore | 11 + dvb-spec/dvbapi/Makefile | 30 ++ dvb-spec/dvbapi/audio.tex | 442 +++++++++++++++ dvb-spec/dvbapi/bibsection.sty | 29 + dvb-spec/dvbapi/ca.tex | 127 +++++ dvb-spec/dvbapi/cimlogo.psi | 122 +++++ dvb-spec/dvbapi/demux.tex | 392 ++++++++++++++ dvb-spec/dvbapi/devices.tex | 12 + dvb-spec/dvbapi/dvbapi.tex | 166 ++++++ dvb-spec/dvbapi/dvbstb.fig | 59 ++ dvb-spec/dvbapi/examples.tex | 366 +++++++++++++ dvb-spec/dvbapi/fig2pstex | 6 + dvb-spec/dvbapi/frontend.tex | 630 ++++++++++++++++++++++ dvb-spec/dvbapi/getbb | 12 + dvb-spec/dvbapi/intro.tex | 183 +++++++ dvb-spec/dvbapi/kdapi.tex | 1007 +++++++++++++++++++++++++++++++++++ dvb-spec/dvbapi/sec.tex | 282 ++++++++++ dvb-spec/dvbapi/title.tex | 24 + dvb-spec/dvbapi/video.tex | 686 ++++++++++++++++++++++++ dvb-spec/valgrind-1.0pre3-dvb.patch | 154 ++++++ 25 files changed, 5058 insertions(+) create mode 100644 dvb-spec/HOWTO-use-the-frontend-api create mode 100644 dvb-spec/README.CABLE create mode 100644 dvb-spec/README.EON create mode 100644 dvb-spec/README.valgrind create mode 100644 dvb-spec/channel create mode 100644 dvb-spec/dvbapi/.cvsignore create mode 100644 dvb-spec/dvbapi/Makefile create mode 100644 dvb-spec/dvbapi/audio.tex create mode 100644 dvb-spec/dvbapi/bibsection.sty create mode 100644 dvb-spec/dvbapi/ca.tex create mode 100644 dvb-spec/dvbapi/cimlogo.psi create mode 100644 dvb-spec/dvbapi/demux.tex create mode 100644 dvb-spec/dvbapi/devices.tex create mode 100644 dvb-spec/dvbapi/dvbapi.tex create mode 100644 dvb-spec/dvbapi/dvbstb.fig create mode 100644 dvb-spec/dvbapi/examples.tex create mode 100755 dvb-spec/dvbapi/fig2pstex create mode 100644 dvb-spec/dvbapi/frontend.tex create mode 100755 dvb-spec/dvbapi/getbb create mode 100644 dvb-spec/dvbapi/intro.tex create mode 100644 dvb-spec/dvbapi/kdapi.tex create mode 100644 dvb-spec/dvbapi/sec.tex create mode 100644 dvb-spec/dvbapi/title.tex create mode 100644 dvb-spec/dvbapi/video.tex create mode 100644 dvb-spec/valgrind-1.0pre3-dvb.patch diff --git a/dvb-spec/HOWTO-use-the-frontend-api b/dvb-spec/HOWTO-use-the-frontend-api new file mode 100644 index 000000000..52bc2836e --- /dev/null +++ b/dvb-spec/HOWTO-use-the-frontend-api @@ -0,0 +1,189 @@ + +------------------------------------------------------------------------------- + +What has changed since the old Nokia OST API? + + file naming: + - /dev/ost directory is now called /dev/dvb + - each DVB adapter has it's own directory /dev/dvb/adapterX + - here you'll find a number of frontend devices /dev/dvb/adapterX/frontendY + - driver header directory is located now in /usr/include/linux/dvb/ + - we have a linux/dvb/version.h file, this is included by all headers which + don't use the original OST API anymore + + struct naming: + - we follow the kernel naming scheme and try to get the namespace clean, + these changes are mostly syntactical + + DiSEqC: + - DiSEqC 2.0 ioctls + - the sec-device is gone, DiSEqC ioctls are passed to the frontend + filedescriptor - this matches the hardware better + - the old secCmdSequence is replaced by lowlevel FE_DISEQC_XXX ioctls, + this allows asynchronous DiSEqC, DiSEqC 2.0 and more flexibility for + cascaded devices and exotic setup + + frontend events: + - the event struct is simplified, you get an event now whenever one of the + frontend status bits changes + + ioctls: + - FE_SELFTEST is gone, was a noop anyway + - FE_GET_NEXT_FREQUENCY and FE_GET_NEXT_SYMBOL_RATE are gone, + this information can be obtained with FE_GET_INFO + - FE_SET_POWER_STATE is gone, powermanagement is done implicitly by device + open()/close() calls + +------------------------------------------------------------------------------- + +How to determine the API version? + + Check in your configure script for #include , + include it and check the DVB_API_VERSION #define. + + Currently we use version 2, it will be incremented whenever an API change + meets the CVS main branch. + +------------------------------------------------------------------------------- + +What do you have to do to set up a your frontend? + + First you should try to determine the type of your frontend. + + struct dvb_frontend_info info; + int fd; + + if ((fd = open ("/dev/dvb/adapter0/frontend0", O_RDWR)) < 0) { + perror ("open failed"); + return -1; + } + + ioctl (fd, FE_GET_INFO, &info); + + Now the info.type field contains either FE_QPSK for a satellite frontend, + FE_QAM for a cable frontend or FE_OFDM for a terrestrial frontend. + + The info.name field contains a human readable vendor string of your frontend. + You might want to show this in your GUI to make support easier. + + The info struct also contains the frequency limits, frontend capabilities, + the frequency and symbol rate tolerance the AFC or timing recovery loop can + compensate and some fields you are not interested in. + +------------------------------------------------------------------------------- + +How to set up a cable or terrestrial frontend? + + Fill a dvb_frontend_parameters struct according to the data in your channel + list. For cable frontends, you have to fill the qam field of the union, for + terrestrial frontends it's the ofdm field. + + Apply it using the FE_SET_FRONTEND_PARAMETERS ioctl. That's all. + +------------------------------------------------------------------------------- + +How to set up a satellite frontend? + + Before you set the frontend parameters you have to setup DiSEqC switches and + the LNB. Modern LNB's switch their polarisation depending of the DC component + of their input (13V for vertical polarisation, 18V for horizontal). When they + see a 22kHz signal at their input they switch into the high band and use a + somewhat higher intermediate frequency to downconvert the signal. + + When your satellite equipment contains a DiSEqC switch device to switch + between different satellites you have to send the according DiSEqC commands, + usually command 0x38. Take a look into the DiSEqC spec available at + http://www.eutelsat.org/ for the complete list of commands. + + The burst signal is used in old equipments and by cheap satellite A/B + switches. + + Voltage, burst and 22kHz tone have to be consistent to the values encoded in + the DiSEqC commands. + + The complete sequence to set up switch and LNB according to the DiSEqC spec + looks like this: + + - stop continous tone + - setup polarisation voltage + - wait at least 15ms. + - send your DiSEqC commands using the FE_DISEQC_SEND_MASTER_CMD ioctl + - wait another 15ms + - send burst + - wait 15ms + - start the 22kHz tone when you tune to a transponder in the high band + + You can copy'n'paste this code sniplets from szap.c or diseqc.c, both + test programs are distributed with the linuxtv DVB driver source. All + DiSEqC related ioctls are passed to the frontend device filedescriptor. + + Depending on the equipment setup, you may or may not have to repeat the + DiSEqC commands (only commands, not the whole sequence) for cascaded devices + and can pack committed/uncommitted switch messages. See the DiSEqC spec for + details. + + In an advanced program, you probably want to send this sequence using an + asynchonous thread. Since sleep() and similiar calls are pthread + cancellation points, it's really simple to stop a running DiSEqC thread + before submitting a new sequence. + + Now you have set up switch and LNB, a valid RF signal of the requested + satellite should be at the input of the demodulator. + + Fill a dvb_frontend_parameters struct using the qpsk field in the union and + apply it using the FE_SET_FRONTEND_PARAMETERS ioctl. + +------------------------------------------------------------------------------- + +How do I check the frontend status? + + You can perform a poll()/select() on the frontend file descriptor. Whenever + one of the frontend status bits toggles the poll returns. Now you can + submit the FE_GET_EVENT ioctl to receive the new status bits. When you used + one of the XXX_AUTO parameters you might want to use the event.parameters + field to determine the correct tuned parameters and update your channel list. + + If you want to simulate the old FE_FAILURE_EV frontend event behaviour you + should check the FE_TIMEDOUT bit, this will be set when the tuning was not + successful within a few seconds. + + When you get a FE_REINIT event the frontend was reinitialized. You should + send the DiSEqC sequence again if you use a QPSK frontend. + + The FE_READ_SIGNAL_STRENGTH ioctl will fill the signal strength into the + 16 LSBs of the passed argument. The signal strength range is from 0 (bad) + to 65535 (too good to be true). + + FE_READ_SNR returns the signal noise ratio. range 0 (bad) to 65535 (not real). + For both the signal strength and signal noise ratio a value of about 60-70% + means a good signal. + + Not all FE_READ_XXX ioctl()s are supported by all hardware. Check the ioctl + return value, if it's less than 0 this ioctl is not supported. + +------------------------------------------------------------------------------- + +What does FE_ENABLE_HIGH_LNB_VOLTAGE? + + some STBs (the dbox2 for example) support somewhat higher LNB voltages than + 13 and 18V. They add about 0.5V to compensate voltage drop on long cables. + + This ioctl is not supported on all boxes. You probably want to show an extra + menu item in your GUI when this ioctl returns a zero value. + +------------------------------------------------------------------------------- + +How to do powermanagement, the FE_SET_POWER_STATE ioctls are gone? + + An open() call on the frontend device powers up and initializes the + demodulator and switches on LNB power if necessairy. The DiSEqC bus won't + be resetted, do this manually if you think you need to. + + Some seconds after the device is closed (and was not opened by a new process) + LNB power and the demodulator are shut down into sleep mode. + + You can configure the shutdown timeout using the shutdown_timeout module + parameter. To disable power management set shutdown_timeout=0. + +------------------------------------------------------------------------------- + diff --git a/dvb-spec/README.CABLE b/dvb-spec/README.CABLE new file mode 100644 index 000000000..de13af020 --- /dev/null +++ b/dvb-spec/README.CABLE @@ -0,0 +1,5 @@ +- The analog module is not fully supported yet. + The MSP3400 module will have to be extended to handle then audio and + video switching for the module. + If you want sound you will have to remove the module for now. + diff --git a/dvb-spec/README.EON b/dvb-spec/README.EON new file mode 100644 index 000000000..df5098132 --- /dev/null +++ b/dvb-spec/README.EON @@ -0,0 +1,7 @@ +- If you do not receive any packets over the dvb0 device the reason could + be the rp_filter. + Check if your distribution enables this or disable it with: + + "echo 0 > /proc/sys/net/ipv4/conf/dvb0/rp_filter" + + This disables source validation by reversed path lookup. \ No newline at end of file diff --git a/dvb-spec/README.valgrind b/dvb-spec/README.valgrind new file mode 100644 index 000000000..c1ce7c994 --- /dev/null +++ b/dvb-spec/README.valgrind @@ -0,0 +1,13 @@ +valgrind-1.0pre3-dvb.patch enables checking correct usage +of the the Linux DVB API ioctls with valgrind +(http://developer.kde.org/~sewardj/). Or, more to the point, +it allows you to check your DVB software with valgrind +without getting all those "unknown ioctl" warnings. + +Notes: +- only frontend and demux ioctls are currently implemented +- some ioctls take structs as arguments; due to padding, valgrind + will complain about uninitialized data passed to the ioctl unless + you memset() the whole struct to some defined value + +Johannes Stezenbach diff --git a/dvb-spec/channel b/dvb-spec/channel new file mode 100644 index 000000000..f17e8cb19 --- /dev/null +++ b/dvb-spec/channel @@ -0,0 +1,104 @@ +This file describes the format of the new channel config file. + +Comments start with # +Each section starts with one of the identifiers: LNB, DISEQC, ROTOR, ... + +IDs are either the official transponder, network, etc. id if it exists +and is unique, otherwise it is just a consecutive number assigned by +the application. +An LNB can also describe a cable TV outlet or a terrestrial antenna. +Names (as all parameters in brackets) are optional. In this case the +application should use the ID as name. + +The application should offer selection sorted by channel number, network, +satellite, bouquet. + + +# satellite definition +SAT + ID satid # ID = xxxy, sat is at position xxx.y degrees + [NAME name] + LNBID lnbid # LNB this sat is received with + [ROTORID rotorid] # rotor commands to position it on this sat + +# LNB definition +LNB + ID lnbid + [NAME name] + [INPUT input] # input of card which the lnb is connected to (default 0) + TYPE type # LNB, CATV or terrestrial antenna? + LOF1 offset1 # local oscillator frequency 1 + LOF2 offset2 # local oscillator frequency 2 + SLOF switchfreq # switching frequency + [DISEQCNR diseqcnr] # simple 2- or 4-switch DiSEqC + [DISEQCID diseqcid] + [INPUT input] + [SWITCHID switchid] + +# A transponder definition +TRANSPONDER + ID tpid + TYPE type # digital (DVB-S(1), C(2) or T(3)) or analog(0) ? + SATID satid + [NAME name] # if analog this is the channel name + FREQ freq + POL H/V + [QAM qam] # only needed if DVB-C + [SRATE sr] # only if DVB + [FEC fec] # only if DVB + [PICID picid] # picture attributes for all channels on this transponder + +# channel definition (only if DVB) +CHANNEL + ID channelid + [NAME name] + TPID tpid + TYPE type + PNR pnr + VPID vpid + APID apid + TPID tpid + [PMTPID pmtpid] + [PCRPID pcrpid] + [APID apid2 APID apid3 ... APID apidn] # more audio PIDs for several languages + [AC3PID ac3] + [NETWID networkid] + [BOUQID bouquetid] + [PICID picid] + +# network definition +NETWORK + ID nwid + [NAME name] + +# bouquet definition +BOUQUET + ID bqid + [NAME name] + + + +# These will be implemented later + +# DiSEqC command sequence +DISEQC + ID disid + [NAME name] + MESSAGE data1 [ ... datan ] BURST 0/1 END + [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] + +# DiSEqC switch +SWITCH + ID switchid + SWITCHID switchid # next "higher" switch + [NAME name] + MESSAGE data1 [ ... datan ] BURST 0/1 END + + +# DiSEqC rotor command sequence leading to a certain rotor position +ROTOR + ID rotid + POS degrees + MESSAGE data1 [ ... datan ] BURST 0/1 END + [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] + diff --git a/dvb-spec/dvbapi/.cvsignore b/dvb-spec/dvbapi/.cvsignore new file mode 100644 index 000000000..fb6974f6b --- /dev/null +++ b/dvb-spec/dvbapi/.cvsignore @@ -0,0 +1,11 @@ +dvbapi.ps +dvbstb.ps +dvbstb.pst +dvbapi.bbl +dvbapi.aux +dvbapi.blg +dvbapi.dvi +dvbapi.log +dvbapi.pdf +dvbapi.out +dvbapi.toc diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile new file mode 100644 index 000000000..aae688f33 --- /dev/null +++ b/dvb-spec/dvbapi/Makefile @@ -0,0 +1,30 @@ +all: dvbapi.ps dvbapi.pdf + +TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex sec.tex frontend.tex \ + intro.tex title.tex dvbstb.ps + +dvbapi.pdf: dvbapi.dvi + dvipdf -o $@ $< + +dvbapi.ps: dvbapi.dvi + dvips -o $@ $< + +dvbapi.dvi: dvbapi.bbl $(TEXS) + -latex dvbapi + -bibtex dvbapi + -makeindex dvbapi + -latex dvbapi + -latex dvbapi + +dvbapi.bbl: $(TEXS) + -latex dvbapi + -bibtex dvbapi + -makeindex dvbapi + +%.ps: %.fig + ./fig2pstex $< + +clean: + rm -f dvbapi.dvi + rm -f *.aux *.bbl *.blg *.idx *.ilg *.ind *.log *.out *.toc + rm -f *.pdf *.pst *.ps diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex new file mode 100644 index 000000000..7b6427094 --- /dev/null +++ b/dvb-spec/dvbapi/audio.tex @@ -0,0 +1,442 @@ +\devsec{DVB Audio Device} + +The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. +It can be accessed through \texttt{/dev/ost/audio}. + + +\devsubsec{Audio Data Types} + +This section describes the structures, data types and defines used when +talking to the audio device. + +\devsubsubsec{audioStreamSource\_t} +\label{audiostreamsource} +The audio stream source is set through the AUDIO\_SELECT\_SOURCE +call and can take the following values, depending on whether we are +replaying from an internal (demuxer) or external (user write) source. +\begin{verbatim} +typedef enum { + AUDIO_SOURCE_DEMUX, + AUDIO_SOURCE_MEMORY +} audio_stream_source_t; +\end{verbatim} +AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed +either by the frontend or the DVR device) as the source of +the video stream. +If AUDIO\_SOURCE\_MEMORY is selected the stream +comes from the application through the \texttt{write()} +system call. + +\devsubsubsec{audioPlayState\_t} +The following values can be returned by the AUDIO\_GET\_STATUS call +representing the state of audio playback. +\label{audioplaystate} +\begin{verbatim} +typedef enum { + AUDIO_STOPPED, + AUDIO_PLAYING, + AUDIO_PAUSED +} audio_play_state_t; +\end{verbatim} + +\devsubsubsec{audioChannelSelect\_t} +\label{audiochannelselect} +The audio channel selected via AUDIO\_CHANNEL\_SELECT is determined by +the following values. +\begin{verbatim} +typedef enum { + AUDIO_STEREO, + AUDIO_MONO_LEFT, + AUDIO_MONO_RIGHT, +} audio_channel_select_t; +\end{verbatim} + +\devsubsubsec{audio_status\_t} +\label{audiostatus} +The AUDIO\_GET\_STATUS call returns the following structure informing +about various states of the playback operation. +\begin{verbatim} +typedef struct audio_status { + boolean AV_sync_state; + boolean mute_state; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; + boolean bypass_mode; +} audio_status_t; +\end{verbatim} + +\devsubsubsec{audio_mixer\_t} +\label{audiomixer} +The following structure is used by the AUDIO\_SET\_MIXER call to set +the audio volume. +\begin{verbatim} +typedef struct audio_mixer { + unsigned int volume_left; + unsigned int volume_right; +} audio_mixer_t; +\end{verbatim} + +\devsubsubsec{audio encodings} +\label{audiotypes} +A call to AUDIO\_GET\_CAPABILITIES returns an unsigned integer with +the following bits set according to the hardwares capabilities. +\begin{verbatim} +#define AUDIO_CAP_DTS 1 +#define AUDIO_CAP_LPCM 2 +#define AUDIO_CAP_MP1 4 +#define AUDIO_CAP_MP2 8 +#define AUDIO_CAP_MP3 16 +#define AUDIO_CAP_AAC 32 +#define AUDIO_CAP_OGG 64 +#define AUDIO_CAP_SDDS 128 +#define AUDIO_CAP_AC3 256 +\end{verbatim} + + +\devsubsubsec{audio karaoke} +\label{audiokaraoke} +The ioctl AUDIO\_SET\_KARAOKE uses the following format: +\begin{verbatim} +typedef +struct audio_karaoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ + int vocal1; /* into left and right t at 70% each */ + int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets */ + int melody; /* mixed into the left channel and */ + /* Vocal2 into the right channel at 100% each. */ + /* if Melody is non-zero, the melody channel gets mixed */ /* into left and right */ +} audio_karaoke_t; +\end{verbatim} + +\devsubsubsec{audio attributes} +\label{aattrib} +The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES: +\begin{verbatim} +typedef uint16_t audio_attributes_t; +/* bits: descr. */ +/* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ +/* 12 multichannel extension */ +/* 11-10 audio type (0=not spec, 1=language included) */ +/* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */ +/* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */ +/* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */ +/* 2- 0 number of audio channels (n+1 channels) */ +\end{verbatim} + + +\clearpage + +\devsubsec{Audio Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + 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 error code will be returned. + If the Audio Device is opened in O\_RDONLY mode, the only ioctl call that can + be used is AUDIO\_GET\_STATUS. All other call will return with an error code. + }{ + const char *deviceName & Name of specific audio device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened audio device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\function{write()}{ + size\_t write(int fd, const void *buf, size\_t count);}{ + 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. + }{ + 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.\\ + }{ + EPERM& Mode AUDIO\_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.\\ +} + +\ifunction{AUDIO\_STOP}{ + int ioctl(int fd, int request = AUDIO\_STOP);}{ + This ioctl call asks the Audio Device to stop playing the current stream. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals AUDIO\_STOP for this command. + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_PLAY}{ + int ioctl(int fd, int request = AUDIO\_PLAY);}{ + This ioctl call asks the Audio Device to start playing an audio stream + from the selected source. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals AUDIO\_PLAY for this command. + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_PAUSE}{ + int ioctl(int fd, int request = AUDIO\_PAUSE);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals AUDIO\_PAUSE for this command. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_SELECT\_SOURCE}{ + int ioctl(int fd, int request = AUDIO\_SELECT\_SOURCE, + audioStreamSource\_t source);}{ + 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. + }{ + 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. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_SET\_MUTE}{ + int ioctl(int fd, int request = AUDIO\_SET\_MUTE, boolean state);}{ + This ioctl call asks the audio device to mute the stream that is + currently being played. + }{ + 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 Un-mute\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_SET\_AV\_SYNC}{ + int ioctl(int fd, int request = AUDIO\_SET\_AV\_SYNC, boolean state);}{ + This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization. + }{ + 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 + synchronization shall be ON or OFF.\\ + & TRUE AV-sync ON \\ + & FALSE AV-sync OFF\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_SET\_BYPASS\_MODE}{ + int ioctl(int fd, int request = AUDIO\_SET\_BYPASS\_MODE, boolean mode);}{ + This ioctl call asks the Audio Device to bypass the Audio decoder and forward + the stream without decoding. This mode shall be used if streams that can't be + handled by the DVB system shall be decoded. + Dolby DigitalTM streams are automatically forwarded by the DVB + subsystem if the hardware can handle it. + }{ + 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\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter. +} + +\ifunction{AUDIO\_CHANNEL\_SELECT}{ + int ioctl(int fd, int request = AUDIO\_CHANNEL\_SELECT, + audioChannelSelect\_t);}{ + This ioctl call asks the Audio Device to select the requested channel + if possible. + }{ + 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 left/right, stereo). + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal input parameter ch. +} + +\ifunction{AUDIO\_GET\_STATUS}{ + int ioctl(int fd, int request = AUDIO\_GET\_STATUS, + struct audio_status *status);}{ + This ioctl call asks the Audio Device to return the current state + of the Audio Device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_GET\_STATUS for this command.\\ + struct audio_status *status & Returns the current state of Audio Device. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EFAULT & status points to invalid address. +} + +\ifunction{AUDIO\_GET\_CAPABILITIES}{ + int ioctl(int fd, int request = AUDIO\_GET\_CAPABILITIES, + unsigned int *cap);}{ + This ioctl call asks the Audio Device to tell us about the + decoding capabilities of the audio hardware. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_GET\_CAPABILITIES for this command.\\ + unsigned int *cap & Returns a bit array of supported sound formats. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EFAULT & cap points to an invalid address. +} + +\ifunction{AUDIO\_CLEAR\_BUFFER}{ + int ioctl(int fd, int request = AUDIO\_CLEAR\_BUFFER);}{ + This ioctl call asks the Audio Device to clear all software + and hardware buffers of the audio decoder device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_CLEAR\_BUFFER for this command. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error. +} + +\ifunction{AUDIO\_SET\_ID}{ + int ioctl(int fd, int request = AUDIO\_SET\_ID, int id);}{ + This ioctl selects which sub-stream is to be decoded if a program or + system stream is sent to the video device. If no audio stream type is set + the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for + AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow + for other stream types. If the stream type is set the id just + specifies the substream id of the audio stream and only the first 5 + bits are recognized. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_ID for this command.\\ + int id& audio sub-stream id + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Invalid sub-stream id. +} + +\ifunction{AUDIO\_SET\_MIXER}{ + int ioctl(int fd, int request = AUDIO\_SET\_MIXER, audio_mixer\_t *mix);}{ + This ioctl lets you adjust the mixer settings of the audio decoder. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_ID for this command.\\ + audio_mixer\_t *mix& mixer settings. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EFAULT & mix points to an invalid address. +} + +\ifunction{AUDIO\_SET\_STREAMTYPE}{ + int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, int type);}{ + This ioctl tells the driver which kind of audio stream to expect. + This is useful if the stream offers several audio sub-streams + like LPCM and AC3. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ + int type & stream type\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& type is not a valid or supported stream type.\\ +} + + +\ifunction{AUDIO\_SET\_EXT\_ID}{ + int ioctl(fd, int request = AUDIO\_SET\_EXT\_ID, int id);}{ + This ioctl can be used to set the extension id for MPEG streams in + DVD playback. Only the first 3 bits are recognized. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_EXT\_ID for this command.\\ + int id & audio sub\_stream\_id\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& id is not a valid id.\\ +} + +\ifunction{AUDIO\_SET\_ATTRIBUTES}{ + int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audioAttributes\_t attr );}{ + This ioctl is intended for DVD playback and allows you to set + certain information about the audio stream. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_ATTRIBUTES for this command.\\ + iaudioAttributes\_t attr & audio attributes according to section \ref{aattrib}\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& attr is not a valid or supported attribute setting.\\ +} + +\ifunction{AUDIO\_SET\_KARAOKE}{ + int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, audio_karaoke\_t *karaoke);}{ + This ioctl allows one to set the mixer settings for a karaoke DVD. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ + audio_karaoke\_t *karaoke & karaoke settings according to section \ref{audiokaraoke}.\\ + }{ + EBADF & fd is not a valid open file descriptor \\ + EINVAL& karaoke is not a valid or supported karaoke setting.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/bibsection.sty b/dvb-spec/dvbapi/bibsection.sty new file mode 100644 index 000000000..7f9eedc6a --- /dev/null +++ b/dvb-spec/dvbapi/bibsection.sty @@ -0,0 +1,29 @@ +\def\thebibliography#1{\chapter*{\bibname\@mkboth + {\uppercase{\bibname}}{\uppercase{\bibname}}} + \setcounter{chapter}{0} + \setcounter{section}{0} + \def\thechapter{Bib} + \def\thesection{\Alph{section}} + \edef\biblab{#1} + \addcontentsline{toc}{chapter}{\bibname} + } + +\def\bibtitle#1#2{\expandafter\def\csname bibtitle#1\endcsname{ + \bibsection{#2}} } + +\def\bibsection#1{\section{#1} + \begin{list} + {\@biblabel{\arabic{enumiv}}}{\settowidth\labelwidth{\@biblabel{\biblab}}% + \leftmargin\labelwidth + \advance\leftmargin\labelsep + \usecounter{enumiv}% + \let\p@enumiv\@empty + \def\theenumiv{\arabic{enumiv}}}% + \def\newblock{\hskip .11em plus.33em minus.07em}% + \sloppy\clubpenalty4000\widowpenalty4000 + \sfcode`\.=\@m} + +\def\endbibsection{\end{list}} + +\def\endthebibliography{\endbibsection} + diff --git a/dvb-spec/dvbapi/ca.tex b/dvb-spec/dvbapi/ca.tex new file mode 100644 index 000000000..eba512b1b --- /dev/null +++ b/dvb-spec/dvbapi/ca.tex @@ -0,0 +1,127 @@ +\devsec{DVB CA Device} + +The DVB CA device controls the conditional access hardware. +It can be accessed through \texttt{/dev/ost/ca}. + + +\devsubsec{CA Data Types} + +\devsubsubsec{ca\_slot\_info\_t} +\label{caslotinfo} + +\begin{verbatim} +/* slot interface types and info */ + +typedef struct ca_slot_info_s { + int num; /* slot number */ + + int type; /* CA interface this slot supports */ +#define CA_CI 1 /* CI high level interface */ +#define CA_CI_LINK 2 /* CI link layer level interface */ +#define CA_CI_PHYS 4 /* CI physical layer level interface */ +#define CA_SC 128 /* simple smart card interface */ + + unsigned int flags; +#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ +#define CA_CI_MODULE_READY 2 +} ca_slot_info_t; +\end{verbatim} + +\devsubsubsec{ca\_descr\_info\_t} +\label{cadescrinfo} + +\begin{verbatim} +typedef struct ca_descr_info_s { + unsigned int num; /* number of available descramblers (keys) */ + unsigned int type; /* type of supported scrambling system */ +#define CA_ECD 1 +#define CA_NDS 2 +#define CA_DSS 4 +} ca_descr_info_t; +\end{verbatim} + +\devsubsubsec{ca\_cap\_t} +\label{cacap} + +\begin{verbatim} +typedef struct ca_cap_s { + unsigned int slot_num; /* total number of CA card and module slots */ + unsigned int slot_type; /* OR of all supported types */ + unsigned int descr_num; /* total number of descrambler slots (keys) */ + unsigned int descr_type;/* OR of all supported types */ +} ca_cap_t; +\end{verbatim} + + +\devsubsubsec{ca\_msg\_t} +\label{camsg} + +\begin{verbatim} +/* a message to/from a CI-CAM */ +typedef struct ca_msg_s { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; +} ca_msg_t; +\end{verbatim} + + +\devsubsubsec{ca\_descr\_t} +\label{cadescr} + +\begin{verbatim} +typedef struct ca_descr_s { + unsigned int index; + unsigned int parity; + unsigned char cw[8]; +} ca_descr_t; +\end{verbatim} + +\clearpage + +\devsubsec{CA Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named ca device (e.g. /dev/ost/ca) + 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 CA Device in O\_RDWR mode. All other attempts to + open the device in this mode will fail, and an error code will be returned. + }{ + const char *deviceName & Name of specific video device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened audio device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/cimlogo.psi b/dvb-spec/dvbapi/cimlogo.psi new file mode 100644 index 000000000..b7b089a49 --- /dev/null +++ b/dvb-spec/dvbapi/cimlogo.psi @@ -0,0 +1,122 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: /home/rjkm/dvbapi/cimlogo.ps +%%Creator: XV Version 3.10a Rev: 12/29/94 (PNG patch 1.2) - by John Bradley +%%BoundingBox: 275 411 309 440 +%%Pages: 1 +%%DocumentFonts: +%%EndComments +%%EndProlog + +%%Page: 1 1 + +% remember original state +/origstate save def + +% build a temporary dictionary +20 dict begin + +% define string to hold a scanline's worth of data +/pix 45 string def + +% define space for color conversions +/grays 45 string def % space for gray scale line +/npixls 0 def +/rgbindx 0 def + +% lower left corner +275 411 translate + +% size of image (on paper, in 1/72inch coords) +33.76800 28.51200 scale + +45 38 8 % dimensions of data +[45 0 0 -38 0 38] % mapping matrix +{currentfile pix readhexstring pop} +image + +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffffff000000ffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffff0000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffff000000000000ffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffff00ffffffffffff0000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffff0000000000ffffffff000000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffff0000000000000000ffffff000000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffff0000000000000000ffffffff000000000000ffffffffffffffffffff +ffffffffffffffffff +ffffffffffffff000000000000000000ffffff000000000000ffffffffffffffffffffff +ffffffffffffffffff +ffffffffffff0000000000000000ffffffffff000000000000ffffff00000000ffffffff +ffffffffffffffffff +ffffffffff00000000000000ffffffffffffff0000000000ffffff0000000000ffffffff +ffffffffffffffffff +ffffffffff000000000000ffffffffffffff000000000000ffffff000000000000ffffff +ffffffffffffffffff +ffffffff00000000000000ffffffffffffff000000000000ffffffff000000000000ffff +ffffffffffffffffff +ffffffff000000000000ffffffffffffffff000000000000ffffffff000000000000ffff +ffffffffffffffffff +ffffffff0000000000ffffffffffffffff000000000000ffffffffffff0000000000ffff +ffffffffffffffffff +ffffff000000000000ffffffffffffffff000000000000ffffffffffff0000000000ffff +ffffffffffffffffff +ffffff0000000000ffffffffffffffffff000000000000ffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffffff0000000000ffffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffff000000000000ffffffffffffffff0000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffff000000000000ffffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffffff0000000000ffffffffffffffffff0000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffff000000000000ffffffffffffffff000000000000ff +ffffffffffffffffff +ffffff0000000000ffffffffffffff000000000000ffffffffffffffff0000000000ffff +ffffffffffffffffff +ffffff000000000000ffffffffffffff00000000ffffffffffffffffff0000000000ffff +ffffffffffffffffff +ffffffff0000000000ffffffffffffffff0000ffffffffffffffffff000000000000ffff +ffffffffffffffffff +ffffffff000000000000ffffffffffffffffffffffffffffffffffff000000000000ffff +ffffffffffffffffff +ffffffff000000000000ffffffffffffffffffffffffffffffffff000000000000ffffff +ffffffffffffffffff +ffffffffff00000000000000ffffffffffffffffffffffffffff000000000000ffffffff +ff0000000000ffffff +ffffffffff0000000000000000ffffffffffffffffffffffff00000000000000ffffffff +00000000000000ffff +ffffffffffff000000000000000000ffffffffffffffff0000000000000000ffffffffff +00000000000000ffff +ffffffffffffff0000000000000000000000000000000000000000000000ffffffffffff +0000000000000000ff +ffffffffffffffff000000000000000000000000000000000000000000ffffffffffffff +00000000000000ffff +ffffffffffffffffffff0000000000000000000000000000000000ffffffffffffffffff +00000000000000ffff +ffffffffffffffffffffffff00000000000000000000000000ffffffffffffffffffffff +ff0000000000ffffff +ffffffffffffffffffffffffffffff00ff0000000000ffffffffffffffffffffffffffff +ffffff0000ffffffff +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff +ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff +ffffffffffffffffff + +showpage + +% stop using temporary dictionary +end + +% restore original state +origstate restore + +%%Trailer diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex new file mode 100644 index 000000000..3607bbffc --- /dev/null +++ b/dvb-spec/dvbapi/demux.tex @@ -0,0 +1,392 @@ +\devsec{DVB Demux Device} + +The DVB demux device controls the filters of the DVB hardware/software. +It can be accessed through \texttt{/dev/ost/demux}. + +\devsubsec{Demux Data Types} + +\begin{verbatim} +typedef uint16_t dvb_pid_t; +\end{verbatim} + + +\devsubsubsec{dmxOutput\_t} +\label{dmxoutput} + +\begin{verbatim} +typedef enum +{ + DMX_OUT_DECODER, + DMX_OUT_TAP, + DMX_OUT_TS_TAP +} dmx_output_t; +\end{verbatim} +/* Output multiplexed into a new TS */ +/* (to be retrieved by reading from the */ +/* logical DVR device). */ + + +\devsubsubsec{dmxInput\_t} +\label{dmxinput} + +\begin{verbatim} +typedef enum +{ + DMX_IN_FRONTEND, /* Input from a front-end device. */ + DMX_IN_DVR /* Input from the logical DVR device. */ +} dmx_input_t; +\end{verbatim} + + +\devsubsubsec{dmxPesType\_t} +\label{dmxpestype} + +\begin{verbatim} +typedef enum +{ + DMX_PES_AUDIO, + DMX_PES_VIDEO, + DMX_PES_TELETEXT, + DMX_PES_SUBTITLE, + DMX_PES_PCR, + DMX_PES_OTHER +} dmx_pes_type_t; +\end{verbatim} + + +\devsubsubsec{dmx_event\_t} +\label{dmxeventt} + +\begin{verbatim} +typedef enum +{ + DMX_SCRAMBLING_EV, + DMX_FRONTEND_EV +} dmx_event_t; +\end{verbatim} + + +\devsubsubsec{dmxScramblingStatus\_t} +\label{dmxscramblingstatus} + +\begin{verbatim} +typedef enum +{ + DMX_SCRAMBLING_OFF, + DMX_SCRAMBLING_ON +} dmx_scrambling_status_t; +\end{verbatim} + + +\devsubsubsec{dmx_filter\_t} +\label{dmxfilter} + +\begin{verbatim} +typedef struct dmx_filter +{ + uint8_t filter[DMX_FILTER_SIZE]; + uint8_t mask[DMX_FILTER_SIZE]; +} dmx_filter_t; +\end{verbatim} + + +\devsubsubsec{dmx_sct_filter_params} +\label{dmxsctfilterparams} + +\begin{verbatim} +struct dmx_sct_filter_params +{ + dvb_pid_t pid; + dmx_filter_t filter; + uint32_t timeout; + uint32_t flags; +#define DMX_CHECK_CRC 1 +#define DMX_ONESHOT 2 +#define DMX_IMMEDIATE_START 4 +}; +\end{verbatim} + + +\devsubsubsec{dmx_pes_filter_params} +\label{dmxpesfilterparams} + +\begin{verbatim} +struct dmx_pes_filter_params +{ + dvb_pid_t pid; + dmx_input_t input; + dmx_output_t output; + dmx_pes_type_t pesType; + uint32_t flags; +}; +\end{verbatim} + + +\devsubsubsec{dmx_event} +\label{dmxevent} + +\begin{verbatim} +struct dmx_event +{ + dmx_event_t event; + time_t timeStamp; + union + { + dmx_scrambling_status_t scrambling; + } u; +}; +\end{verbatim} + +\clearpage + +\devsubsec{Demux Function Calls} +\function{open()}{ + int open(const char *deviceName, int flags);}{ + 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 functionality. When reading from + this device a transport stream containing the packets from all PES + filters set in the corresponding demux device (/dev/ost/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. + }{ + const char *deviceName & Name of demux device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + 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.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call deactivates and deallocates a filter that was previously + allocated via the open() call. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\function{read()}{ + size\_t read(int fd, void *buf, size\_t count); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + void *buf & Pointer to the buffer to be used for returned filtered data.\\ + size\_t count & Size of buf.\\ + }{ + 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.\\ +} + +\function{write()}{ + ssize\_t write(int fd, const void *buf, size\_t count); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + void *buf & Pointer to the buffer containing the Transport Stream.\\ + size\_t count & Size of buf.\\ + }{ + 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.\\ +} + +\ifunction{DMX\_START}{ + int ioctl( int fd, int request = DMX\_START); + }{ + This ioctl call is used to start the actual filtering operation + defined via the ioctl calls DMX\_SET\_FILTER or DMX\_SET\_PES\_FILTER. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_START for this command.\\ + }{ + 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.\\ +} + +\ifunction{DMX\_STOP}{ + int ioctl( int fd, int request = DMX\_STOP); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_STOP for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ +} + +\ifunction{DMX\_SET\_FILTER}{ + int ioctl( int fd, int request = DMX\_SET\_FILTER, struct dmx_sct_filter_params *params); + }{ + This ioctl call sets up a filter according to the filter and mask + parameters provided. A timeout may be defined stating number of seconds + to wait for a section to be loaded. A value of 0 means that no timeout + should be applied. Finally there is a flag field where it is possible to + state whether a section should be CRC-checked, whether the filter should + be a "one-shot" filter, i.e. if the filtering operation should be stopped + after the first section is received, and whether the filtering operation + should be started immediately (without waiting for a DMX\_START ioctl call). + If a filter was previously set-up, this filter will be canceled, and the + receive buffer will be flushed. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_SET\_FILTER for this command.\\ + struct dmx_sct_filter_params *params + & Pointer to structure containing filter parameters.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EINVAL & Invalid argument.\\ +} + +\ifunction{DMX\_SET\_PES\_FILTER}{ + int ioctl( int fd, int request = DMX\_SET\_PES\_FILTER, + struct dmx_pes_filter_params *params); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_SET\_PES\_FILTER for this command.\\ + struct dmx_pes_filter_params *params + & Pointer to structure containing filter parameters.\\ + }{ + 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.\\ +} + +\ifunction{DMX\_SET\_BUFFER\_SIZE}{ + int ioctl( int fd, int request = DMX\_SET\_BUFFER\_SIZE, unsigned long size); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_SET\_BUFFER\_SIZE for this command.\\ + unsigned long size & Size of circular buffer.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + ENOMEM & The driver was not able to allocate a buffer of the requested size.\\ +} + +\ifunction{DMX\_GET\_EVENT}{ + int ioctl( int fd, int request = DMX\_GET\_EVENT, struct dmx_event *ev); + }{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_GET\_EVENT for this command.\\ + struct dmx_event *ev & Pointer to the location where the event is to be stored.\\ + }{ + 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.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/devices.tex b/dvb-spec/dvbapi/devices.tex new file mode 100644 index 000000000..9c561e853 --- /dev/null +++ b/dvb-spec/dvbapi/devices.tex @@ -0,0 +1,12 @@ +\input{video.tex} +\input{audio.tex} +\input{frontend.tex} +\input{sec.tex} +\input{demux.tex} +\input{ca.tex} +\input{kdapi.tex} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex new file mode 100644 index 000000000..ad0251c01 --- /dev/null +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -0,0 +1,166 @@ +\documentclass[10pt]{book} +\usepackage[dvips,colorlinks=true]{hyperref} + +\usepackage{times} + +%\usepackage[hang]{caption} +\usepackage{fancyheadings} +%\usepackage{lucidabr} +%\usepackage{fancybox} +\usepackage{array} +\usepackage{graphicx} +%\usepackage{latexsym} +%\usepackage{pstricks,pst-node,pst-tree} +%\usepackage{verbatim} +%\usepackage{rotating} +%\usepackage{pdftex} +%\usepackage{color} +%\usepackage{subfigure} +%\usepackage{wrapfig} + +\newcommand{\devsec}[1]{\chapter{#1}} +\newcommand{\devsubsec}[1]{\section{#1}} +\newcommand{\devsubsubsec}[1]{\subsection{#1}} +\newcommand{\function}[5]{ + \subsection{#1} + + \noindent DESCRIPTION + \medskip + + \begin{tabular}[h]{p{11cm}} + #3 + \end{tabular} + + \medskip + \noindent SYNOPSIS + \medskip + + \begin{tabular}[h]{p{11cm}} + {\tt #2} + \end{tabular} + + %\item[] +\medskip +\noindent PARAMETERS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #4 + \end{tabular} + + %\item[] +\medskip +\noindent ERRORS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #5 + \end{tabular} + + %\end{itemize} + +\medskip +} +\def\ifunction#1#2#3#4#5{\function{#1\index{#1}}{#2}{#3}{#4}{#5}} + +\newcommand{\kfunction}[5]{ + \subsection{#1} + \noindent DESCRIPTION + \medskip + + \begin{tabular}[h]{p{11cm}} + #3 + \end{tabular} + + \medskip + \noindent SYNOPSIS + \medskip + + \begin{tabular}[h]{p{11cm}} + {\tt #2} + \end{tabular} + + %\item[] +\medskip +\noindent PARAMETERS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #4 + \end{tabular} + + %\item[] +\medskip +\noindent RETURNS +\medskip + + \begin{tabular}[h]{p{3cm}p{8cm}} + #5 + \end{tabular} + + %\end{itemize} + +\medskip +} +\def\kifunction#1#2#3#4#5{\kfunction{#1\index{#1}}{#2}{#3}{#4}{#5}} + + +%\usepackage{index} +%\makeindex + + +\begin{document} + +\input{title.tex} + +\cleardoublepage + +\pagenumbering{roman} +\pagestyle{fancyplain} + + +\tableofcontents +%\listoffigures +%\listoftables + +\cleardoublepage + +\pagenumbering{arabic} + +\renewcommand{\chaptermark}[1]{\markboth{\uppercase{#1}}{}} +\renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} +\lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} +\rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} +\cfoot{\copyright 2002 convergence GmbH} + +\input{intro.tex} + +\input{devices.tex} + +\input{examples.tex} + +\cleardoublepage + +\appendix + +\cleardoublepage + +\thispagestyle{plain}\chaptermark{Bibliography} +\addcontentsline{toc}{chapter}{Bibliography} +\bibliographystyle{bibsec} +\bibliography{main} + +\cleardoublepage + +\thispagestyle{plain}\chaptermark{Subject Index} +\addcontentsline{toc}{chapter}{Subject Index} +%\printindex + +\cleardoublepage + +\end{document} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: diff --git a/dvb-spec/dvbapi/dvbstb.fig b/dvb-spec/dvbapi/dvbstb.fig new file mode 100644 index 000000000..0a6bbadc3 --- /dev/null +++ b/dvb-spec/dvbapi/dvbstb.fig @@ -0,0 +1,59 @@ +#FIG 3.2 +Landscape +Center +Metric +A4 +100.00 +Single +-2 +1200 2 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1620 360 2520 360 2520 900 1620 900 1620 360 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 1260 1080 1620 630 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 2520 630 2880 630 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2880 360 3780 360 3780 900 2880 900 2880 360 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 0 0 1.00 60.00 120.00 + 4590 900 3330 1170 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 0 0 1.00 60.00 120.00 + 4590 900 4590 1170 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4140 360 5040 360 5040 900 4140 900 4140 360 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3780 630 4140 630 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 4140 1170 5040 1170 5040 1710 4140 1710 4140 1170 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 2880 1170 3780 1170 3780 1710 2880 1710 2880 1170 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1620 1170 2520 1170 2520 1710 1620 1710 1620 1170 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 0 0 1.00 60.00 120.00 + 1620 1440 1260 1080 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 1350 225 5175 225 5175 1845 1350 1845 1350 225 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 3240 1710 3960 2070 +2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2 + 1 1 1.00 60.00 120.00 + 4590 1710 3960 2070 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 3510 2070 4410 2070 4410 2610 3510 2610 3510 2070 +2 2 0 1 0 7 50 0 -1 0.000 0 0 -1 0 0 5 + 360 810 1260 810 1260 1350 360 1350 360 810 +4 0 0 50 0 0 12 0.0000 4 135 675 1755 675 Frontend\001 +4 0 0 50 0 0 12 0.0000 4 135 690 4275 675 Demuxer\001 +4 0 0 50 0 0 12 0.0000 4 135 450 4365 1485 Video\001 +4 0 0 50 0 0 12 0.0000 4 135 450 3105 1485 Audio\001 +4 0 0 50 0 0 12 0.0000 4 135 345 1890 1485 SEC\001 +4 0 0 50 0 0 12 0.0000 4 135 255 3195 675 CA\001 +4 0 0 50 0 0 12 0.0000 4 135 645 495 1125 Antenna\001 +4 0 0 50 0 0 12 0.0000 4 135 240 3870 2385 TV\001 diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex new file mode 100644 index 000000000..ea2797481 --- /dev/null +++ b/dvb-spec/dvbapi/examples.tex @@ -0,0 +1,366 @@ +\chapter{Examples} +In this section we would like to present some examples for using the DVB API. + +\section{Tuning} +We will start with a generic tuning subroutine that uses the frontend +and SEC, as well as the demux devices. The example is given for QPSK +tuners, but can easily be adjusted for QAM. + +{\small +\begin{verbatim} +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#include + +#define DMX "/dev/ost/demux" +#define FRONT "/dev/ost/frontend" +#define SEC "/dev/ost/sec" + +/* routine for checking if we have a signal and other status information*/ +int FEReadStatus(int fd, fe_status_t *stat) +{ + int ans; + + if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ + perror("FE READ STATUS: "); + return -1; + } + + if (*stat & FE_HAS_POWER) + printf("FE HAS POWER\n"); + + if (*stat & FE_HAS_SIGNAL) + printf("FE HAS SIGNAL\n"); + + if (*stat & FE_SPECTRUM_INV) + printf("SPEKTRUM INV\n"); + + return 0; +} + + +/* tune qpsk */ +/* freq: frequency of transponder */ +/* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */ +/* diseqc: DiSEqC address of the used LNB */ +/* pol: Polarisation */ +/* srate: Symbol Rate */ +/* fec. FEC */ +/* lnb_lof1: local frequency of lower LNB band */ +/* lnb_lof2: local frequency of upper LNB band */ +/* lnb_slof: switch frequency of LNB */ + +int set_qpsk_channel(int freq, int vpid, int apid, int tpid, + int diseqc, int pol, int srate, int fec, int lnb_lof1, + int lnb_lof2, int lnb_slof) +{ + struct secCommand scmd; + struct secCmdSequence scmds; + struct dmx_pes_filter_params pesFilterParams; + FrontendParameters frp; + struct pollfd pfd[1]; + FrontendEvent event; + int demux1, dmeux2, demux3, front, + + frequency = (uint32_t) freq; + symbolrate = (uint32_t) srate; + + if((front = open(FRONT,O_RDWR)) < 0){ + perror("FRONTEND DEVICE: "); + return -1; + } + + if((sec = open(SEC,O_RDWR)) < 0){ + perror("SEC DEVICE: "); + return -1; + } + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux3 < 0){ + if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (freq < lnb_slof) { + frp.Frequency = (freq - lnb_lof1); + scmds.continuousTone = SEC_TONE_OFF; + } else { + frp.Frequency = (freq - lnb_lof2); + scmds.continuousTone = SEC_TONE_ON; + } + frp.Inversion = INVERSION_AUTO; + if (pol) scmds.voltage = SEC_VOLTAGE_18; + else scmds.voltage = SEC_VOLTAGE_13; + + scmd.type=0; + scmd.u.diseqc.addr=0x10; + scmd.u.diseqc.cmd=0x38; + scmd.u.diseqc.numParams=1; + scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) | + (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | + (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); + + scmds.miniCommand=SEC_MINI_NONE; + scmds.numCommands=1; + scmds.commands=&scmd; + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + frp.u.qpsk.SymbolRate = srate; + frp.u.qpsk.FEC_inner = fec; + + if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ + perror("QPSK TUNE: "); + return -1; + } + + pfd[0].fd = front; + pfd[0].events = POLLIN; + + if (poll(pfd,1,3000)){ + if (pfd[0].revents & POLLIN){ + printf("Getting QPSK event\n"); + if ( ioctl(front, FE_GET_EVENT, &event) + + == -EBUFFEROVERFLOW){ + perror("qpsk get event"); + return -1; + } + printf("Received "); + switch(event.type){ + case FE_UNEXPECTED_EV: + printf("unexpected event\n"); + return -1; + case FE_FAILURE_EV: + printf("failure event\n"); + return -1; + + case FE_COMPLETION_EV: + printf("completion event\n"); + } + } + } + + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pesType = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_vpid"); + return -1; + } + + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pesType = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_apid"); + return -1; + } + + pesFilterParams.pid = tpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pesType = DMX_PES_TELETEXT; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_tpid"); + return -1; + } + + return has_signal(fds); +} + +\end{verbatim} +} +The program assumes that you are using a universal LNB and a standard +DiSEqC switch with up to 4 addresses. Of course, you could build in +some more checking if tuning was successful and maybe try to repeat +the tuning process. Depending on the external hardware, i.e. LNB and +DiSEqC switch, and weather conditions this may be necessary. + + +\section{The DVR device} +The following program code shows how to use the DVR device for +recording. + +{\small +\begin{verbatim} +#include +#include +#include +#include +#include +#include +#include +#include + +#include +#include +#include +#define DVR "/dev/ost/dvr" +#define AUDIO "/dev/ost/audio" +#define VIDEO "/dev/ost/video" + +#define BUFFY (188*20) +#define MAX_LENGTH (1024*1024*5) /* record 5MB */ + + +/* switch the demuxes to recording, assuming the transponder is tuned */ + +/* demux1, demux2: file descriptor of video and audio filters */ +/* vpid, apid: PIDs of video and audio channels */ + +int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) +{ + struct dmx_pes_filter_params pesFilterParams; + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pesType = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pesType = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + return 0; +} + +/* start recording MAX_LENGTH , assuming the transponder is tuned */ + +/* demux1, demux2: file descriptor of video and audio filters */ +/* vpid, apid: PIDs of video and audio channels */ +int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) +{ + int i; + int len; + int written; + uint8_t buf[BUFFY]; + uint64_t length; + struct pollfd pfd[1]; + int dvr, dvr_out; + + /* open dvr device */ + if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ + perror("DVR DEVICE"); + return -1; + } + + /* switch video and audio demuxes to dvr */ + printf ("Switching dvr on\n"); + i = switch_to_record(demux1, demux2, vpid, apid); + printf("finished: "); + + printf("Recording %2.0f MB of test file in TS format\n", + MAX_LENGTH/(1024.0*1024.0)); + length = 0; + + /* open output file */ + if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT + |O_TRUNC, S_IRUSR|S_IWUSR + |S_IRGRP|S_IWGRP|S_IROTH| + S_IWOTH)) < 0){ + perror("Can't open file for dvr test"); + return -1; + } + + pfd[0].fd = dvr; + pfd[0].events = POLLIN; + + /* poll for dvr data and write to file */ + while (length < MAX_LENGTH ) { + if (poll(pfd,1,1)){ + if (pfd[0].revents & POLLIN){ + len = read(dvr, buf, BUFFY); + if (len < 0){ + perror("recording"); + return -1; + } + if (len > 0){ + written = 0; + while (written < len) + written += + write (dvr_out, + buf, len); + length += len; + printf("written %2.0f MB\r", + length/1024./1024.); + } + } + } + } + return 0; +} + +\end{verbatim} +} +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% TeX-master: t +%%% End: diff --git a/dvb-spec/dvbapi/fig2pstex b/dvb-spec/dvbapi/fig2pstex new file mode 100755 index 000000000..bf62eb7ec --- /dev/null +++ b/dvb-spec/dvbapi/fig2pstex @@ -0,0 +1,6 @@ +#!/bin/sh +f=`basename $1 .fig` +fig2dev -L pstex $f.fig $f.ps +fig2dev -L pstex_t -p $f.ps $f.fig $f.pst2 +./getbb $f.pst2 $f.ps > $f.pst +rm $f.pst2 \ No newline at end of file diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex new file mode 100644 index 000000000..cb3285d06 --- /dev/null +++ b/dvb-spec/dvbapi/frontend.tex @@ -0,0 +1,630 @@ +\devsec{DVB Frontend API} + +The DVB frontend device controls the tuner and DVB demodulator hardware. +It can be accessed through \texttt{/dev/ost/frontend}. +If you are using \texttt{devfs} you can use \texttt{/dev/dvb/card0/frontend}. +The frontend device will only be made visible through \texttt{devfs} +if the corresponding card actually has a frontend. Cards which support +the DVB API but, e.g., only can play back recordings, will not offer the +frontend device. + +\devsubsec{Frontend Data Types} + +\devsubsubsec{frontend status} +\label{frontendstatus} + +Several functions of the frontend device use the feStatus data +type defined by +\begin{verbatim} +typedef uint32_t feStatus; +\end{verbatim} +to indicate the current state and/or state changes of +the frontend hardware. + +\noindent +It can take on the values +\begin{verbatim} +#define FE_HAS_POWER 1 +#define FE_HAS_SIGNAL 2 +#define FE_SPECTRUM_INV 4 +#define FE_HAS_LOCK 8 +#define FE_HAS_CARRIER 16 +#define FE_HAS_VITERBI 32 +#define FE_HAS_SYNC 64 +#define TUNER_HAS_LOCK 128 +\end{verbatim} +which can be ORed together and have the following meaning: + +\medskip + +\begin{tabular}{lp{11cm}} +FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ +FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ +FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ +FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ +FE\_HAS\_CARRIER & carrier detected in signal\\ +FE\_HAS\_VITERBI & lock at viterbi decoder stage\\ +FE\_HAS\_SYNC & TS sync bytes detected \\ +TUNER\_HAS\_LOCK & the tuner has a frequency lock +\end{tabular} + + +\devsubsubsec{frontend parameters} +\label{frontendparameters} + +The kind of parameters passed to the frontend device for tuning +depend on the kind of hardware you are using. +All kinds of parameters are combined as a union in the +FrontendParameters structure: +\begin{verbatim} +typedef struct { + __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ + /* intermediate frequency in kHz for QPSK */ + fe_spectral_inversion_t Inversion; /* spectral inversion */ + union { + QPSKParameters qpsk; + QAMParameters qam; + OFDMParameters ofdm; + } u; +} FrontendParameters; +\end{verbatim} + +For satellite QPSK frontends you have to use QPSKParameters defined by +\begin{verbatim} +typedef struct { + __u32 SymbolRate; /* symbol rate in Symbols per second */ + fe_code_rate_t FEC_inner; /* forward error correction (see above) */ +} QPSKParameters; +\end{verbatim} +for cable QAM frontend you use the QAMParameters structure +\begin{verbatim} +typedef struct { + __u32 SymbolRate; /* symbol rate in Symbols per second */ + fe_code_rate_t FEC_outer; /* forward error correction (see above) */ + fe_code_rate_t FEC_inner; /* forward error correction (see above) */ + fe_modulation_t QAM; /* modulation type (see above) */ +} QAMParameters; +\end{verbatim} +DVB-T frontends are supported by the OFDMParamters structure +\begin{verbatim} +typedef struct { + fe_bandwidth_t bandWidth; + fe_code_rate_t HP_fe_code_rate_t; /* high priority stream code rate */ + fe_code_rate_t LP_fe_code_rate_t; /* low priority stream code rate */ + fe_modulation_t Constellation; /* modulation type (see above) */ + fe_transmit_mode_t TransmissionMode; + fe_guard_interval_t guardInterval; + fe_hierarchy_t fe_hierarchy_tInformation; +} OFDMParameters; +\end{verbatim} + +In the case of QPSK frontends the Frequency field specifies the intermediate +frequency, i.e. the offset which is effectively added to the local oscillator +frequency (LOF) of the LNB. +The intermediate frequency has to be specified in units of kHz. +For QAM and OFDM frontends the Frequency specifies the absolute frequency +and is given in Hz. + +The Inversion field can take one of these values: +\begin{verbatim} +typedef enum { + INVERSION_OFF, + INVERSION_ON, + INVERSION_AUTO +} fe_spectral_inversion_t; +\end{verbatim} +It indicates if spectral inversion should be presumed or not. +In the automatic setting (\verb INVERSION\_AUTO) the hardware will +try to figure out the correct setting by itself. + +\noindent +The possible values for the FEC\_inner field are +\begin{verbatim} +enum { + FEC_AUTO, + FEC_1_2, + FEC_2_3, + FEC_3_4, + FEC_5_6, + FEC_7_8, + FEC_NONE +}; +\end{verbatim} +which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., +no error correction or auto detection. + +\noindent +For cable and terrestrial frontends (QAM and OFDM) one also has to +specify the quadrature modulation mode which can be one of the following: +\begin{verbatim} +typedef enum +{ QPSK, + QAM_16, + QAM_32, + QAM_64, + QAM_128, + QAM_256 +} QAM_TYPE; +\end{verbatim} + +Finally, there are several more parameters for OFDM: +\begin{verbatim} +typedef enum { + TRANSMISSION_MODE_2K, + TRANSMISSION_MODE_8K +} fe_transmit_mode_t; +\end{verbatim} + +\begin{verbatim} +typedef enum { + BANDWIDTH_8_MHZ, + BANDWIDTH_7_MHZ, + BANDWIDTH_6_MHZ +} fe_bandwidth_t; +\end{verbatim} + +\begin{verbatim} +typedef enum { + GUARD_INTERVAL_1_32, + GUARD_INTERVAL_1_16, + GUARD_INTERVAL_1_8, + GUARD_INTERVAL_1_4 +} fe_guard_interval_t; +\end{verbatim} + +\begin{verbatim} +typedef enum { + HIERARCHY_NONE, + HIERARCHY_1, + HIERARCHY_2, + HIERARCHY_4 +} fe_hierarchy_t; +\end{verbatim} + + +\devsubsubsec{frontend events} +\label{frontendevents} + +\begin{verbatim} +enum { + FE_UNEXPECTED_EV, + FE_COMPLETION_EV, + FE_FAILURE_EV +}; +\end{verbatim} + +\begin{verbatim} +typedef struct { + EventType type; /* type of event, FE_UNEXPECTED_EV, ... */ + long timestamp; /* time in seconds since 1970-01-01 */ + + union { + struct { + fe_status_t previousStatus; /* status before event */ + fe_status_t currentStatus; /* status during event */ + } unexpectedEvent; + FrontendParameters completionEvent; /* parameters for which the + tuning succeeded */ + fe_status_t failureEvent; /* status at failure (e.g. no lock) */ + } u; +} FrontendEvent; +\end{verbatim} + +\begin{verbatim} +struct qpskRegister { + uint8_t chipId; + uint8_t address; + uint8_t value; +}; +\end{verbatim} + +\begin{verbatim} +struct qamRegister { + uint8_t chipId; + uint8_t address; + uint8_t value; +}; +\end{verbatim} + +\begin{verbatim} +struct qpskFrontendInfo { + uint32_t minFrequency; + uint32_t maxFrequency; + uint32_t maxSymbolRate; + uint32_t minSymbolRate; + uint32_t hwType; + uint32_t hwVersion; +}; +\end{verbatim} + +\begin{verbatim} +struct qamFrontendInfo { + uint32_t minFrequency; + uint32_t maxFrequency; + uint32_t maxSymbolRate; + uint32_t minSymbolRate; + uint32_t hwType; + uint32_t hwVersion; +}; +\end{verbatim} + +\begin{verbatim} +typedef enum { + FE_POWER_ON, + FE_POWER_STANDBY, + FE_POWER_SUSPEND, + FE_POWER_OFF +} powerState_t; +\end{verbatim} + + +\clearpage + + +\devsubsec{Frontend Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named frontend device (e.g. /dev/ost/qpskfe + for a satellite frontend or /dev/ost/qamfe for a cable frontend) + 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. + + }{ + const char *deviceName & Name of specific video device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\ifunction{OST\_SELFTEST}{ + int ioctl(int fd, int request = OST\_SELFTEST);}{ + This ioctl call initiates an automatic self-test of the front-end hardware. + This call requires read/write access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals OST\_SELFTEST for this command.\\ + }{ + -1& Self test failure.\\ +} + +\ifunction{OST\_SET\_POWER\_STATE}{ + int ioctl(int fd, int request = OST\_SET\_POWER\_STATE, uint32\_t state);}{ + 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 supports 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: \\ + \begin{center} + \begin{tabular}[h]{cll} + number of low-power & requested state & resulting state\\ + states supported &&\\ + \\ + 1 & standby & suspend \\ + 1 & suspend & suspend \\ + 0 & standby & on \\ + 0 & suspend & on + \end{tabular} + \end{center}\\ + 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.) + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals OST\_SET\_POWER\_STATE for this command.\\ + uint32\_t state & Requested power state. One of: \\ + & + \begin{tabular}[h]{ll} + 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\\ + \end{tabular} + }{ + 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. +} + +\ifunction{FE\_GET\_POWER\_STATE}{ + int ioctl(int fd, int request = OST\_GET\_POWER\_STATE, uint32\_t *state);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals OST\_GET\_POWER\_STATE for this command.\\ + uint32\_t *state & Requested power state. One of: \\ + & + \begin{tabular}[h]{ll} + 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\\ + \end{tabular} + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINVAL& Illegal state, or not available on this device.\\ + EFAULT& state points to invalid address.\\ + ENOSYS& Function not available for this device. +} + +\ifunction{FE\_READ\_STATUS}{ + int ioctl(int fd, int request = FE\_READ\_STATUS, feStatus *status);}{ + This ioctl call returns status information about the front-end. + This call only requires read-only access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_READ\_STATUS for this command.\\ + struct feStatus *status&Points to the location where the front-end + status word is to be stored. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& status points to invalid address.\\ +} + +\ifunction{FE\_READ\_BER}{ + int ioctl(int fd, int request = FE\_READ\_BER, uint32\_t *ber);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_READ\_BER for this command.\\ + uint32\_t *ber & 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\cdot 10^{-6}$, or 1 error in 400000 bits. + }{ + 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. +} + +\ifunction{FE\_READ\_SNR}{ + int ioctl(int fd, int request = FE\_READ\_SNR, int32\_t *snr);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_READ\_SNR for this command.\\ + int32\_t *snr& 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. +}{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& snr 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. +} + +\ifunction{FE\_READ\_SIGNAL\_STRENGTH}{ + int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int32\_t *strength); +}{ +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. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_READ\_SIGNAL\_STRENGTH for this command.\\ +int32\_t *strength & 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. +}{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& status 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. +} + +\ifunction{FE\_READ\_UNCORRECTED\_BLOCKS}{ + int ioctl( int fd, int request = FE\_READ\_UNCORRECTED\_BLOCKS, uint32\_t *ublocks); }{ + This ioctl call returns the number of uncorrected blocks detected by + the device driver during its lifetime. + For meaningful measurements, the increment in + block count during a specific time interval should be calculated. + For this command, read-only access to the device is sufficient.\\ + Note that the counter will wrap to zero after its maximum count has + been reached. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_READ\_UNCORRECTED\_BLOCKS for this command.\\ +uint32\_t *ublocks & The total number of uncorrected blocks seen +by the driver so far. +}{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& ublocks points to invalid address.\\ + ENOSYS& Function not available for this device. +} + + +\ifunction{FE\_GET\_NEXT\_FREQUENCY}{ + int ioctl( int fd, int request = FE\_GET\_NEXT\_FREQUENCY, uint32\_t *freq);}{ + 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 efficient 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.\\ + Note that scanning may still be excruciatingly slow on some hardware, for + other reasons than a non-optimal scanning step size. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_GET\_NEXT\_FREQUENCY for this command.\\ + uint32\_t *freq& Input: a given frequency \\ + & Output: the frequency corresponding to + the next higher frequency setting.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& freq points to invalid address.\\ + EINVAL& Maximum supported frequency reached.\\ + ENOSYS& Function not available for this device. +} + +\ifunction{FE\_GET\_NEXT\_SYMBOL\_RATE}{ + int ioctl( int fd, int request = FE\_GET\_NEXT\_SYMBOL\_RATE, uint32\_t *symbolRate); + }{ + 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 efficient 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_GET\_NEXT\_SYMBOL\_RATE for this command.\\ + uint32\_t *symbolRate& Input: a given symbol rate \\ + & Output: the symbol rate corresponding to + the next higher symbol rate.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& symbolRate points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ + ENOSYS& Function not available for this device. +} + +\ifunction{FE\_SET\_FRONTEND}{ + int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct FrontendParameters *p);}{ + This ioctl call starts a tuning operation using specified parameters. + The result of this call will be successful if the parameters were valid and + the tuning could be initiated. + The result of the tuning operation in itself, however, will arrive + asynchronously as an event (see documentation for FE\_GET\_EVENT + and FrontendEvent.) + If a new FE\_SET\_FRONTEND operation is initiated before the previous + one was completed, + the previous operation will be aborted in favor of the new one. + This command requires read/write access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_SET\_FRONTEND for this command.\\ + struct FrontendParameters *p& Points to parameters for tuning operation.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& p points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ +} + +\ifunction{FE\_GET\_EVENT}{ + int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct qpskEvent *ev);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals QPSK\_GET\_EVENT for this command.\\ + struct qpskEvent *ev&Points to the location where the event, if any, is to be stored. + }{ + 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.\\ +} + +\ifunction{FE\_GET\_INFO}{ + int ioctl(int fd, int request = FE\_GET\_INFO, struct FrontendInfo *info);}{ + This ioctl call returns information about the front-end. + This call only requires read-only access to the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_GET\_INFO for this command.\\ + struct qpskFrontendInfo *info & Points to the location where the front-end + information is to be stored. + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& info points to invalid address.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/getbb b/dvb-spec/dvbapi/getbb new file mode 100755 index 000000000..004714d3a --- /dev/null +++ b/dvb-spec/dvbapi/getbb @@ -0,0 +1,12 @@ +#!/bin/sh +f=`grep BoundingBox $2 | cut -d' ' -f2,3,4,5` +g=`\ +echo $2" llx=";(echo $f|cut -d' ' -f1 );\ +echo " lly=";(echo $f|cut -d' ' -f2 );\ +echo " urx=";(echo $f|cut -d' ' -f3 );\ +echo " ury=";(echo $f|cut -d' ' -f4 );\ +echo " rwi=";(echo $f|cut -d' ' -f3 );\ +echo "0" +` +h=`echo $g| sed "s/= /=/g" | sed "s/ 0/0/g"` +cat $1 | sed "s/psfile=$2/psfile=$h/" diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex new file mode 100644 index 000000000..1d859fadb --- /dev/null +++ b/dvb-spec/dvbapi/intro.tex @@ -0,0 +1,183 @@ +\chapter{Introduction} +%\addcontentsline{toc}{part}{Introduction} +%\chaptermark{Introduction} +\section{What you need to know} +The reader of this document is required to have some knowledge in the +area of digital video broadcasting (DVB) and should be familiar with +part I of ISO/IEC 13818, i.e you should know what a +program/transport stream (PS/TS) is and what is meant by a packetized elementary +stream (PES) or an I-frame. + +It is also necessary to know how to access unix/linux devices and how +to use ioctl calls. This also includes the knowledge of C or C++. +\section{History} + +The first API for DVB cards we used at Convergence in late 1999 +was an extension of the Video4Linux API which was primarily +developed for frame grabber cards. +As such it was not really well suited to be used for DVB cards and +their new features like recording MPEG streams and filtering several +section and PES data streams at the same time. + +In early 2000, we were approached by Nokia with a proposal for a new +standard Linux DVB API. +As a commitment to the development of terminals based on open standards, +Nokia and Convergence made it available to all Linux developers and +published it on \texttt{http://www.linuxtv.org/} in September 2000. +Convergence is the maintainer of the Linux DVB API. +Together with the LinuxTV community (i.e. you, the reader of this document), +the Linux DVB API will be constantly reviewed and improved upon. +With the Linux driver for the Siemens/Hauppauge DVB PCI card Convergence +provides a first implementation of the Linux DVB API. + + +\section{Overview} + +\begin{figure}[htbp] + \begin{center} + \includegraphics{dvbstb.ps} + \caption{Components of a DVB card/STB} + \label{fig:dvbstb} + \end{center} +\end{figure} + + +A DVB PCI card or DVB set-top-box (STB) usually consists of the following +main hardware components: +\begin{itemize} +\item Frontend consisting of tuner and DVB demodulator + +Here the raw signal reaches the DVB hardware from a satellite dish or antenna +or directly from cable. The frontend down-converts and demodulates +this signal into an MPEG transport stream (TS). + +\item SEC for controlling external hardware like LNBs and antennas + +This part of the hardware can send signals back through the satellite +cable to control the polarization of the LNB, to switch between +different LNBs or even to control the movements of a dish rotor. + + +\item Conditional Access (CA) hardware like CI adapters and smartcard slots + +The complete TS is passed through the CA hardware. Programs to which +the user has access (controlled by the smart card) are decoded in real +time and re-inserted into the TS. + +\item Demultiplexer which filters the incoming DVB stream + +The demultiplexer splits the TS into its components like audio and video +streams. Besides usually several of such audio and video streams it also +contains data streams with information about the programs offered in this +or other streams of the same provider. + +\item MPEG2 audio and video decoder + +The main targets of the demultiplexer are the MPEG2 audio and video +decoders. After decoding the pass on the uncompressed audio +and video to the computer screen or (through a PAL/NTSC encoder) to +a TV set. +\end{itemize} +Figure \ref{fig:dvbstb} shows a crude schematic of the control and data flow +between those components. + +On a DVB PCI card not all of these have to be present since some +functionality can be provided by the main CPU of the PC (e.g. MPEG picture +and sound decoding) or is not needed (e.g. for data-only uses like +``internet over satellite''). +Also not every card or STB provides conditional access hardware. + +\section{Linux DVB Devices} + +The Linux DVB API lets you control these hardware components +through currently six Unix-style character devices for +video, audio, frontend, SEC, demux and CA. +The video and audio devices control the MPEG2 decoder hardware, +the frontend device the tuner and the DVB demodulator. +External hardware like DiSEqC switches and rotors can be controlled +through the SEC device. +The demux device gives you control over the PES and section filters +of the hardware. If the hardware does not support filtering these filters +can be implemented in software. +Finally, the CA device controls all the conditional access capabilities +of the hardware. It can depend on the individual security requirements +of the platform, if and how many of the CA functions are made available +to the application through this device. + +All devices can be found in the \texttt{/dev} tree under +\texttt{/dev/ost}, where OST stands for Open Standards Terminal. +The individual devices are called +\begin{itemize} +\item \texttt{/dev/ost/audio}, +\item \texttt{/dev/ost/video}, +\item \texttt{/dev/ost/frontend}, +\item \texttt{/dev/ost/sec}, +\item \texttt{/dev/ost/demux}, +\item \texttt{/dev/ost/ca}, +\end{itemize} +but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of +these devices. + +If more than one card is present in the system the other cards +can be accessed through the corresponding devices with the +card's number appended. \texttt{/dev/ost/demux0} (which +is identical to \texttt{/dev/ost/demux}) would, e.g., control the +demultiplexer of the first card, while \texttt{/dev/ost/demux1} +would control the demultiplexer of the second card, and so on. + +More details about the data structures and function calls of +all the devices are described in the following chapters. + + +\section{DVB Devices with Devfs} + +Recent Linux kernel versions support a special file system called +\textsl{devfs} which is a replacement for the traditional +device directory. +With devfs a Linux DVB driver will only create those device file entries +which actually exist. +It also makes dealing with more complex DVB hardware much easier. +The device structure described above is not well suited to deal +with multiple DVB cards with more than one frontend or demultiplexer. +Consider, e.g., two DVB cards, one with two frontends and +one demultiplexer, the other with one frontend and two demultiplexers. +If we just assign them consecutive numbers, there would be a demultiplexer +and a frontend which do not belong to the same card but have +the same number. + +With \textsl{devfs} we propose a different scheme for the device names. +The root directory for all DVB cards will be \texttt{/dev/dvb}. +Each card gets assigned a sub-directory with the name \texttt{/dev/card0}, +\texttt{/dev/card1}, etc. +The files created in these sub-directories will correspond directly to the +hardware actually present on the card. +Thus, if the first card has one QAM frontend, one demultiplexer +and otherwise no other hardware, +only \texttt{/dev/dvb/card0/qamfe0} and \texttt{/dev/dvb/card0/demux0} +will be created. +When a second DVB-S card with one frontend (including SEC) device, +two demultiplexers and an MPEG2 audio/video decoder is added, the +complete \texttt{/dev/dvb} tree will look like this: + +\begin{verbatim} +/dev/dvb/card0/frontend0 + demux0 + +/dev/dvb/card1/video0 + audio0 + demux0 + demux1 + frontend0 + sec0 +\end{verbatim} + + +\section{Using the Devices} + +\dots + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex new file mode 100644 index 000000000..59490299b --- /dev/null +++ b/dvb-spec/dvbapi/kdapi.tex @@ -0,0 +1,1007 @@ +\devsec{Kernel Demux API} + +The kernel demux API + +\devsubsec{Kernel Demux Data Types} + +\devsubsubsec{dmx\_success\_t} +\label{dmxsuccesst} + +\begin{verbatim} +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; +\end{verbatim} + + +\devsubsubsec{TS filter types} +\label{tsfiltertypes} + +\begin{verbatim} +/*--------------------------------------------------------------------------*/ +/* TS packet reception */ +/*--------------------------------------------------------------------------*/ + +/* TS filter type for set_type() */ + +#define TS_PACKET 1 /* send TS packets (188 bytes) to callback (default) */ +#define TS_PAYLOAD_ONLY 2 /* in case TS_PACKET is set, only send the TS + payload (<=184 bytes per packet) to callback */ +#define TS_DECODER 4 /* send stream to built-in decoder (if present) */ +\end{verbatim} + + +\devsubsubsec{dmx\_ts\_pes\_t} +\label{dmxtspest} + +The structure +\begin{verbatim} +typedef enum +{ + DMX_TS_PES_AUDIO, /* also send packets to audio decoder (if it exists) */ + DMX_TS_PES_VIDEO, /* ... */ + DMX_TS_PES_TELETEXT, + DMX_TS_PES_SUBTITLE, + DMX_TS_PES_PCR, + DMX_TS_PES_OTHER, +} dmx_ts_pes_t; +\end{verbatim} +describes the PES type for filters which write to +a built-in decoder. +The correspond (and should be kept identical) to the types in +the demux device. + +\begin{verbatim} +struct dmx_ts_feed_s { + int is_filtering; /* Set to non-zero when filtering in progress */ + struct dmx_demux_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ + int (*set) (struct dmx_ts_feed_s* feed, + __u16 pid, + size_t callback_length, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (*start_filtering) (struct dmx_ts_feed_s* feed); + int (*stop_filtering) (struct dmx_ts_feed_s* feed); + int (*set_type) (struct dmx_ts_feed_s* feed, + int type, + dmx_ts_pes_t pes_type); +}; + +typedef struct dmx_ts_feed_s dmx_ts_feed_t; +\end{verbatim} + +\begin{verbatim} +/*--------------------------------------------------------------------------*/ +/* PES packet reception (not supported yet) */ +/*--------------------------------------------------------------------------*/ + +typedef struct dmx_pes_filter_s { + struct dmx_pes_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ +} dmx_pes_filter_t; +\end{verbatim} + +\begin{verbatim} +typedef struct dmx_pes_feed_s { + int is_filtering; /* Set to non-zero when filtering in progress */ + struct dmx_demux_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ + int (*set) (struct dmx_pes_feed_s* feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + struct timespec timeout); + int (*start_filtering) (struct dmx_pes_feed_s* feed); + int (*stop_filtering) (struct dmx_pes_feed_s* feed); + int (*allocate_filter) (struct dmx_pes_feed_s* feed, + dmx_pes_filter_t** filter); + int (*release_filter) (struct dmx_pes_feed_s* feed, + dmx_pes_filter_t* filter); +} dmx_pes_feed_t; +\end{verbatim} + + +\label{sectionfilter} +\begin{verbatim} +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; +\end{verbatim} + +\begin{verbatim} +struct dmx_section_feed_s { + int is_filtering; /* Set to non-zero when filtering in progress */ + struct dmx_demux_s* parent; /* Back-pointer */ + void* priv; /* Pointer to private data of the API client */ + int (*set) (struct dmx_section_feed_s* feed, + __u16 pid, + size_t circular_buffer_size, + int descramble, + int check_crc); + int (*allocate_filter) (struct dmx_section_feed_s* feed, + dmx_section_filter_t** filter); + int (*release_filter) (struct dmx_section_feed_s* feed, + dmx_section_filter_t* filter); + int (*start_filtering) (struct dmx_section_feed_s* feed); + int (*stop_filtering) (struct dmx_section_feed_s* feed); +}; +typedef struct dmx_section_feed_s dmx_section_feed_t; + +/*--------------------------------------------------------------------------*/ +/* Callback functions */ +/*--------------------------------------------------------------------------*/ + +typedef int (*dmx_ts_cb) ( __u8 * buffer1, + size_t buffer1_length, + __u8 * buffer2, + size_t buffer2_length, + dmx_ts_feed_t* source, + dmx_success_t success); + +typedef int (*dmx_section_cb) ( __u8 * buffer1, + size_t buffer1_len, + __u8 * buffer2, + size_t buffer2_len, + dmx_section_filter_t * source, + dmx_success_t success); + +typedef int (*dmx_pes_cb) ( __u8 * buffer1, + size_t buffer1_len, + __u8 * buffer2, + size_t buffer2_len, + dmx_pes_filter_t* source, + dmx_success_t success); + +/*--------------------------------------------------------------------------*/ +/* DVB Front-End */ +/*--------------------------------------------------------------------------*/ + +typedef enum { + DMX_OTHER_FE = 0, + DMX_SATELLITE_FE, + DMX_CABLE_FE, + DMX_TERRESTRIAL_FE, + DMX_LVDS_FE, + DMX_ASI_FE, /* DVB-ASI interface */ + DMX_MEMORY_FE +} dmx_frontend_source_t; + +typedef struct { + /* The following char* fields point to NULL terminated strings */ + char* id; /* Unique front-end identifier */ + char* vendor; /* Name of the front-end vendor */ + char* model; /* Name of the front-end model */ + struct list_head connectivity_list; /* List of front-ends that can + be connected to a particular + demux */ + void* priv; /* Pointer to private data of the API client */ + dmx_frontend_source_t source; +} dmx_frontend_t; + +/*--------------------------------------------------------------------------*/ +/* MPEG-2 TS Demux */ +/*--------------------------------------------------------------------------*/ + +/* + * Flags OR'ed in the capabilites field of struct dmx_demux_s. + */ + +#define DMX_TS_FILTERING 1 +#define DMX_PES_FILTERING 2 +#define DMX_SECTION_FILTERING 4 +#define DMX_MEMORY_BASED_FILTERING 8 /* write() available */ +#define DMX_CRC_CHECKING 16 +#define DMX_TS_DESCRAMBLING 32 +#define DMX_SECTION_PAYLOAD_DESCRAMBLING 64 +#define DMX_MAC_ADDRESS_DESCRAMBLING 128 +\end{verbatim} + +\devsubsubsec{demux\_demux\_t} +\label{demuxdemuxt} + +\begin{verbatim} +/* + * DMX_FE_ENTRY(): Casts elements in the list of registered + * front-ends from the generic type struct list_head + * to the type * dmx_frontend_t + *. +*/ + +#define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list) + +struct dmx_demux_s { + /* The following char* fields point to NULL terminated strings */ + char* id; /* Unique demux identifier */ + char* vendor; /* Name of the demux vendor */ + char* model; /* Name of the demux model */ + __u32 capabilities; /* Bitfield of capability flags */ + dmx_frontend_t* frontend; /* Front-end connected to the demux */ + struct list_head reg_list; /* List of registered demuxes */ + void* priv; /* Pointer to private data of the API client */ + int users; /* Number of users */ + int (*open) (struct dmx_demux_s* demux); + int (*close) (struct dmx_demux_s* demux); + int (*write) (struct dmx_demux_s* demux, const char* buf, size_t count); + int (*allocate_ts_feed) (struct dmx_demux_s* demux, + dmx_ts_feed_t** feed, + dmx_ts_cb callback); + int (*release_ts_feed) (struct dmx_demux_s* demux, + dmx_ts_feed_t* feed); + int (*allocate_pes_feed) (struct dmx_demux_s* demux, + dmx_pes_feed_t** feed, + dmx_pes_cb callback); + int (*release_pes_feed) (struct dmx_demux_s* demux, + dmx_pes_feed_t* feed); + int (*allocate_section_feed) (struct dmx_demux_s* demux, + dmx_section_feed_t** feed, + dmx_section_cb callback); + int (*release_section_feed) (struct dmx_demux_s* demux, + dmx_section_feed_t* feed); + int (*descramble_mac_address) (struct dmx_demux_s* demux, + __u8* buffer1, + size_t buffer1_length, + __u8* buffer2, + size_t buffer2_length, + __u16 pid); + int (*descramble_section_payload) (struct dmx_demux_s* demux, + __u8* buffer1, + size_t buffer1_length, + __u8* buffer2, size_t buffer2_length, + __u16 pid); + int (*add_frontend) (struct dmx_demux_s* demux, + dmx_frontend_t* frontend); + int (*remove_frontend) (struct dmx_demux_s* demux, + dmx_frontend_t* frontend); + struct list_head* (*get_frontends) (struct dmx_demux_s* demux); + int (*connect_frontend) (struct dmx_demux_s* demux, + dmx_frontend_t* frontend); + int (*disconnect_frontend) (struct dmx_demux_s* demux); + + + /* added because js cannot keep track of these himself */ + int (*get_pes_pids) (struct dmx_demux_s* demux, __u16 *pids); +}; +typedef struct dmx_demux_s dmx_demux_t; +\end{verbatim} + + +\devsubsubsec{Demux directory} +\label{demuxdir} + +\begin{verbatim} +/* + * 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); +\end{verbatim} + +\clearpage + +\devsubsec{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. + +\kifunction{dmx\_register\_demux()}{ + int dmx\_register\_demux ( dmx\_demux\_t *demux ) + }{ + 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(), + }{ + dmx\_demux\_t* demux & Pointer to the demux structure. + }{ + 0 & The function was completed without errors.\\ + -EEXIST & A demux with the same value of the id field + already stored in the directory.\\ + -ENOSPC & No space left in the directory. +} + +\kifunction{dmx\_unregister\_demux()}{ + int dmx\_unregister\_demux ( dmx\_demux\_t *demux ) + }{ + 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. + }{ + dmx\_demux\_t* demux & Pointer to the demux structure which is to be unregistered. + }{ + 0 & The function was completed without errors.\\ + ENODEV & The specified demux is not registered in the demux directory.\\ + EBUSY & The specified demux is currently in use. +} + +\kifunction{dmx\_get\_demuxes()}{ + struct list\_head *dmx\_get\_demuxes () + }{ + 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. + }{ + none + }{ + struct list\_head * & + A list of demux interfaces, or NULL in the case of an empty list. +} + +\clearpage + +\devsubsec{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 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 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. + +\kfunction{open()}{ + int open ( demux\_t* demux ); + }{ + 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. + }{ + demux\_t* demux & Pointer to the demux API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EUSERS & Maximum usage count reached.\\ + -EINVAL & Bad parameter. +} + +\kfunction{close()}{ + int close(demux\_t* demux); + }{ + 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. + }{ + demux\_t* demux & Pointer to the demux API and instance data. + }{ + 0 & The function was completed without errors.\\ + -ENODEV & The demux was not in use.\\ + -EINVAL & Bad parameter. +} + +\kfunction{write()}{ + int write(demux\_t* demux, const char* buf, size\_t count); + }{ + This function provides the demux driver with a memory buffer containing TS + packets. Instead of receiving TS packets from the DVB front-end, the demux + driver software will read packets from memory. Any clients of this demux + with active TS, PES or Section filters will receive filtered data via the Demux + callback API (see 0). The function returns when all the data in the buffer has + been consumed by the demux. + Demux hardware typically cannot read TS from memory. If this is the case, + memory-based filtering has to be implemented entirely in software. + }{ + demux\_t* demux & Pointer to the demux API and instance data.\\ + const char* buf & Pointer to the TS data in kernel-space memory.\\ + size\_t length & Length of the TS data. + }{ + 0 & The function was completed without errors.\\ + -ENOSYS & The command is not implemented.\\ + -EINVAL & Bad parameter. +} + +\kifunction{allocate\_ts\_feed()}{ + int allocate\_ts\_feed(dmx\_demux\_t* demux, + dmx\_ts\_feed\_t** feed, dmx\_ts\_cb callback); + }{ + 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. + }{ + demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_ts\_feed\_t** feed & Pointer to the TS feed API and instance data.\\ + dmx\_ts\_cb callback & Pointer to the callback function for + passing received TS packet + }{ + 0 & The function was completed without errors.\\ + -EBUSY & No more TS feeds available.\\ + -ENOSYS & The command is not implemented.\\ + -EINVAL & Bad parameter. +} + +\kifunction{release\_ts\_feed()}{ + int release\_ts\_feed(dmx\_demux\_t* demux, dmx\_ts\_feed\_t* feed); + }{ + Releases the resources allocated with allocate\_ts\_feed(). Any filtering in progress + on the TS feed should be stopped before calling this function. + }{ + demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{allocate\_section\_feed()}{ + int allocate\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t **feed, + dmx\_section\_cb callback); + }{ + 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. + }{ + demux\_t *demux & Pointer to the demux API and instance data.\\ + dmx\_section\_feed\_t **feed & Pointer to the section feed API and instance data.\\ + dmx\_section\_cb callback & Pointer to the callback function for + passing received sections. + }{ + 0 & The function was completed without errors.\\ + -EBUSY & No more section feeds available.\\ + -ENOSYS & The command is not implemented.\\ + -EINVAL & Bad parameter. +} + + +\kifunction{release\_section\_feed()}{ + int release\_section\_feed(dmx\_demux\_t* demux, dmx\_section\_feed\_t *feed); + }{ + 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. + }{ + demux\_t *demux & Pointer to the demux API and instance data.\\ + dmx\_section\_feed\_t *feed & Pointer to the section feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{descramble\_mac\_address()}{ + int descramble\_mac\_address(dmx\_demux\_t* demux, + \_\_u8 *buffer1, size\_t buffer1\_length, + \_\_u8 *buffer2, size\_t buffer2\_length, \_\_u16 pid); + }{ + This function runs a descrambling algorithm on the destination MAC address field of a + DVB Datagram Section, replacing the original address with its un-encrypted version. + Otherwise, the description on the function descramble\_section\_payload() applies + also to this function. + }{ + dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ + \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ + size\_t buffer1\_length & Length of the section data, including headers and CRC, + in buffer1.\\ + \_\_u8* buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a + non-NULL value if the section wraps + past the end of a circular buffer.\\ + size\_t buffer2\_length & Length of the section data, + including headers and CRC, in buffer2.\\ + \_\_u16 pid & The PID on which the section was received. Useful for obtaining the + descrambling key, e.g. from a DVB Common Access facility. + }{ + 0 & The function was completed without errors.\\ + -ENOSYS & No descrambling facility available.\\ + -EINVAL & Bad parameter. +} + +\kifunction{descramble\_section\_payload()}{ + int descramble\_section\_payload(dmx\_demux\_t* demux, + \_\_u8 *buffer1, size\_t buffer1\_length, \_\_u8 *buffer2, size\_t + buffer2\_length, \_\_u16 pid); + }{ + This function runs a descrambling algorithm on the payload of a DVB Datagram + Section, replacing the original payload with its un-encrypted version. + The function will + be called from the demux API implementation; the API client need + not call this function directly. + Section-level scrambling algorithms are currently standardized only for DVB-RCC + (return channel over 2-directional cable TV network) systems. For all other DVB + networks, encryption schemes are likely to be proprietary to each data broadcaster. + Thus, it is expected that this function pointer will have the value of NULL + (i.e., function not available) in most demux API implementations. + Nevertheless, it should be possible + to use the function pointer as a hook for dynamically adding a ``plug-in'' + descrambling facility to a demux driver.\\ + 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. + }{ + dmx\_demux\_t *demux & Pointer to the demux API and instance data.\\ + \_\_u8 *buffer1 & Pointer to the first byte of the section.\\ + size\_t buffer1\_length & Length of the section data, including headers and CRC, in + buffer1.\\ + \_\_u8 *buffer2 & Pointer to the tail of the section data, or NULL. The pointer has a + non-NULL value if the section wraps + past the end of a circular buffer.\\ + size\_t buffer2\_length & Length of the section data, including headers and CRC, in + buffer2.\\ + \_\_u16 pid & The PID on which the section was received. Useful for obtaining the + descrambling key, e.g. from a DVB Common Access facility. + }{ + 0 & The function was completed without errors.\\ + -ENOSYS & No descrambling facility available.\\ + -EINVAL & Bad parameter. +} + +\kifunction{add\_frontend()}{ + int add\_frontend(dmx\_demux\_t *demux, dmx\_frontend\_t *frontend); + }{ + 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(). + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_frontend\_t* frontend & Pointer to the front-end instance data. + }{ + 0 & The function was completed without errors.\\ + -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 parameter. +} + +\kifunction{remove\_frontend()}{ + int remove\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); + }{ + Indicates that the given front-end, registered by a call to add\_frontend(), can no + longer be connected as a TS source by this demux. The function should be called + when a front-end driver or a demux driver is removed from the system. If the front-end + is in use, the function fails with the return value of -EBUSY. + After successfully calling this function, the caller can free the memory of + the frontend struct if it was dynamically allocated before the add\_frontend() + operation. + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_frontend\_t* frontend & Pointer to the front-end instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter.\\ + -EBUSY & The front-end is in use, i.e. a call to + connect\_frontend() has not been followed by + a call to disconnect\_frontend(). +} + +\kifunction{get\_frontends()}{ + struct list\_head* get\_frontends(dmx\_demux\_t* demux); + }{ + 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. + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data. + }{ + dmx\_demux\_t* & A list of front-end interfaces, or NULL in the case of an empty list. +} + + +\kifunction{connect\_frontend()}{ + int connect\_frontend(dmx\_demux\_t* demux, dmx\_frontend\_t* frontend); + }{ + 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(). + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data.\\ + dmx\_frontend\_t* frontend & Pointer to the front-end instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter.\\ + -EBUSY & The front-end is in use. +} + +\kifunction{disconnect\_frontend()}{ + int disconnect\_frontend(dmx\_demux\_t* demux); + }{ + Disconnects the demux and a front-end previously connected by a + connect\_frontend() call. + }{ + dmx\_demux\_t* demux & Pointer to the demux API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\clearpage + +\devsubsec{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. + +\kifunction{dmx\_ts\_cb()}{ + 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); + }{ + 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. \\ + Any TS packets that match the filter settings are copied to a circular buffer. + The filtered TS packets are delivered to the client using this callback + function. The size of the circular buffer is controlled by the + circular\_buffer\_size parameter of the set() function in the TS Feed API. It is + expected that the buffer1 and buffer2 callback parameters point to addresses + within the circular buffer, but other implementations are also + possible. Note that the called party should not try to free the memory the + buffer1 and buffer2 parameters point to.\\ + When this function is called, the buffer1 parameter typically points to the + start of the first undelivered TS packet within a circular buffer. The buffer2 + buffer parameter is normally NULL, except when the received TS packets have + crossed the last address of the circular buffer and "wrapped" to the beginning + of the buffer. In the latter case the buffer1 parameter would contain an + address within the circular buffer, while the buffer2 parameter would contain + the first address of the circular buffer.\\ + The number of bytes delivered with this function (i.e. buffer1\_length + + buffer2\_length) is usually equal to the value of callback\_length parameter given + in the set() function, with one exception: if a timeout occurs before receiving + callback\_length bytes of TS data, any undelivered packets are immediately + delivered to the client by calling this function. The timeout duration is + controlled by the set() function in the TS Feed API.\\ + If a TS packet is received with errors that could not be fixed by the TS-level + forward error correction (FEC), the Transport\_error\_indicator flag of the TS + packet header should be set. The TS packet should not be discarded, as the + error can possibly be corrected by a higher layer protocol. + If the called party is slow in processing the callback, it is possible that + the circular buffer eventually fills up. If this happens, the demux driver + should discard any TS packets received while the buffer is full. The error + should be indicated to the client on the next callback by setting the success + parameter to the value of DMX\_OVERRUN\_ERROR.\\ + The type of data returned to the callback can be selected by the + new function int (*set\_type) (struct dmx\_ts\_feed\_s* feed, int type, + dmx\_ts\_pes\_t pes\_type) which is part of the dmx\_ts\_feed\_s struct + (also cf. to the include file ost/demux.h) + The type parameter decides if the raw TS packet (TS\_PACKET) or just the + payload (TS\_PACKET|TS\_PAYLOAD\_ONLY) should be returned. + If additionally the TS\_DECODER bit is set the stream will also be sent + to the hardware MPEG decoder. In this case, the second flag decides + as what kind of data the stream should be interpreted. + The possible choices are one of DMX\_TS\_PES\_AUDIO, DMX\_TS\_PES\_VIDEO, + DMX\_TS\_PES\_TELETEXT, DMX\_TS\_PES\_SUBTITLE, DMX\_TS\_PES\_PCR, or + DMX\_TS\_PES\_OTHER. + }{ + \_\_u8* buffer1 & Pointer to the start of the filtered TS packets.\\ + size\_t buffer1\_length & Length of the TS data in buffer1.\\ + \_\_u8* buffer2 & Pointer to the tail of the filtered TS packets, or NULL.\\ + size\_t buffer2\_length & Length of the TS data in buffer2.\\ + dmx\_ts\_feed\_t* source & Indicates which TS feed is the source of the callback.\\ + dmx\_success\_t success & Indicates if there was an error in TS reception. + }{ + 0 & Continue filtering.\\ + -1& Stop filtering - has the same effect as a call + to stop\_filtering() on the TS Feed API. +} + +\kifunction{dmx\_section\_cb()}{ + 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); + }{ + This function, provided by the client of the demux API, is called from the demux code. + The function is only called when filtering of sections has been enabled using the + function start\_filtering() of the section feed API. + When the demux driver has received a complete section that matches at least one + section filter, the client is notified via this callback function. Normally this function is + called for each received section; however, it is also possible to deliver multiple sections + with one callback, for example when the system load is high. + If an error occurs while receiving a section, this function should be called with the + corresponding error type set in the success field, whether or not there is data to + deliver. + The Section Feed implementation should maintain a circular buffer for received sections. + However, this is not necessary if the Section Feed API is implemented as a client of + the TS Feed API, because the TS Feed implementation then buffers the + received data. + The size of the circular buffer can be configured using the set() function in the + Section Feed API. If there is no room in the circular buffer when a new section is + received, the section must be discarded. If this happens, the value of the success + parameter should be DMX\_OVERRUN\_ERROR on the next callback. + }{ + \_\_u8* buffer1 & Pointer to the start of the filtered section, e.g. + within the circular buffer of the demux driver.\\ + size\_t buffer1\_length & 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 circular + buffer.\\ + size\_t buffer2\_length & Length of the filtered section data in buffer2, + including headers and CRC.\\ + dmx\_section\_filter\_t* filter & Indicates the filter that triggered the callback.\\ + dmx\_success\_t success & Indicates if there was an error in section reception. + }{ + 0 & Continue filtering.\\ + -1& Stop filtering - has the same effect as a call + to stop\_filtering() on the Section Feed API. +} + +\clearpage + +\devsubsec{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. + +\kifunction{set()}{ + int set ( dmx\_ts\_feed\_t* feed, \_\_u16 pid, size\_t callback\_length, + size\_t circular\_buffer\_size, int descramble, struct timespec timeout); + }{ + This function sets the parameters of a TS feed. + Any filtering in progress on the TS feed + must be stopped before calling this function. + }{ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data.\\ + \_\_u16 pid & PID value to filter. Only the TS packets carrying the specified PID will + be passed to the API client.\\ + size\_t callback\_length & 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 circular\_buffer\_size & Size of the circular buffer for the filtered TS packets.\\ + int descramble & If non-zero, descramble the filtered TS packets.\\ + struct timespec timeout & Maximum time to wait before + delivering received TS packets to the client. + }{ + 0 & The function was completed without errors.\\ + -ENOMEM & Not enough memory for the requested buffer size.\\ + -ENOSYS & No descrambling facility available for TS.\\ + -EINVAL & Bad parameter. +} + + +\kifunction{start\_filtering()}{ + int start\_filtering(dmx\_ts\_feed\_t* feed); + }{ + 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(). + }{ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{stop\_filtering()}{ + int stop\_filtering(dmx\_ts\_feed\_t* feed); + }{ + Stops filtering TS packets on this TS feed. + }{ + dmx\_ts\_feed\_t* feed & Pointer to the TS feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\clearpage + +\devsubsec{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. + + +\kifunction{set()}{ + int set(dmx\_section\_feed\_t* feed, \_\_u16 pid, size\_t circular\_buffer\_size, + int descramble, int check\_crc); + }{ + This function sets the parameters of a section feed. Any filtering in progress on the + section feed must be stopped before calling this function. + If descrambling is enabled, the payload\_scrambling\_control and + address\_scrambling\_control fields of received DVB datagram sections should be + observed. If either one is non-zero, the section should be descrambled either in + hardware or using the functions descramble\_mac\_address() and + descramble\_section\_payload() of the demux API. Note that according to the + MPEG-2 Systems specification, only the payloads of private sections can be + scrambled while the rest of the section data must be sent in the clear. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + \_\_u16 pid & PID value to filter; only the TS packets + carrying the specified PID will be accepted.\\ + size\_t circular\_buffer\_size & Size of the circular buffer for filtered sections.\\ + int descramble & If non-zero, descramble any sections that are scrambled.\\ + int check\_crc & If non-zero, check the CRC values of filtered sections. + }{ + 0 & The function was completed without errors.\\ + -ENOMEM & Not enough memory for the requested buffer size.\\ + -ENOSYS & No descrambling facility available for sections.\\ + -EINVAL & Bad parameters. +} + +\kifunction{allocate\_filter()}{ + int allocate\_filter(dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t** filter); + }{ + This function is used to allocate a section filter on the demux. + It should only be called when no filtering is in progress on this section feed. + If a filter cannot be allocated, the function fails with -ENOSPC. + See in section \ref{sectionfilter} for the format of the section filter. \\ + 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. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + dmx\_section\_filter\_t** filter & Pointer to the allocated filter. + }{ + 0 & The function was completed without errors.\\ + -ENOSPC & No filters of given type and length available.\\ + -EINVAL & Bad parameters. +} + +\kifunction{release\_filter()}{ + int release\_filter ( dmx\_section\_feed\_t* feed, dmx\_section\_filter\_t* filter); + }{ + 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. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + dmx\_section\_filter\_t* filter & I/O Pointer to the instance data of a section filter. + }{ + 0 & The function was completed without errors.\\ + -ENODEV & No such filter allocated.\\ + -EINVAL & Bad parameter. +} + +\kifunction{start\_filtering()}{ + int start\_filtering ( dmx\_section\_feed\_t* feed ); + }{ + 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(). + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data.\\ + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + +\kifunction{stop\_filtering()}{ + int stop\_filtering ( dmx\_section\_feed\_t* feed ); + }{ + 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. + }{ + dmx\_section\_feed\_t* feed & Pointer to the section feed API and instance data. + }{ + 0 & The function was completed without errors.\\ + -EINVAL & Bad parameter. +} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex new file mode 100644 index 000000000..88342c3a6 --- /dev/null +++ b/dvb-spec/dvbapi/sec.tex @@ -0,0 +1,282 @@ +\devsec{DVB SEC API} + +The DVB SEC device controls the Satellite Equipment Control of +the DVB hardware, i.e. DiSEqC and V-SEC. +It is accessed through \texttt{/dev/ost/sec}. + +\devsubsec{SEC Data Types} + +\devsubsubsec{secDiseqcCmd} +\label{secdiseqccmd} + +\begin{verbatim} +struct secDiseqcCmd { + uint8_t addr; + uint8_t cmd; + uint8_t numParams; + uint8_t params[SEC_MAX_DISEQC_PARAMS]; +}; +\end{verbatim} + + +\devsubsubsec{secVoltage} +\label{secvoltage} + +\begin{verbatim} +typedef uint32_t secVoltage; +\end{verbatim} +\begin{verbatim} +enum { + SEC_VOLTAGE_OFF, + SEC_VOLTAGE_LT, + SEC_VOLTAGE_13, + SEC_VOLTAGE_13_5, + SEC_VOLTAGE_18, + SEC_VOLTAGE_18_5 +}; +\end{verbatim} + + +\devsubsubsec{secToneMode} +\label{sectonemode} + +\begin{verbatim} +typedef uint32_t secToneMode; +\end{verbatim} +\begin{verbatim} +typedef enum { + SEC_TONE_ON, + SEC_TONE_OFF +} secToneMode_t; +\end{verbatim} + + +\devsubsubsec{secMiniCmd} +\label{secminicmd} + +\begin{verbatim} +typedef uint32_t secMiniCmd; +\end{verbatim} +\begin{verbatim} +typedef enum { + SEC_MINI_NONE, + SEC_MINI_A, + SEC_MINI_B +} secMiniCmd_t; +\end{verbatim} +\begin{verbatim} +struct secStatus { + int32_t busMode; + secVoltage selVolt; + secToneMode contTone; +}; +\end{verbatim} + +\begin{verbatim} +enum { + SEC_BUS_IDLE, + SEC_BUS_BUSY, + SEC_BUS_OFF, + SEC_BUS_OVERLOAD +}; +\end{verbatim} + + +\devsubsubsec{secCommand} +\label{seccommand} + +\begin{verbatim} +struct secCommand { + int32_t type; + union { + struct secDiseqcCmd diseqc; + uint8_t vsec; + uint32_t pause; + } u; +}; +\end{verbatim} + + +\devsubsubsec{secCmdSequence} +\label{seccmdsequence} + +\begin{verbatim} +struct secCmdSequence { + secVoltage voltage; + secMiniCmd miniCommand; + secToneMode continuousTone; + + uint32_t numCommands; + struct secCommand* commands; +}; +\end{verbatim} + +\begin{verbatim} +enum { + SEC_CMDTYPE_DISEQC, + SEC_CMDTYPE_VSEC, + SEC_CMDTYPE_PAUSE +}; +\end{verbatim} + +\begin{verbatim} +typedef enum { + SEC_DISEQC_SENT, + SEC_VSEC_SENT, + SEC_PAUSE_COMPLETE, + SEC_CALLBACK_ERROR +} secCallback_t; +\end{verbatim} + +\clearpage + +\devsubsec{SEC Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + This system call opens a named SEC device for subsequent use. + If the device is opened in read-only mode, only status and statistics + monitoring is allowed. If the device is opened in read/write mode, all + types of operations can be performed. + Any number of applications can have simultaneous access to the device. + }{ + const char *deviceName & Name of specific SEC device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & The optional flag O\_NONBLOCK is not supported. If O\_NONBLOCK is set, + open() and most other subsequent calls to the device will return -1 and + set errno to EWOULDBLOCK. + The communication with the peripheral devices is sequential by nature, + so it is probably preferable to use the device in synchronous mode. + This is the motivation for not going through the extra effort of + implementing asynchronous operation of the device. + }{ + ENODEV & Device driver not loaded/available.\\ + EFAULT & deviceName does not refer to a valid memory area.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened SEC device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\ifunction{SEC\_GET\_STATUS}{ + int ioctl(int fd, int request = SEC\_GET\_STATUS, struct secStatus* status);}{ + This call gets the status of the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_GET\_STATUS for this command.\\ + struct secStatus* status & The status of the device.\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EFAULT & status is an invalid pointer.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ + EPERM & File not opened with read permissions.\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{SEC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = SEC\_RESET\_OVERLOAD);}{ + If the bus has been automatically powered off due to power overload, this + ioctl call restores the power to the bus. The call requires read/write + access to the device. + This call has no effect if the device is manually powered off. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_RESET\_OVERLOAD for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{SEC\_SEND\_SEQUENCE}{ +int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); +}{ +This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC +commands. The first version of the SEC device does not support V-SEC +signaling and it aborts the operation with an error code if a V-SEC +command is detected in the input data.\\ +\begin{itemize} +\item[$\bullet$] The call will fail with errno set to EBUSOVERLOAD if the bus is +overloaded. If the bus is overloaded, SEC\_RESET\_OVERLOAD can be +called and the operation can be retried. +\item[$\bullet$] If seq.numCommands equals 0 and seq.miniCommand equals SEC\_MINI\_NONE, +the bus voltage will be switched and the continuous 22kHz tone +generation enabled/disabled immediately. +\end{itemize}\\ +This operation is atomic. If several processes calls this ioctl +simultaneously, the operations will be serialized so a complete sequence +is sent at a time. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals SEC\_SEND\_SEQUENCE for this command.\\ + struct secCmdSequence *seq & Pointer to the command sequence to be transmitted.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & Seq points to an invalid address.\\ + EINVAL & The data structure referred to by seq is invalid in some way.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ + EBUSMODE & The device is not prepared for transmission + (e.g. it might be manually powered off).\\ + EBUSOVERLOAD & Bus overload has occurred.\\ +} + + +\ifunction{SEC\_SET\_TONE}{ +int ioctl(int fd, int request = SEC\_SET\_TONE, secToneMode tone); +}{ +This call is used to set the generation of the continuous 22kHz tone. +The possibility to just change the tone mode is already provided by +ioctl SEC\_SEND\_SEQUENCE, but SEC\_SET\_TONE is an easier to use interface. +To keep the transmission of a command sequence as +an atomic operation, SEC\_SET\_TONE will block if a transmission is in +progress. This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals SEC\_SET\_TONE for this command.\\ +secToneMode tone & The requested tone generation mode (on/off).\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{SEC\_SET\_VOLTAGE}{ +int ioctl(int fd, int request = SEC\_SET\_VOLTAGE, secVoltage voltage); +}{ +This call is used to set the bus voltage. The possibility to just change +the bus voltage is already provided by ioctl SEC\_SEND\_SEQUENCE, but +SEC\_SET\_VOLTAGE is an easier to use interface. +To keep the transmission of a command sequence as +an atomic operation, SEC\_SET\_VOLTAGE will block if a transmission is in +progress. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals SEC\_SET\_VOLTAGE for this command.\\ +secVoltage voltage & The requested bus voltage.\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex new file mode 100644 index 000000000..574464d23 --- /dev/null +++ b/dvb-spec/dvbapi/title.tex @@ -0,0 +1,24 @@ +\pagenumbering{arabic} +\pagestyle{empty} +\title{\huge\textbf{LINUX DVB API}} + +\author{ +\includegraphics{cimlogo.psi}\\ + Convergence integrated media GmbH\\\\ + Dr. Ralph J.K. Metzler\\ + \texttt{}\\\\ + Dr. Marcus O.C. Metzler\\ + \texttt{} +% Rosenthalerstr. 51\\ +% 10178 Berlin\\Germany +} +\date{02/14/2002\\V 0.9.4} +\maketitle + +\newpage + +%\end{titlepage} +% Local Variables: +% mode: latex +% TeX-master: "dvbapi" +% End: diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex new file mode 100644 index 000000000..ee61ad78b --- /dev/null +++ b/dvb-spec/dvbapi/video.tex @@ -0,0 +1,686 @@ +\devsec{DVB Video Device} + +The DVB video device controls the MPEG2 video decoder of the DVB hardware. +It can be accessed through \texttt{/dev/ost/video}. +The include file \texttt{ost/video.h} defines the data types and lists +all I/O calls. Please note that some DVB cards don't have their own +MPEG decoder, which results in the omission of the audio and video +device as well as the video4linux device. + +\devsubsec{Video Data Types} + +\devsubsubsec{video_format\_t} +\label{videoformat} + +The \texttt{video_format\_t} data type defined by +\begin{verbatim} +typedef enum { + VIDEO_FORMAT_4_3, + VIDEO_FORMAT_16_9 +} video_format_t; +\end{verbatim} +is used in the VIDEO\_SET\_FORMAT function (\ref{videosetformat}) to +tell the driver which aspect ratio the output hardware (e.g. TV) has. +It is also used in the data structures video_status (\ref{videostatus}) +returned by VIDEO\_GET\_STATUS (\ref{videogetstatus}) and +video_event (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) +which report about the display format of the current video stream. + +\devsubsubsec{videoDisplayFormat\_t} +\label{videodispformat} + +In case the display format of the video stream and of the +display hardware differ the application has to specify how to handle +the cropping of the picture. +This can be done using the VIDEO\_SET\_DISPLAY\_FORMAT call +(\ref{videosetdisplayformat}) which accepts +\begin{verbatim} +typedef enum { + VIDEO_PAN_SCAN, + VIDEO_LETTER_BOX, + VIDEO_CENTER_CUT_OUT +} video_displayformat_t; +\end{verbatim} +as argument. + + +\devsubsubsec{video stream source} +\label{videostreamsource} +The video stream source is set through the VIDEO\_SELECT\_SOURCE +call and can take the following values, depending on whether we are +replaying from an internal (demuxer) or external (user write) source. +\begin{verbatim} +typedef enum { + VIDEO_SOURCE_DEMUX, + VIDEO_SOURCE_MEMORY +} video_stream_source_t; +\end{verbatim} +VIDEO\_SOURCE\_DEMUX selects the demultiplexer (fed +either by the frontend or the DVR device) as the source of +the video stream. +If VIDEO\_SOURCE\_MEMORY is selected the stream +comes from the application through the \texttt{write()} +system call. + +\devsubsubsec{video play state} +\label{videoplaystate} +The following values can be returned by the VIDEO\_GET\_STATUS call +representing the state of video playback. +\begin{verbatim} +typedef enum { + VIDEO_STOPPED, + VIDEO_PLAYING, + VIDEO_FREEZED +} video_play_state_t; +\end{verbatim} + + +\devsubsubsec{video event} +\label{videoevent} +The following is the structure of a video event as it is returned by +the VIDEO\_GET\_EVENT call. +\begin{verbatim} +struct video_event { + int32_t type; + time_t timestamp; + union { + video_format_t video_format; + } u; +}; +\end{verbatim} + +\devsubsubsec{video status} +\label{videostatus} +The VIDEO\_GET\_STATUS call returns the following structure informing +about various states of the playback operation. +\begin{verbatim} +struct video_status { + boolean video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; +}; +\end{verbatim} +If video_blank is set video will be blanked out if the channel is changed or +if playback is stopped. Otherwise, the last picture will be displayed. +play_state indicates if the video is currently frozen, stopped, or +being played back. The stream_source corresponds to the seleted source +for the video stream. It can come either from the demultiplexer or from memory. +The video_format indicates the aspect ratio (one of 4:3 or 16:9) +of the currently played video stream. +Finally, display_format corresponds to the selected cropping mode in case the +source video format is not the same as the format of the output device. + + +\devsubsubsec{video display still picture} +\label{videostill} +An I-frame displayed via the VIDEO\_STILLPICTURE call is passed on +within the following structure. +\begin{verbatim} +/* pointer to and size of a single iframe in memory */ +struct video_still_picture { + char *iFrame; + int32_t size; +}; +\end{verbatim} + +\devsubsubsec{video capabilities} +\label{videocaps} +A call to VIDEO\_GET\_CAPABILITIES returns an unsigned integer with +the following bits set according to the hardwares capabilities. +\begin{verbatim} +/* bit definitions for capabilities: */ +/* can the hardware decode MPEG1 and/or MPEG2? */ +#define VIDEO_CAP_MPEG1 1 +#define VIDEO_CAP_MPEG2 2 +/* can you send a system and/or program stream to video device? + (you still have to open the video and the audio device but only + send the stream to the video device) */ +#define VIDEO_CAP_SYS 4 +#define VIDEO_CAP_PROG 8 +/* can the driver also handle SPU, NAVI and CSS encoded data? + (CSS API is not present yet) */ +#define VIDEO_CAP_SPU 16 +#define VIDEO_CAP_NAVI 32 +#define VIDEO_CAP_CSS 64 +\end{verbatim} + + +\devsubsubsec{video system} +\label{videosys} +A call to VIDEO\_SET\_SYSTEM sets the desired video system for TV +output. The following system types can be set: + +\begin{verbatim} +typedef enum { + VIDEO_SYSTEM_PAL, + VIDEO_SYSTEM_NTSC, + VIDEO_SYSTEM_PALN, + VIDEO_SYSTEM_PALNc, + VIDEO_SYSTEM_PALM, + VIDEO_SYSTEM_NTSC60, + VIDEO_SYSTEM_PAL60, + VIDEO_SYSTEM_PALM60 +} video_system_t; +\end{verbatim} + + + +\devsubsubsec{video highlights} +\label{vhilite} +Calling the ioctl VIDEO\_SET\_HIGHLIGHTS posts the SPU highlight +information. The call expects the following format for that information: + +\begin{verbatim} +typedef +struct video_highlight { + boolean active; /* 1=show highlight, 0=hide highlight */ + uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ + /* 3- 0 Background pixel contrast */ + uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */ + /* 3- 0 Emphasis pixel-1 contrast */ + uint8_t color1; /* 7- 4 Pattern pixel color */ + /* 3- 0 Background pixel color */ + uint8_t color2; /* 7- 4 Emphasis pixel-2 color */ + /* 3- 0 Emphasis pixel-1 color */ + uint32_t ypos; /* 23-22 auto action mode */ + /* 21-12 start y */ + /* 9- 0 end y */ + uint32_t xpos; /* 23-22 button color number */ + /* 21-12 start x */ + /* 9- 0 end x */ +} video_highlight_t; +\end{verbatim} + + +\devsubsubsec{video SPU} +\label{videospu} +Calling VIDEO\_SET\_SPU deactivates or activates SPU decoding, +according to the following format: +\begin{verbatim} +typedef +struct video_spu { + boolean active; + int stream_id; +} video_spu_t; +\end{verbatim} + + +\devsubsubsec{video SPU palette} +\label{vspupal} +The following structure is used to set the SPU palette by calling VIDEO\_SPU\_PALETTE: +\begin{verbatim} +typedef +struct video_spu_palette{ /* SPU Palette information */ + int length; + uint8_t *palette; +} video_spu_palette_t; +\end{verbatim} + +\devsubsubsec{video NAVI pack} +\label{videonavi} +In order to get the navigational data the following structure has to +be passed to the ioctl VIDEO\_GET\_NAVI: +\begin{verbatim} +typedef +struct video_navi_pack{ + int length; /* 0 ... 1024 */ + uint8_t data[1024]; +} video_navi_pack_t; +\end{verbatim} + + +\devsubsubsec{video attributes} +\label{vattrib} +The following attributes can be set by a call to VIDEO\_SET\_ATTRIBUTES: +\begin{verbatim} +typedef uint16_t video_attributes_t; +/* bits: descr. */ +/* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ +/* 13-12 TV system (0=525/60, 1=625/50) */ +/* 11-10 Aspect ratio (0=4:3, 3=16:9) */ +/* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */ +/* 7 line 21-1 data present in GOP (1=yes, 0=no) */ +/* 6 line 21-2 data present in GOP (1=yes, 0=no) */ +/* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */ +/* 2 source letterboxed (1=yes, 0=no) */ +/* 0 film/camera mode (0=camera, 1=film (625/50 only)) */ +\end{verbatim} + + +\clearpage + +\devsubsec{Video Function Calls} + +\function{open()}{ + int open(const char *deviceName, int flags);}{ + 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 attempts to + open the device in this mode will fail, and an error-code will be returned. + If the Video Device is opened in O\_RDONLY mode, the only ioctl call that can + be used is VIDEO\_GET\_STATUS. All other call will return an error code. + }{ + const char *deviceName & Name of specific video device.\\ + int flags & A bit-wise OR of the following flags:\\ + & \hspace{1em} O\_RDONLY read-only access\\ + & \hspace{1em} O\_RDWR read/write access\\ + & \hspace{1em} O\_NONBLOCK open in non-blocking mode \\ + & \hspace{1em} (blocking mode is the default)\\ + }{ + ENODEV & Device driver not loaded/available.\\ + EINTERNAL & Internal error.\\ + EBUSY & Device or resource busy.\\ + EINVAL & Invalid argument.\\ +} + +\function{close()}{ + int close(int fd);}{ + This system call closes a previously opened video device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + }{ + EBADF & fd is not a valid open file descriptor.\\ +} + +\function{write()}{ + size\_t write(int fd, const void *buf, size\_t count);}{ + This system call can only be used if VIDEO\_SOURCE\_MEMORY is selected in the + ioctl call VIDEO\_SELECT\_SOURCE. The data provided shall be in PES + format, unless the capability allows other formats. + If O\_NONBLOCK is not specified the function will block until buffer space is + available. The amount of data to be transferred is implied by count. + }{ + 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.\\ + }{ + 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.\\ +} + + +\ifunction{VIDEO\_STOP}{ + int ioctl(fd, int request = VIDEO\_STOP, boolean mode);}{ + 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. +}{ +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.\\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ +} + +\ifunction{VIDEO\_PLAY}{ + int ioctl(fd, int request = VIDEO\_PLAY);}{ + This ioctl call asks the Video Device to start playing a video stream + from the selected source. +}{ +int fd & File descriptor returned by a previous call to open(). \\ +int request & Equals VIDEO\_PLAY for this command. \\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ +} + + +\ifunction{VIDEO\_FREEZE}{ + int ioctl(fd, int request = VIDEO\_FREEZE);}{ + This ioctl call suspends the live video stream being played. + Decoding and playing are frozen. It is then possible to restart + the decoding and playing process of the video stream using the + VIDEO\_CONTINUE command. If VIDEO\_SOURCE\_MEMORY is selected in the + ioctl call VIDEO\_SELECT\_SOURCE, the DVB subsystem will not decode + any more data until the ioctl call VIDEO\_CONTINUE or VIDEO\_PLAY is + performed. +}{ +int fd & File descriptor returned by a previous call to open(). \\ +int request & Equals VIDEO\_FREEZE for this command. \\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ +} + +\ifunction{VIDEO\_CONTINUE}{ + int ioctl(fd, int request = VIDEO\_CONTINUE);}{ + This ioctl call restarts decoding and playing processes of the video + stream which was played before a call to VIDEO\_FREEZE was made. + }{ + int fd & File descriptor returned by a previous call to open(). \\ + int request & Equals VIDEO\_CONTINUE for this command. \\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error, possibly in the communication with + the DVB subsystem.\\ + } + + +\ifunction{VIDEO\_SELECT\_SOURCE}{ + int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, videoStreamSource\_t source);}{ + This ioctl call informs the video device which source shall be used + for the input data. The possible sources are demux or memory. If + memory is selected, the data is fed to the video device through + the write command. + }{ + 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.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ +} + +\ifunction{VIDEO\_SET\_BLANK}{ + int ioctl(fd, int request = VIDEO\_SET\_BLANK, boolean mode);}{ + This ioctl call asks the Video Device to blank out the picture. +}{ +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.\\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ +EINVAL & Illegal input parameter\\ +} + +\ifunction{VIDEO\_GET\_STATUS}{ +\label{videogetstatus} + int ioctl(fd, int request = VIDEO\_GET\_STATUS, struct video_status *status);}{ + This ioctl call asks the Video Device to return the current status of the device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals VIDEO\_GET\_STATUS for this command.\\ + struct video_status *status & Returns the current status of the Video Device.\\ +}{ +EBADF& fd is not a valid open file descriptor \\ +EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ +EFAULT & status points to invalid address\\ +} + +\ifunction{VIDEO\_GET\_EVENT}{ +\label{videogetevent} + int ioctl(fd, int request = VIDEO\_GET\_EVENT, struct video_event *ev);}{ + This ioctl call returns an event of type video_event if available. + If an event is not available, the behavior depends on whether the device is in + blocking or non-blocking mode. In the latter case, the call fails immediately + with errno set to EWOULDBLOCK. In the former case, the call blocks until an + event becomes available. + The standard Linux poll() and/or select() system calls can be used with the + device file descriptor to watch for new events. For select(), the file + descriptor should be included in the exceptfds argument, and for poll(), + POLLPRI should be specified as the wake-up condition. + Read-only permissions are sufficient for this ioctl call. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request& Equals VIDEO\_GET\_EVENT for this command.\\ + struct video_event *ev & Points to the location where the event, if any, is + to be stored.\\ +}{ +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.\\ +} + +\ifunction{VIDEO\_SET\_DISPLAY\_FORMAT}{ +\label{videosetdisplayformat} + int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, videoDisplayFormat\_t format);}{ + This ioctl call asks the Video Device to select the video format to be applied + by the MPEG chip on the video. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_DISPLAY\_FORMAT for this command.\\ + videoDisplayFormat\_t format & Selects the video format to be used.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EINVAL & Illegal parameter format.\\ +} + +\ifunction{VIDEO\_STILLPICTURE}{ + int ioctl(fd, int request = VIDEO\_STILLPICTURE, struct video_still_picture *sp);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_STILLPICTURE for this command.\\ + struct video_still_picture *sp& + Pointer to a location where an I-frame and size is stored.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EFAULT & sp points to an invalid iframe.\\ +} + +\ifunction{VIDEO\_FAST\_FORWARD}{ + int ioctl(fd, int request = VIDEO\_FAST\_FORWARD, int nFrames);}{ + This ioctl call asks the Video Device to skip decoding of N number of I-frames. + This call can only be used if VIDEO\_SOURCE\_MEMORY is selected. + }{ + 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.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EPERM & Mode VIDEO\_SOURCE\_MEMORY not selected.\\ + EINVAL & Illegal parameter format.\\ +} + +\ifunction{VIDEO\_SLOWMOTION}{ + int ioctl(fd, int request = VIDEO\_SLOWMOTION, int nFrames);}{ + 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. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SLOWMOTION for this command.\\ + int nFrames & The number of times to repeat each frame.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINTERNAL & Internal error.\\ + EPERM & Mode VIDEO\_SOURCE\_MEMORY not selected.\\ + EINVAL & Illegal parameter format.\\ +} + +\ifunction{VIDEO\_GET\_CAPABILITIES}{ + int ioctl(fd, int request = VIDEO\_GET\_CAPABILITIES, unsigned int *cap);}{ + This ioctl call asks the video device about its decoding capabilities. + On success it returns and integer which has bits set according to the + defines in section \ref{videocaps}. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_GET\_CAPABILITIES for this command.\\ + unsigned int *cap & Pointer to a location where to store the + capability information.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EFAULT & cap points to an invalid iframe.\\ +} + +\ifunction{VIDEO\_SET\_ID}{ + int ioctl(int fd, int request = VIDEO\_SET\_ID, int id);}{ + This ioctl selects which sub-stream is to be decoded if a program or + system stream is sent to the video device. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_ID for this command.\\ + int id& video sub-stream id + }{ + EBADF& fd is not a valid open file descriptor.\\ + EINTERNAL & Internal error.\\ + EINVAL & Invalid sub-stream id. +} + +\ifunction{VIDEO\_CLEAR\_BUFFER}{ + int ioctl(fd, int request = VIDEO\_CLEAR\_BUFFER);}{ + This ioctl call clears all video buffers in the driver and + in the decoder hardware. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_CLEAR\_BUFFER for this command.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ +} + +\ifunction{VIDEO\_SET\_STREAMTYPE}{ + int ioctl(fd, int request = VIDEO\_SET\_STREAMTYPE, int type);}{ + This ioctl tells the driver which kind of stream to expect + being written to it. If this call is not used the default of video PES + is used. Some drivers might not support this call and always expect PES. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_STREAMTYPE for this command.\\ + int type & stream type\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& type is not a valid or supported stream type.\\ +} + +\ifunction{VIDEO\_SET\_FORMAT}{ +\label{videosetformat} + int ioctl(fd, int request = VIDEO\_SET\_FORMAT, video_format\_t format); +}{ + This ioctl sets the screen format (aspect ratio) of the connected + output device (TV) so that the output of the decoder can + be adjusted accordingly. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_FORMAT for this command.\\ + video_format\_t format& video format of TV as defined in section \ref{videoformat}.\\ + }{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& format is not a valid video format.\\ +} + +\ifunction{VIDEO\_SET\_SYSTEM}{ +\label{videosetsystem} + int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , videoSystem\_t system); +}{ + This ioctl sets the television output format. The format (see section + \ref{videosys}) may vary from the color format of the displayed MPEG + stream. If the hardware is not able to display the requested format + the call will return an error. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_FORMAT for this command.\\ + videoSystem\_t system& video system of TV output.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& system is not a valid or supported video system.\\ +} + +\ifunction{VIDEO\_SET\_HIGHLIGHT}{ +\label{videosethighlight} + int ioctl(fd, int request = VIDEO\_SET\_HIGHLIGHT ,video_highlight\_t *vhilite) +}{ + This ioctl sets the SPU highlight information for the menu access of + a DVD. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_HIGHLIGHT for this command.\\ + video_highlight\_t *vhilite& SPU Highlight information according to + section \ref{vhilite}.\\ +}{ + EBADF& fd is not a valid open file descriptor. \\ + EINVAL& input is not a valid highlight setting.\\ +} + + +\ifunction{VIDEO\_SET\_SPU}{ +\label{videosetspu} + int ioctl(fd, int request = VIDEO\_SET\_SPU , video_spu\_t *spu) +}{ + This ioctl activates or deactivates SPU decoding in a DVD input + stream. It can only be used, if the driver is able to handle a DVD + stream. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_SPU for this command.\\ + video_spu\_t *spu& SPU decoding (de)activation and subid setting + according to section \ref{videospu}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& input is not a valid spu setting or driver cannot handle SPU.\\ +} + + +\ifunction{VIDEO\_SET\_SPU\_PALETTE}{ +\label{videosetspupalette} + int ioctl(fd, int request = VIDEO\_SET\_SPU\_PALETTE ,video_spu_palette\_t *palette ) +}{ + This ioctl sets the SPU color palette. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_SPU\_PALETTE for this command.\\ + video_spu_palette\_t *palette& SPU palette according to section \ref{vspupal}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& input is not a valid palette or driver doesn't handle SPU.\\ +} + + + +\ifunction{VIDEO\_GET\_NAVI}{ +\label{videosetnavi} + int ioctl(fd, int request = VIDEO\_GET\_NAVI , video_navi_pack\_t *navipack) +}{ + This ioctl returns navigational information from the DVD stream. This is + especially needed if an encoded stream has to be decoded by the hardware. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_GET\_NAVI for this command.\\ + video_navi_pack\_t *navipack& PCI or DSI pack (private stream 2) + according to section \ref{videonavi}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EFAULT& driver is not able to return navigational information\\ +} + + +\ifunction{VIDEO\_SET\_ATTRIBUTES}{ +\label{videosetattributes} + int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,videoAttributes\_t + vattr) +}{ + This ioctl is intended for DVD playback and allows you to set + certain information about the stream. Some hardware may not need + this information, but the call also tells the hardware to prepare + for DVD playback. +}{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals VIDEO\_SET\_ATTRIBUTE for this command.\\ + videoAttributes\_t vattr& video attributes according to section \ref{vattrib}.\\ +}{ + EBADF& fd is not a valid open file descriptor \\ + EINVAL& input is not a valid attribute setting.\\ +} + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/valgrind-1.0pre3-dvb.patch b/dvb-spec/valgrind-1.0pre3-dvb.patch new file mode 100644 index 000000000..6c61ceb91 --- /dev/null +++ b/dvb-spec/valgrind-1.0pre3-dvb.patch @@ -0,0 +1,154 @@ +diff -ur valgrind-1.0pre3.orig/vg_syscall_mem.c valgrind-1.0pre3/vg_syscall_mem.c +--- valgrind-1.0pre3.orig/vg_syscall_mem.c Thu Jun 20 09:23:49 2002 ++++ valgrind-1.0pre3/vg_syscall_mem.c Mon Jul 8 19:55:45 2002 +@@ -2038,6 +2038,136 @@ + sizeof(struct cdrom_msf)); + KERNEL_DO_SYSCALL(tid,res); + break; ++ ++ /* DVB (Digital Video Broadcasting) related stuff ++ * http://www.linuxtv.org ++ */ ++ case FE_GET_INFO: ++ must_be_writable(tst, "ioctl(FE_GET_INFO)", arg3, ++ sizeof(struct dvb_frontend_info)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_frontend_info)); ++ break; ++ case FE_DISEQC_RESET_OVERLOAD: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_SEND_MASTER_CMD: ++ must_be_readable(tst, "ioctl(FE_DISEQC_SEND_MASTER_CMD)", arg3, ++ sizeof(struct dvb_diseqc_master_cmd)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_RECV_SLAVE_REPLY: ++ must_be_writable(tst, "ioctl(FE_DISEQC_RECV_SLAVE_REPLY)", arg3, ++ sizeof(struct dvb_diseqc_slave_reply)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_diseqc_slave_reply)); ++ break; ++ case FE_DISEQC_SEND_BURST: ++ case FE_SET_TONE: ++ case FE_SET_VOLTAGE: ++ case FE_ENABLE_HIGH_LNB_VOLTAGE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_READ_STATUS: ++ must_be_writable(tst, "ioctl(FE_READ_STATUS)", arg3, ++ sizeof(fe_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(fe_status_t)); ++ break; ++ case FE_READ_BER: ++ must_be_writable(tst, "ioctl(FE_READ_BER)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint32_t)); ++ break; ++ case FE_READ_SIGNAL_STRENGTH: ++ must_be_writable(tst, "ioctl(FE_READ_SIGNAL_STRENGTH)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_SNR: ++ must_be_writable(tst, "ioctl(FE_READ_SNR)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_UNCORRECTED_BLOCKS: ++ must_be_writable(tst, "ioctl(FE_READ_UNCORRECTED_BLOCKS)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint32_t)); ++ break; ++ case FE_SET_FRONTEND: ++ must_be_readable(tst, "ioctl(FE_SET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_FRONTEND: ++ must_be_writable(tst, "ioctl(FE_GET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_frontend_parameters)); ++ break; ++ case FE_GET_EVENT: ++ must_be_writable(tst, "ioctl(FE_GET_EVENT)", arg3, ++ sizeof(struct dvb_frontend_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_frontend_event)); ++ break; ++ case DMX_START: ++ case DMX_STOP: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_FILTER: ++ must_be_readable(tst, "ioctl(DMX_SET_FILTER)", arg3, ++ sizeof(struct dmx_sct_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_PES_FILTER: ++ must_be_readable(tst, "ioctl(DMX_SET_PES_FILTER)", arg3, ++ sizeof(struct dmx_pes_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_BUFFER_SIZE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_GET_EVENT: ++ must_be_writable(tst, "ioctl(DMX_GET_EVENT)", arg3, ++ sizeof(struct dmx_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dmx_event)); ++ break; ++ case DMX_GET_PES_PIDS: ++ must_be_writable(tst, "ioctl(DMX_GET_PES_PIDS)", arg3, ++ 5*sizeof(dvb_pid_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, 5*sizeof(dvb_pid_t)); ++ break; ++ case DMX_GET_CAPS: ++ must_be_writable(tst, "ioctl(DMX_GET_CAPS)", arg3, ++ sizeof(dmx_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(dmx_caps_t)); ++ break; ++ case DMX_SET_SOURCE: ++ must_be_readable(tst, "ioctl(DMX_SET_SOURCE)", arg3, ++ sizeof(dmx_source_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ + /* We don't have any specific information on it, so + try to do something reasonable based on direction and + size bits. The encoding scheme is described in +diff -ur valgrind-1.0pre3.orig/vg_unsafe.h valgrind-1.0pre3/vg_unsafe.h +--- valgrind-1.0pre3.orig/vg_unsafe.h Thu Jun 13 18:02:37 2002 ++++ valgrind-1.0pre3/vg_unsafe.h Mon Jul 8 19:56:20 2002 +@@ -85,6 +85,10 @@ + + #include + ++#include ++#include ++#include ++#include + + /*--------------------------------------------------------------------*/ + /*--- end vg_unsafe.h ---*/ -- cgit v1.2.3 From a801585585baeadfc1a94c685ebd83304640ff54 Mon Sep 17 00:00:00 2001 From: holger Date: Thu, 10 Oct 2002 16:46:21 -0300 Subject: more CodingStyle racism --- dvb-spec/dvbapi/demux.tex | 12 ++++++------ dvb-spec/dvbapi/examples.tex | 12 ++++++------ dvb-spec/dvbapi/frontend.tex | 4 ++-- dvb-spec/dvbapi/video.tex | 2 +- dvb-spec/valgrind-1.0pre3-dvb.patch | 4 ++-- 5 files changed, 17 insertions(+), 17 deletions(-) diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex index 3607bbffc..5a8cc1e9a 100644 --- a/dvb-spec/dvbapi/demux.tex +++ b/dvb-spec/dvbapi/demux.tex @@ -6,7 +6,7 @@ It can be accessed through \texttt{/dev/ost/demux}. \devsubsec{Demux Data Types} \begin{verbatim} -typedef uint16_t dvb_pid_t; +typedef uint16_t uint16_t; \end{verbatim} @@ -96,7 +96,7 @@ typedef struct dmx_filter \begin{verbatim} struct dmx_sct_filter_params { - dvb_pid_t pid; + uint16_t pid; dmx_filter_t filter; uint32_t timeout; uint32_t flags; @@ -113,10 +113,10 @@ struct dmx_sct_filter_params \begin{verbatim} struct dmx_pes_filter_params { - dvb_pid_t pid; + uint16_t pid; dmx_input_t input; dmx_output_t output; - dmx_pes_type_t pesType; + dmx_pes_type_t pes_type; uint32_t flags; }; \end{verbatim} @@ -200,7 +200,7 @@ struct dmx_event 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, + in a buffer overflow error. In this case EOVERFLOW will be returned, and the circular buffer will be emptied. This call is blocking if there is no data to return, i.e. the process will be put to sleep waiting for data, unless the O\_NONBLOCK flag is @@ -222,7 +222,7 @@ struct dmx_event EBADF & fd is not a valid open file descriptor.\\ ECRC & Last section had a CRC error - no data returned. The buffer is flushed.\\ - EBUFFEROVERFLOW & \\ + EOVERFLOW & \\ & The filtered data was not read from the buffer in due time, resulting in non-read data being lost. The buffer is flushed.\\ diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex index ea2797481..fa5c24b48 100644 --- a/dvb-spec/dvbapi/examples.tex +++ b/dvb-spec/dvbapi/examples.tex @@ -157,7 +157,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, printf("Getting QPSK event\n"); if ( ioctl(front, FE_GET_EVENT, &event) - == -EBUFFEROVERFLOW){ + == -EOVERFLOW){ perror("qpsk get event"); return -1; } @@ -180,7 +180,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, pesFilterParams.pid = vpid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pesType = DMX_PES_VIDEO; + pesFilterParams.pes_type = DMX_PES_VIDEO; pesFilterParams.flags = DMX_IMMEDIATE_START; if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ perror("set_vpid"); @@ -190,7 +190,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, pesFilterParams.pid = apid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pesType = DMX_PES_AUDIO; + pesFilterParams.pes_type = DMX_PES_AUDIO; pesFilterParams.flags = DMX_IMMEDIATE_START; if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ perror("set_apid"); @@ -200,7 +200,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, pesFilterParams.pid = tpid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_DECODER; - pesFilterParams.pesType = DMX_PES_TELETEXT; + pesFilterParams.pes_type = DMX_PES_TELETEXT; pesFilterParams.flags = DMX_IMMEDIATE_START; if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ perror("set_tpid"); @@ -273,7 +273,7 @@ int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) pesFilterParams.pid = vpid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pesType = DMX_PES_VIDEO; + pesFilterParams.pes_type = DMX_PES_VIDEO; pesFilterParams.flags = DMX_IMMEDIATE_START; if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ perror("DEMUX DEVICE"); @@ -282,7 +282,7 @@ int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) pesFilterParams.pid = apid; pesFilterParams.input = DMX_IN_FRONTEND; pesFilterParams.output = DMX_OUT_TS_TAP; - pesFilterParams.pesType = DMX_PES_AUDIO; + pesFilterParams.pes_type = DMX_PES_AUDIO; pesFilterParams.flags = DMX_IMMEDIATE_START; if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ perror("DEMUX DEVICE"); diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index cb3285d06..e41ef3d54 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -591,7 +591,7 @@ by the driver so far. 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 + oldest event is discarded from the queue, and an error (EOVERFLOW) occurs the next time the queue is read. After reporting the error condition in this fashion, subsequent QPSK\_GET\_EVENT calls will return events from the queue as usual.\\ @@ -606,7 +606,7 @@ by the driver so far. EFAULT& ev points to invalid address.\\ EWOULDBLOCK & There is no event pending, and the device is in non-blocking mode.\\ - EBUFFEROVERFLOW &\\ + EOVERFLOW &\\ & Overflow in event queue - one or more events were lost.\\ } diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex index ee61ad78b..d33f03c83 100644 --- a/dvb-spec/dvbapi/video.tex +++ b/dvb-spec/dvbapi/video.tex @@ -440,7 +440,7 @@ EFAULT & status points to invalid address\\ 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 & \\ +EOVERFLOW & \\ &Overflow in event queue - one or more events were lost.\\ } diff --git a/dvb-spec/valgrind-1.0pre3-dvb.patch b/dvb-spec/valgrind-1.0pre3-dvb.patch index 6c61ceb91..173aaecc5 100644 --- a/dvb-spec/valgrind-1.0pre3-dvb.patch +++ b/dvb-spec/valgrind-1.0pre3-dvb.patch @@ -117,10 +117,10 @@ diff -ur valgrind-1.0pre3.orig/vg_syscall_mem.c valgrind-1.0pre3/vg_syscall_mem. + break; + case DMX_GET_PES_PIDS: + must_be_writable(tst, "ioctl(DMX_GET_PES_PIDS)", arg3, -+ 5*sizeof(dvb_pid_t)); ++ 5*sizeof(uint16_t)); + KERNEL_DO_SYSCALL(tid,res); + if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, 5*sizeof(dvb_pid_t)); ++ make_readable (arg3, 5*sizeof(uint16_t)); + break; + case DMX_GET_CAPS: + must_be_writable(tst, "ioctl(DMX_GET_CAPS)", arg3, -- cgit v1.2.3 From 913350c2997c22fa120029c010859c8bcf12fe12 Mon Sep 17 00:00:00 2001 From: holger Date: Tue, 29 Oct 2002 06:20:39 -0300 Subject: refer to API version 3 not 2 --- dvb-spec/HOWTO-use-the-frontend-api | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dvb-spec/HOWTO-use-the-frontend-api b/dvb-spec/HOWTO-use-the-frontend-api index 52bc2836e..538f5d05e 100644 --- a/dvb-spec/HOWTO-use-the-frontend-api +++ b/dvb-spec/HOWTO-use-the-frontend-api @@ -41,7 +41,7 @@ How to determine the API version? Check in your configure script for #include , include it and check the DVB_API_VERSION #define. - Currently we use version 2, it will be incremented whenever an API change + Currently we use version 3, it will be incremented whenever an API change meets the CVS main branch. ------------------------------------------------------------------------------- -- cgit v1.2.3 From b12bb27ebff9dfdc48d0d6fb9ee83914f8e2bad7 Mon Sep 17 00:00:00 2001 From: holger Date: Tue, 29 Oct 2002 07:34:35 -0300 Subject: add some words about 'what the heck is a frontend' --- dvb-spec/HOWTO-use-the-frontend-api | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/dvb-spec/HOWTO-use-the-frontend-api b/dvb-spec/HOWTO-use-the-frontend-api index 538f5d05e..7f5456d1e 100644 --- a/dvb-spec/HOWTO-use-the-frontend-api +++ b/dvb-spec/HOWTO-use-the-frontend-api @@ -46,10 +46,25 @@ How to determine the API version? ------------------------------------------------------------------------------- -What do you have to do to set up a your frontend? +What is a DVB frontend? + + the term 'frontend' refers to this part of the DVB adapter which receives + an MPEG transport stream and will feed it later into the Demultiplexer. + Whenever you want to receive MPEG streams via satellite, antenna or cable + you have to set up your frontend first. + + When you watch on your DVB card or into your SetTopBox the frontend is usually + the combination of a demodulator chip and a small silver metal box with the + HF electronic. Usually the demodulator is built into this metal box. + +------------------------------------------------------------------------------- + +What do you have to do to set up your frontend? First you should try to determine the type of your frontend. + #include + struct dvb_frontend_info info; int fd; -- cgit v1.2.3 From dfcfc66af625ee81810782a807632a265df83254 Mon Sep 17 00:00:00 2001 From: holger Date: Tue, 29 Oct 2002 07:35:02 -0300 Subject: some words about how to use the demux and section filter API --- dvb-spec/HOWTO-use-the-demux-api | 190 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 dvb-spec/HOWTO-use-the-demux-api diff --git a/dvb-spec/HOWTO-use-the-demux-api b/dvb-spec/HOWTO-use-the-demux-api new file mode 100644 index 000000000..2f1fe8c3d --- /dev/null +++ b/dvb-spec/HOWTO-use-the-demux-api @@ -0,0 +1,190 @@ + +------------------------------------------------------------------------------- + +What has changed since the old Nokia OST API? + + file naming: + - /dev/ost directory is now called /dev/dvb + - each DVB adapter has it's own directory /dev/dvb/adapterX + - here you'll find a number of frontend devices /dev/dvb/adapterX/dmxY + - driver header directory is located now in /usr/include/linux/dvb/ + - we have a linux/dvb/version.h file, this is included by all headers which + don't use the original OST API anymore + + struct naming: + - we follow the kernel naming scheme and try to get the namespace clean, + these changes are mostly syntactical + + new feature: + - section filters have a mode field now, you can set not-equal filters + where you will get only notified when the related bits change + +------------------------------------------------------------------------------- + +How to determine the API version? + + Check in your configure script for #include , + include it and check the DVB_API_VERSION #define. + + Currently we use version 3, it will be incremented whenever an API change + meets the CVS main branch. + +------------------------------------------------------------------------------- + +What is a demultiplexer? + + The demultiplexer in your DVB system cares about the routing of an MPEG2 + stream you feed into the DVB adapter either by read/write system calls, + by using stream inputs of the demultiplexer or the frontend(s). + + Using the demux API you can set up the stream routing and set up filters to + filter the interesting parts of the input streams only. + +------------------------------------------------------------------------------- + +I have set up the frontend and now I want to see some video! +What do I have to do? + + When you have an MPEG video decoder on board we can set up the demultiplexer + to feed the related PES packets into the MPEG decoder: + + #include + + struct dmx_pes_filter_params pesfilter; + + if ((fd = open("/dev/dvb/adapter0/demux0", O_RDWR) < 0) { + perror ("open failed"); + return -1; + } + + pesfilter.pid = pid; + pesfilter.input = DMX_IN_FRONTEND; + pesfilter.output = DMX_OUT_DECODER; + pesfilter.pes_type = DMX_PES_VIDEO; + pesfilter.flags = DMX_IMMEDIATE_START; + + if (ioctl(fd, DMX_SET_PES_FILTER, &pesfilter) < 0) { + perror ("ioctl DMX_SET_PES_FILTER failed"); + return -1; + } + + This will unpack the payload from all transport stream packets with + payload ID and feed it into the MPEG decoder. When pes_type is set + to DMX_PES_VIDEO it will be handled as video data. Other types are + DMX_PES_AUDIO, DMX_PES_TELETEXT, DMX_PES_SUBTITLE which will be fed into + the corresponding decoders. + + Open such a PES filter for each substream you want to decode. + + DMX_PES_PCR is used by the decoder to achieve a correct timing syncronisation + for the partial audio/video/... substreams. + + Note that you have to keep the frontend and demux filedescriptor open until + you are not interested in the stream anymore. Old API versions did not shut + down the demodulator and decoder, new driver versions can be configured to + power down after the device is closed. + +------------------------------------------------------------------------------- + +I want to record a stream to disk! How? + + Set up a filter for each substream you want to record as above but set + the pesfilter.output field to DMX_OUT_TAP. Then you can use read() calls + to receive the PES packets. + + When you want to receive transport stream packets use DMX_OUT_TS_TAP and + read the stream from /dev/dvb/adapter0/dvr0. + + Don't forget to keep all device filedescriptors you use open. + +------------------------------------------------------------------------------- + +I want to play back a recorded stream from disk! How? + + Just do the opposite as above. pesfilter.input is now DMX_IN_DVR. + Write your transport stream into the dvr device. + +------------------------------------------------------------------------------- + +What the heck are section filters? + + On some pid's in an MPEG2 stream data is transmitted in form of sections. + These sections describe the stream content, provider data, service + information and other things. + + Here a short list of some pid's where section data is transmitted on DVB + streams: + + 0x00 PAT (Program Association Table - refers to PMT's) + 0x10 NIT (Network Information Table - frequency lists etc) + 0x11 SDT (Service Description Table - service names etc) + 0x12 EIT (Event Information Table - event descriptions etc) + 0x14 TDT/TOT (Time and Date Table, Time Offset Table - time and timezone) + + For a complete list look into the ITU H222.0 (MPEG2) and ETSI EN300468 + standards, there you also find some informations how to parse these sections. + + When you want to receive this data the simple way you can set up a section + filter. + +------------------------------------------------------------------------------- + +How to set up a section filter? + + #include + + struct dmx_sct_filter_params sctfilter; + + if ((fd = open("/dev/dvb/adapter0/demux0", O_RDWR) < 0) { + perror ("open failed"); + return -1; + } + + memset(&sctfilter, 0, sizeof(struct dmx_sct_filter_params)); + + sctfilter.pid = pid; + sctfilter.flags = DMX_IMMEDIATE_START; + + if (ioctl(fd, DMX_SET_FILTER, &sctfilter) < 0) { + perror ("ioctl DMX_SET_FILTER failed"); + return -1; + } + + Now start subsequent read() calls to receive your sections and parse them. + Your read-buffer should be at least 4096 bytes if you want to receive complete + sections, otherwise you have to put the parts together manually. + + If your read() call returns -EOVERFLOW you were not fast enough to read/ + process the section data, the internal driver ringbuffer was overflown. + + This error is usually not critical since section data is transmitted + periodically. Anyway, you can adjust the ringbuffer size with the + DMX_SET_BUFFER_SIZE ioctl. + +------------------------------------------------------------------------------- + +How to do table id filtering? + + The struct dmx_sct_filter_params contains two fields filter.filter and + filter.mask. set those mask bits to '1' which should be equal to the filter + bits you set: + + /* set up a TDT filter, table id 0x70 */ + sctfilter.pid = pid; + sctfilter.filter.filter[0] = 0x70; + sctfilter.filter.mask[0] = 0xff; + sctfilter.flags = DMX_IMMEDIATE_START; + + Then submit the DMX_SET_FILTER ioctl. + +------------------------------------------------------------------------------- + +What are not-equal filters? + + When you want to get notified about a new version of a section you can set + up a not-equal filter. Set those filter.mode bits to '1' for which the filter + should pass a section when the corresponding section bit is not equal to the + corresponding filter bit. + +------------------------------------------------------------------------------- + -- cgit v1.2.3 From 731ce4b117fe41c6b57bad827652cdd0a8ad882c Mon Sep 17 00:00:00 2001 From: js Date: Tue, 29 Oct 2002 10:09:27 -0300 Subject: =?UTF-8?q?my=202=C2=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- dvb-spec/HOWTO-use-the-demux-api | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/dvb-spec/HOWTO-use-the-demux-api b/dvb-spec/HOWTO-use-the-demux-api index 2f1fe8c3d..ee782db6d 100644 --- a/dvb-spec/HOWTO-use-the-demux-api +++ b/dvb-spec/HOWTO-use-the-demux-api @@ -3,10 +3,12 @@ What has changed since the old Nokia OST API? - file naming: + device node naming: - /dev/ost directory is now called /dev/dvb - each DVB adapter has it's own directory /dev/dvb/adapterX - - here you'll find a number of frontend devices /dev/dvb/adapterX/dmxY + - the devfs devices names are identical to those + creatd by the makedev.napi script on non-devfs systems + - here you'll find a number of demux devices /dev/dvb/adapterX/dmxY - driver header directory is located now in /usr/include/linux/dvb/ - we have a linux/dvb/version.h file, this is included by all headers which don't use the original OST API anymore @@ -45,7 +47,7 @@ What is a demultiplexer? I have set up the frontend and now I want to see some video! What do I have to do? - When you have an MPEG video decoder on board we can set up the demultiplexer + When you have an MPEG video decoder on board you can set up the demultiplexer to feed the related PES packets into the MPEG decoder: #include @@ -69,15 +71,20 @@ What do I have to do? } This will unpack the payload from all transport stream packets with - payload ID and feed it into the MPEG decoder. When pes_type is set + packet ID and feed it into the MPEG decoder. When pes_type is set to DMX_PES_VIDEO it will be handled as video data. Other types are DMX_PES_AUDIO, DMX_PES_TELETEXT, DMX_PES_SUBTITLE which will be fed into - the corresponding decoders. + the corresponding decoders (if these deocders exist in hardware or firmware). + DMX_PES_TELETEXT usually means VBI insertion by the PAL/NTSC encoder for display + on a connected TV set. If you want to avoid sending the data to one of the + decoders, use pes_type = DMX_PES_OTHER. - Open such a PES filter for each substream you want to decode. + You must open the demux device once for each PES filter you want to set. + E.g. if you want audio and video, you must have two distinct file descriptors + for the two filters. DMX_PES_PCR is used by the decoder to achieve a correct timing syncronisation - for the partial audio/video/... substreams. + between the audio/video/... substreams. Note that you have to keep the frontend and demux filedescriptor open until you are not interested in the stream anymore. Old API versions did not shut @@ -90,10 +97,17 @@ I want to record a stream to disk! How? Set up a filter for each substream you want to record as above but set the pesfilter.output field to DMX_OUT_TAP. Then you can use read() calls - to receive the PES packets. + to receive PES data. When you want to receive transport stream packets use DMX_OUT_TS_TAP and - read the stream from /dev/dvb/adapter0/dvr0. + read the stream from /dev/dvb/adapterX/dvrY. The dvr device gives you + a multiplex of all filtered PES data with DMX_OUT_TS_TAP. E.g. if you + want to record video and audio, open demuxX twice and set two PEs filters + with DMX_OUT_TS_TAP, and open dvrX once to read the TS. + + [ The current API does not allow you to specify you an input/output + routing for section filters. So you can't get multiplexed section + data from the dvr device. ] Don't forget to keep all device filedescriptors you use open. @@ -177,6 +191,9 @@ How to do table id filtering? Then submit the DMX_SET_FILTER ioctl. + The filter comprises 16 bytes covering byte 0 and byte 3..17 in a section, + thus excluding bytes 1 and 2 (the length field of a section). + ------------------------------------------------------------------------------- What are not-equal filters? -- cgit v1.2.3 From d6e1cc571bad041ab402ef377b6ae86bb7599c05 Mon Sep 17 00:00:00 2001 From: holger Date: Thu, 5 Dec 2002 09:37:23 -0200 Subject: Syntax fixes by Joerg Friedrich --- dvb-spec/dvbapi/Makefile | 2 +- dvb-spec/dvbapi/audio.tex | 42 +++++++++---------- dvb-spec/dvbapi/demux.tex | 54 ++++++++++++------------- dvb-spec/dvbapi/video.tex | 100 +++++++++++++++++++++++----------------------- 4 files changed, 99 insertions(+), 99 deletions(-) diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile index aae688f33..fe9827cff 100644 --- a/dvb-spec/dvbapi/Makefile +++ b/dvb-spec/dvbapi/Makefile @@ -4,7 +4,7 @@ TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex sec.tex frontend.tex \ intro.tex title.tex dvbstb.ps dvbapi.pdf: dvbapi.dvi - dvipdf -o $@ $< + dvipdf $< $@ dvbapi.ps: dvbapi.dvi dvips -o $@ $< diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex index 7b6427094..540248463 100644 --- a/dvb-spec/dvbapi/audio.tex +++ b/dvb-spec/dvbapi/audio.tex @@ -18,7 +18,7 @@ replaying from an internal (demuxer) or external (user write) source. typedef enum { AUDIO_SOURCE_DEMUX, AUDIO_SOURCE_MEMORY -} audio_stream_source_t; +} audio\_stream_source_t; \end{verbatim} AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed either by the frontend or the DVR device) as the source of @@ -36,7 +36,7 @@ typedef enum { AUDIO_STOPPED, AUDIO_PLAYING, AUDIO_PAUSED -} audio_play_state_t; +} audio\_play_state_t; \end{verbatim} \devsubsubsec{audioChannelSelect\_t} @@ -48,33 +48,33 @@ typedef enum { AUDIO_STEREO, AUDIO_MONO_LEFT, AUDIO_MONO_RIGHT, -} audio_channel_select_t; +} audio\_channel_select_t; \end{verbatim} -\devsubsubsec{audio_status\_t} +\devsubsubsec{audio\_status\_t} \label{audiostatus} The AUDIO\_GET\_STATUS call returns the following structure informing about various states of the playback operation. \begin{verbatim} -typedef struct audio_status { +typedef struct audio\_status { boolean AV_sync_state; boolean mute_state; - audio_play_state_t play_state; - audio_stream_source_t stream_source; - audio_channel_select_t channel_select; + audio\_play_state_t play_state; + audio\_stream_source_t stream_source; + audio\_channel_select_t channel_select; boolean bypass_mode; -} audio_status_t; +} audio\_status_t; \end{verbatim} -\devsubsubsec{audio_mixer\_t} +\devsubsubsec{audio\_mixer\_t} \label{audiomixer} The following structure is used by the AUDIO\_SET\_MIXER call to set the audio volume. \begin{verbatim} -typedef struct audio_mixer { +typedef struct audio\_mixer { unsigned int volume_left; unsigned int volume_right; -} audio_mixer_t; +} audio\_mixer_t; \end{verbatim} \devsubsubsec{audio encodings} @@ -99,20 +99,20 @@ the following bits set according to the hardwares capabilities. The ioctl AUDIO\_SET\_KARAOKE uses the following format: \begin{verbatim} typedef -struct audio_karaoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ +struct audio\_karaoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ int vocal1; /* into left and right t at 70% each */ int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets */ int melody; /* mixed into the left channel and */ /* Vocal2 into the right channel at 100% each. */ /* if Melody is non-zero, the melody channel gets mixed */ /* into left and right */ -} audio_karaoke_t; +} audio\_karaoke_t; \end{verbatim} \devsubsubsec{audio attributes} \label{aattrib} The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES: \begin{verbatim} -typedef uint16_t audio_attributes_t; +typedef uint16_t audio\_attributes_t; /* bits: descr. */ /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ /* 12 multichannel extension */ @@ -311,13 +311,13 @@ typedef uint16_t audio_attributes_t; \ifunction{AUDIO\_GET\_STATUS}{ int ioctl(int fd, int request = AUDIO\_GET\_STATUS, - struct audio_status *status);}{ + struct audio\_status *status);}{ This ioctl call asks the Audio Device to return the current state of the Audio Device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_GET\_STATUS for this command.\\ - struct audio_status *status & Returns the current state of Audio Device. + struct audio\_status *status & Returns the current state of Audio Device. }{ EBADF& fd is not a valid open file descriptor.\\ EINTERNAL & Internal error.\\ @@ -371,12 +371,12 @@ typedef uint16_t audio_attributes_t; } \ifunction{AUDIO\_SET\_MIXER}{ - int ioctl(int fd, int request = AUDIO\_SET\_MIXER, audio_mixer\_t *mix);}{ + int ioctl(int fd, int request = AUDIO\_SET\_MIXER, audio\_mixer\_t *mix);}{ This ioctl lets you adjust the mixer settings of the audio decoder. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_ID for this command.\\ - audio_mixer\_t *mix& mixer settings. + audio\_mixer\_t *mix& mixer settings. }{ EBADF& fd is not a valid open file descriptor.\\ EINTERNAL & Internal error.\\ @@ -425,12 +425,12 @@ typedef uint16_t audio_attributes_t; } \ifunction{AUDIO\_SET\_KARAOKE}{ - int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, audio_karaoke\_t *karaoke);}{ + int ioctl(fd, int request = AUDIO\_SET\_STREAMTYPE, audio\_karaoke\_t *karaoke);}{ This ioctl allows one to set the mixer settings for a karaoke DVD. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_STREAMTYPE for this command.\\ - audio_karaoke\_t *karaoke & karaoke settings according to section \ref{audiokaraoke}.\\ + audio\_karaoke\_t *karaoke & karaoke settings according to section \ref{audiokaraoke}.\\ }{ EBADF & fd is not a valid open file descriptor \\ EINVAL& karaoke is not a valid or supported karaoke setting.\\ diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex index 5a8cc1e9a..c74b133ec 100644 --- a/dvb-spec/dvbapi/demux.tex +++ b/dvb-spec/dvbapi/demux.tex @@ -19,7 +19,7 @@ typedef enum DMX_OUT_DECODER, DMX_OUT_TAP, DMX_OUT_TS_TAP -} dmx_output_t; +} dmx\_output_t; \end{verbatim} /* Output multiplexed into a new TS */ /* (to be retrieved by reading from the */ @@ -34,7 +34,7 @@ typedef enum { DMX_IN_FRONTEND, /* Input from a front-end device. */ DMX_IN_DVR /* Input from the logical DVR device. */ -} dmx_input_t; +} dmx\_input_t; \end{verbatim} @@ -50,11 +50,11 @@ typedef enum DMX_PES_SUBTITLE, DMX_PES_PCR, DMX_PES_OTHER -} dmx_pes_type_t; +} dmx\_pes\_type_t; \end{verbatim} -\devsubsubsec{dmx_event\_t} +\devsubsubsec{dmx\_event\_t} \label{dmxeventt} \begin{verbatim} @@ -62,7 +62,7 @@ typedef enum { DMX_SCRAMBLING_EV, DMX_FRONTEND_EV -} dmx_event_t; +} dmx\_event_t; \end{verbatim} @@ -74,30 +74,30 @@ typedef enum { DMX_SCRAMBLING_OFF, DMX_SCRAMBLING_ON -} dmx_scrambling_status_t; +} dmx\_scrambling_status_t; \end{verbatim} -\devsubsubsec{dmx_filter\_t} +\devsubsubsec{dmx\_filter\_t} \label{dmxfilter} \begin{verbatim} -typedef struct dmx_filter +typedef struct dmx\_filter { uint8_t filter[DMX_FILTER_SIZE]; uint8_t mask[DMX_FILTER_SIZE]; -} dmx_filter_t; +} dmx\_filter\_t; \end{verbatim} -\devsubsubsec{dmx_sct_filter_params} +\devsubsubsec{dmx\_sct\_filter\_params} \label{dmxsctfilterparams} \begin{verbatim} -struct dmx_sct_filter_params +struct dmx\_sct\_filter\_params { uint16_t pid; - dmx_filter_t filter; + dmx\_filter\_t filter; uint32_t timeout; uint32_t flags; #define DMX_CHECK_CRC 1 @@ -107,32 +107,32 @@ struct dmx_sct_filter_params \end{verbatim} -\devsubsubsec{dmx_pes_filter_params} +\devsubsubsec{dmx\_pes\_filter\_params} \label{dmxpesfilterparams} \begin{verbatim} -struct dmx_pes_filter_params +struct dmx\_pes\_filter\_params { uint16_t pid; - dmx_input_t input; - dmx_output_t output; - dmx_pes_type_t pes_type; + dmx\_input_t input; + dmx\_output_t output; + dmx\_pes\_type_t pes\_type; uint32_t flags; }; \end{verbatim} -\devsubsubsec{dmx_event} +\devsubsubsec{dmx\_event} \label{dmxevent} \begin{verbatim} -struct dmx_event +struct dmx\_event { - dmx_event_t event; + dmx\_event_t event; time_t timeStamp; union { - dmx_scrambling_status_t scrambling; + dmx\_scrambling_status_t scrambling; } u; }; \end{verbatim} @@ -295,7 +295,7 @@ struct dmx_event } \ifunction{DMX\_SET\_FILTER}{ - int ioctl( int fd, int request = DMX\_SET\_FILTER, struct dmx_sct_filter_params *params); + int ioctl( int fd, int request = DMX\_SET\_FILTER, struct dmx\_sct\_filter\_params *params); }{ This ioctl call sets up a filter according to the filter and mask parameters provided. A timeout may be defined stating number of seconds @@ -310,7 +310,7 @@ struct dmx_event }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals DMX\_SET\_FILTER for this command.\\ - struct dmx_sct_filter_params *params + struct dmx\_sct\_filter\_params *params & Pointer to structure containing filter parameters.\\ }{ EBADF & fd is not a valid file descriptor.\\ @@ -319,7 +319,7 @@ struct dmx_event \ifunction{DMX\_SET\_PES\_FILTER}{ int ioctl( int fd, int request = DMX\_SET\_PES\_FILTER, - struct dmx_pes_filter_params *params); + struct dmx\_pes\_filter\_params *params); }{ 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 @@ -335,7 +335,7 @@ struct dmx_event }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals DMX\_SET\_PES\_FILTER for this command.\\ - struct dmx_pes_filter_params *params + struct dmx\_pes\_filter\_params *params & Pointer to structure containing filter parameters.\\ }{ EBADF & fd is not a valid file descriptor.\\ @@ -364,7 +364,7 @@ struct dmx_event } \ifunction{DMX\_GET\_EVENT}{ - int ioctl( int fd, int request = DMX\_GET\_EVENT, struct dmx_event *ev); + int ioctl( int fd, int request = DMX\_GET\_EVENT, struct dmx\_event *ev); }{ 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 @@ -379,7 +379,7 @@ struct dmx_event }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals DMX\_GET\_EVENT for this command.\\ - struct dmx_event *ev & Pointer to the location where the event is to be stored.\\ + struct dmx\_event *ev & Pointer to the location where the event is to be stored.\\ }{ EBADF & fd is not a valid file descriptor.\\ EFAULT & ev points to an invalid address.\\ diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex index d33f03c83..7300c95c0 100644 --- a/dvb-spec/dvbapi/video.tex +++ b/dvb-spec/dvbapi/video.tex @@ -9,21 +9,21 @@ device as well as the video4linux device. \devsubsec{Video Data Types} -\devsubsubsec{video_format\_t} +\devsubsubsec{video\_format\_t} \label{videoformat} -The \texttt{video_format\_t} data type defined by +The \texttt{video\_format\_t} data type defined by \begin{verbatim} typedef enum { VIDEO_FORMAT_4_3, VIDEO_FORMAT_16_9 -} video_format_t; +} video\_format_t; \end{verbatim} is used in the VIDEO\_SET\_FORMAT function (\ref{videosetformat}) to tell the driver which aspect ratio the output hardware (e.g. TV) has. -It is also used in the data structures video_status (\ref{videostatus}) +It is also used in the data structures video\_status (\ref{videostatus}) returned by VIDEO\_GET\_STATUS (\ref{videogetstatus}) and -video_event (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) +video\_event (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) which report about the display format of the current video stream. \devsubsubsec{videoDisplayFormat\_t} @@ -39,7 +39,7 @@ typedef enum { VIDEO_PAN_SCAN, VIDEO_LETTER_BOX, VIDEO_CENTER_CUT_OUT -} video_displayformat_t; +} video\_displayformat_t; \end{verbatim} as argument. @@ -53,7 +53,7 @@ replaying from an internal (demuxer) or external (user write) source. typedef enum { VIDEO_SOURCE_DEMUX, VIDEO_SOURCE_MEMORY -} video_stream_source_t; +} video\_stream\_source_t; \end{verbatim} VIDEO\_SOURCE\_DEMUX selects the demultiplexer (fed either by the frontend or the DVR device) as the source of @@ -71,7 +71,7 @@ typedef enum { VIDEO_STOPPED, VIDEO_PLAYING, VIDEO_FREEZED -} video_play_state_t; +} video\_play\_state_t; \end{verbatim} @@ -80,11 +80,11 @@ typedef enum { The following is the structure of a video event as it is returned by the VIDEO\_GET\_EVENT call. \begin{verbatim} -struct video_event { +struct video\_event { int32_t type; time_t timestamp; union { - video_format_t video_format; + video\_format_t video\_format; } u; }; \end{verbatim} @@ -94,22 +94,22 @@ struct video_event { The VIDEO\_GET\_STATUS call returns the following structure informing about various states of the playback operation. \begin{verbatim} -struct video_status { - boolean video_blank; - video_play_state_t play_state; - video_stream_source_t stream_source; - video_format_t video_format; - video_displayformat_t display_format; +struct video\_status { + boolean video\_blank; + video\_play\_state_t play\_state; + video\_stream\_source_t stream\_source; + video\_format_t video\_format; + video\_displayformat_t display\_format; }; \end{verbatim} -If video_blank is set video will be blanked out if the channel is changed or +If video\_blank is set video will be blanked out if the channel is changed or if playback is stopped. Otherwise, the last picture will be displayed. -play_state indicates if the video is currently frozen, stopped, or -being played back. The stream_source corresponds to the seleted source +play\_state indicates if the video is currently frozen, stopped, or +being played back. The stream\_source corresponds to the seleted source for the video stream. It can come either from the demultiplexer or from memory. -The video_format indicates the aspect ratio (one of 4:3 or 16:9) +The video\_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently played video stream. -Finally, display_format corresponds to the selected cropping mode in case the +Finally, display\_format corresponds to the selected cropping mode in case the source video format is not the same as the format of the output device. @@ -119,7 +119,7 @@ An I-frame displayed via the VIDEO\_STILLPICTURE call is passed on within the following structure. \begin{verbatim} /* pointer to and size of a single iframe in memory */ -struct video_still_picture { +struct video\_still\_picture { char *iFrame; int32_t size; }; @@ -162,7 +162,7 @@ typedef enum { VIDEO_SYSTEM_NTSC60, VIDEO_SYSTEM_PAL60, VIDEO_SYSTEM_PALM60 -} video_system_t; +} video\_system_t; \end{verbatim} @@ -174,7 +174,7 @@ information. The call expects the following format for that information: \begin{verbatim} typedef -struct video_highlight { +struct video\_highlight { boolean active; /* 1=show highlight, 0=hide highlight */ uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ /* 3- 0 Background pixel contrast */ @@ -190,7 +190,7 @@ struct video_highlight { uint32_t xpos; /* 23-22 button color number */ /* 21-12 start x */ /* 9- 0 end x */ -} video_highlight_t; +} video\_highlight_t; \end{verbatim} @@ -200,10 +200,10 @@ Calling VIDEO\_SET\_SPU deactivates or activates SPU decoding, according to the following format: \begin{verbatim} typedef -struct video_spu { +struct video\_spu { boolean active; - int stream_id; -} video_spu_t; + int stream\_id; +} video\_spu\_t; \end{verbatim} @@ -212,10 +212,10 @@ struct video_spu { The following structure is used to set the SPU palette by calling VIDEO\_SPU\_PALETTE: \begin{verbatim} typedef -struct video_spu_palette{ /* SPU Palette information */ +struct video\_spu\_palette{ /* SPU Palette information */ int length; uint8_t *palette; -} video_spu_palette_t; +} video\_spu\_palette_t; \end{verbatim} \devsubsubsec{video NAVI pack} @@ -224,10 +224,10 @@ In order to get the navigational data the following structure has to be passed to the ioctl VIDEO\_GET\_NAVI: \begin{verbatim} typedef -struct video_navi_pack{ +struct video\_navi\_pack{ int length; /* 0 ... 1024 */ uint8_t data[1024]; -} video_navi_pack_t; +} video\_navi\_pack_t; \end{verbatim} @@ -235,7 +235,7 @@ struct video_navi_pack{ \label{vattrib} The following attributes can be set by a call to VIDEO\_SET\_ATTRIBUTES: \begin{verbatim} -typedef uint16_t video_attributes_t; +typedef uint16_t video\_attributes_t; /* bits: descr. */ /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ /* 13-12 TV system (0=525/60, 1=625/50) */ @@ -406,12 +406,12 @@ EINVAL & Illegal input parameter\\ \ifunction{VIDEO\_GET\_STATUS}{ \label{videogetstatus} - int ioctl(fd, int request = VIDEO\_GET\_STATUS, struct video_status *status);}{ + int ioctl(fd, int request = VIDEO\_GET\_STATUS, struct video\_status *status);}{ This ioctl call asks the Video Device to return the current status of the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request& Equals VIDEO\_GET\_STATUS for this command.\\ - struct video_status *status & Returns the current status of the Video Device.\\ + struct video\_status *status & Returns the current status of the Video Device.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ @@ -420,8 +420,8 @@ EFAULT & status points to invalid address\\ \ifunction{VIDEO\_GET\_EVENT}{ \label{videogetevent} - int ioctl(fd, int request = VIDEO\_GET\_EVENT, struct video_event *ev);}{ - This ioctl call returns an event of type video_event if available. + int ioctl(fd, int request = VIDEO\_GET\_EVENT, struct video\_event *ev);}{ + This ioctl call returns an event of type video\_event if available. If an event is not available, the behavior depends on whether the device is in blocking or non-blocking mode. In the latter case, the call fails immediately with errno set to EWOULDBLOCK. In the former case, the call blocks until an @@ -434,7 +434,7 @@ EFAULT & status points to invalid address\\ }{ int fd & File descriptor returned by a previous call to open().\\ int request& Equals VIDEO\_GET\_EVENT for this command.\\ - struct video_event *ev & Points to the location where the event, if any, is + struct video\_event *ev & Points to the location where the event, if any, is to be stored.\\ }{ EBADF & fd is not a valid open file descriptor \\ @@ -460,14 +460,14 @@ EOVERFLOW & \\ } \ifunction{VIDEO\_STILLPICTURE}{ - int ioctl(fd, int request = VIDEO\_STILLPICTURE, struct video_still_picture *sp);}{ + int ioctl(fd, int request = VIDEO\_STILLPICTURE, struct video\_still\_picture *sp);}{ 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. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_STILLPICTURE for this command.\\ - struct video_still_picture *sp& + struct video\_still\_picture *sp& Pointer to a location where an I-frame and size is stored.\\ }{ EBADF& fd is not a valid open file descriptor \\ @@ -562,7 +562,7 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_FORMAT}{ \label{videosetformat} - int ioctl(fd, int request = VIDEO\_SET\_FORMAT, video_format\_t format); + int ioctl(fd, int request = VIDEO\_SET\_FORMAT, video\_format\_t format); }{ This ioctl sets the screen format (aspect ratio) of the connected output device (TV) so that the output of the decoder can @@ -570,7 +570,7 @@ EOVERFLOW & \\ }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_FORMAT for this command.\\ - video_format\_t format& video format of TV as defined in section \ref{videoformat}.\\ + video\_format\_t format& video format of TV as defined in section \ref{videoformat}.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& format is not a valid video format.\\ @@ -595,14 +595,14 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_HIGHLIGHT}{ \label{videosethighlight} - int ioctl(fd, int request = VIDEO\_SET\_HIGHLIGHT ,video_highlight\_t *vhilite) + int ioctl(fd, int request = VIDEO\_SET\_HIGHLIGHT ,video\_highlight\_t *vhilite) }{ This ioctl sets the SPU highlight information for the menu access of a DVD. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_HIGHLIGHT for this command.\\ - video_highlight\_t *vhilite& SPU Highlight information according to + video\_highlight\_t *vhilite& SPU Highlight information according to section \ref{vhilite}.\\ }{ EBADF& fd is not a valid open file descriptor. \\ @@ -612,7 +612,7 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_SPU}{ \label{videosetspu} - int ioctl(fd, int request = VIDEO\_SET\_SPU , video_spu\_t *spu) + int ioctl(fd, int request = VIDEO\_SET\_SPU , video\_spu\_t *spu) }{ This ioctl activates or deactivates SPU decoding in a DVD input stream. It can only be used, if the driver is able to handle a DVD @@ -620,7 +620,7 @@ EOVERFLOW & \\ }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_SPU for this command.\\ - video_spu\_t *spu& SPU decoding (de)activation and subid setting + video\_spu\_t *spu& SPU decoding (de)activation and subid setting according to section \ref{videospu}.\\ }{ EBADF& fd is not a valid open file descriptor \\ @@ -630,13 +630,13 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_SPU\_PALETTE}{ \label{videosetspupalette} - int ioctl(fd, int request = VIDEO\_SET\_SPU\_PALETTE ,video_spu_palette\_t *palette ) + int ioctl(fd, int request = VIDEO\_SET\_SPU\_PALETTE ,video\_spu\_palette\_t *palette ) }{ This ioctl sets the SPU color palette. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_SPU\_PALETTE for this command.\\ - video_spu_palette\_t *palette& SPU palette according to section \ref{vspupal}.\\ + video\_spu\_palette\_t *palette& SPU palette according to section \ref{vspupal}.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& input is not a valid palette or driver doesn't handle SPU.\\ @@ -646,14 +646,14 @@ EOVERFLOW & \\ \ifunction{VIDEO\_GET\_NAVI}{ \label{videosetnavi} - int ioctl(fd, int request = VIDEO\_GET\_NAVI , video_navi_pack\_t *navipack) + int ioctl(fd, int request = VIDEO\_GET\_NAVI , video\_navi\_pack\_t *navipack) }{ This ioctl returns navigational information from the DVD stream. This is especially needed if an encoded stream has to be decoded by the hardware. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_GET\_NAVI for this command.\\ - video_navi_pack\_t *navipack& PCI or DSI pack (private stream 2) + video\_navi\_pack\_t *navipack& PCI or DSI pack (private stream 2) according to section \ref{videonavi}.\\ }{ EBADF& fd is not a valid open file descriptor \\ -- cgit v1.2.3 From 76715ed624559f5d635cc50f74df12a8ac2ad977 Mon Sep 17 00:00:00 2001 From: js Date: Wed, 5 Feb 2003 16:32:21 -0200 Subject: fix syntax error in example program --- dvb-spec/dvbapi/examples.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex index fa5c24b48..126268c5d 100644 --- a/dvb-spec/dvbapi/examples.tex +++ b/dvb-spec/dvbapi/examples.tex @@ -70,7 +70,7 @@ int set_qpsk_channel(int freq, int vpid, int apid, int tpid, FrontendParameters frp; struct pollfd pfd[1]; FrontendEvent event; - int demux1, dmeux2, demux3, front, + int demux1, demux2, demux3, front; frequency = (uint32_t) freq; symbolrate = (uint32_t) srate; -- cgit v1.2.3 From 622f6e3335a0dd1a97cdaee9913c1f105f3e36fa Mon Sep 17 00:00:00 2001 From: js Date: Mon, 10 Feb 2003 10:18:16 -0200 Subject: - merged GNU FDL lincense from NEWSTRUCT branch - updated from DVB_API_VERSION 3 - various minor fixes/additions - bumped version number to 1.0.0-pre1 to match wth upcoming linuxtv-dvb driver release --- dvb-spec/dvbapi/LICENSE | 355 ++++++++++++++++++++++ dvb-spec/dvbapi/Makefile | 8 +- dvb-spec/dvbapi/audio.tex | 80 ++--- dvb-spec/dvbapi/ca.tex | 4 +- dvb-spec/dvbapi/demux.tex | 101 +++---- dvb-spec/dvbapi/devices.tex | 6 +- dvb-spec/dvbapi/dvbapi.tex | 8 +- dvb-spec/dvbapi/examples.tex | 26 +- dvb-spec/dvbapi/fdl.tex | 367 +++++++++++++++++++++++ dvb-spec/dvbapi/frontend.tex | 689 +++++++++++++++++++++++-------------------- dvb-spec/dvbapi/intro.tex | 117 +++----- dvb-spec/dvbapi/kdapi.tex | 9 +- dvb-spec/dvbapi/net.tex | 19 ++ dvb-spec/dvbapi/sec.tex | 282 ------------------ dvb-spec/dvbapi/title.tex | 24 +- dvb-spec/dvbapi/video.tex | 101 ++++--- 16 files changed, 1350 insertions(+), 846 deletions(-) create mode 100644 dvb-spec/dvbapi/LICENSE create mode 100644 dvb-spec/dvbapi/fdl.tex create mode 100644 dvb-spec/dvbapi/net.tex delete mode 100644 dvb-spec/dvbapi/sec.tex diff --git a/dvb-spec/dvbapi/LICENSE b/dvb-spec/dvbapi/LICENSE new file mode 100644 index 000000000..b42936beb --- /dev/null +++ b/dvb-spec/dvbapi/LICENSE @@ -0,0 +1,355 @@ + GNU Free Documentation License + Version 1.1, March 2000 + + Copyright (C) 2000 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + +0. PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + + +1. APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The "Document", below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as "you". + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A "Secondary Section" is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The "Invariant Sections" are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The "Cover Texts" are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, "Title Page" means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +2. VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +3. COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +4. MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. +D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +H. Include an unaltered copy of this License. +I. Preserve the section entitled "History", and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled "History" in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the "History" section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +M. Delete any section entitled "Endorsements". Such a section + may not be included in the Modified Version. +N. Do not retitle any existing section as "Endorsements" + or to conflict in title with any Invariant Section. + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +5. COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" +in the various original documents, forming one section entitled +"History"; likewise combine any sections entitled "Acknowledgements", +and any sections entitled "Dedications". You must delete all sections +entitled "Endorsements." + + +6. COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +7. AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an "aggregate", and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +8. TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +9. TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +10. FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + + +ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". + +If you have no Invariant Sections, write "with no Invariant Sections" +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write "no Front-Cover Texts" instead of +"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile index fe9827cff..83a5e5f7a 100644 --- a/dvb-spec/dvbapi/Makefile +++ b/dvb-spec/dvbapi/Makefile @@ -1,13 +1,13 @@ all: dvbapi.ps dvbapi.pdf -TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex sec.tex frontend.tex \ - intro.tex title.tex dvbstb.ps +TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex net.tex frontend.tex \ + demux.tex kdapi.tex examples.tex intro.tex title.tex dvbstb.ps dvbapi.pdf: dvbapi.dvi - dvipdf $< $@ + dvipdf $< dvbapi.ps: dvbapi.dvi - dvips -o $@ $< + dvips $< dvbapi.dvi: dvbapi.bbl $(TEXS) -latex dvbapi diff --git a/dvb-spec/dvbapi/audio.tex b/dvb-spec/dvbapi/audio.tex index 540248463..05c23e56f 100644 --- a/dvb-spec/dvbapi/audio.tex +++ b/dvb-spec/dvbapi/audio.tex @@ -1,7 +1,13 @@ \devsec{DVB Audio Device} The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. -It can be accessed through \texttt{/dev/ost/audio}. +It can be accessed through \texttt{/dev/dvb/adapter0/audio0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/video.h} in your application. + +Please note that some DVB cards don't have their own +MPEG decoder, which results in the omission of the audio and video +device. \devsubsec{Audio Data Types} @@ -9,16 +15,16 @@ It can be accessed through \texttt{/dev/ost/audio}. This section describes the structures, data types and defines used when talking to the audio device. -\devsubsubsec{audioStreamSource\_t} +\devsubsubsec{audio\_stream\_source\_t} \label{audiostreamsource} The audio stream source is set through the AUDIO\_SELECT\_SOURCE call and can take the following values, depending on whether we are -replaying from an internal (demuxer) or external (user write) source. +replaying from an internal (demux) or external (user write) source. \begin{verbatim} typedef enum { AUDIO_SOURCE_DEMUX, AUDIO_SOURCE_MEMORY -} audio\_stream_source_t; +} audio_stream_source_t; \end{verbatim} AUDIO\_SOURCE\_DEMUX selects the demultiplexer (fed either by the frontend or the DVR device) as the source of @@ -27,7 +33,7 @@ If AUDIO\_SOURCE\_MEMORY is selected the stream comes from the application through the \texttt{write()} system call. -\devsubsubsec{audioPlayState\_t} +\devsubsubsec{audio\_play\_state\_t} The following values can be returned by the AUDIO\_GET\_STATUS call representing the state of audio playback. \label{audioplaystate} @@ -36,45 +42,45 @@ typedef enum { AUDIO_STOPPED, AUDIO_PLAYING, AUDIO_PAUSED -} audio\_play_state_t; +} audio_play_state_t; \end{verbatim} -\devsubsubsec{audioChannelSelect\_t} +\devsubsubsec{audio\_channel\_select\_t} \label{audiochannelselect} The audio channel selected via AUDIO\_CHANNEL\_SELECT is determined by -the following values. +the following values. \begin{verbatim} typedef enum { AUDIO_STEREO, AUDIO_MONO_LEFT, AUDIO_MONO_RIGHT, -} audio\_channel_select_t; +} audio_channel_select_t; \end{verbatim} -\devsubsubsec{audio\_status\_t} +\devsubsubsec{struct audio\_status} \label{audiostatus} The AUDIO\_GET\_STATUS call returns the following structure informing about various states of the playback operation. \begin{verbatim} -typedef struct audio\_status { +typedef struct audio_status { boolean AV_sync_state; boolean mute_state; - audio\_play_state_t play_state; - audio\_stream_source_t stream_source; - audio\_channel_select_t channel_select; + audio_play_state_t play_state; + audio_stream_source_t stream_source; + audio_channel_select_t channel_select; boolean bypass_mode; -} audio\_status_t; +} audio_status_t; \end{verbatim} -\devsubsubsec{audio\_mixer\_t} +\devsubsubsec{struct audio\_mixer} \label{audiomixer} The following structure is used by the AUDIO\_SET\_MIXER call to set the audio volume. \begin{verbatim} -typedef struct audio\_mixer { +typedef struct audio_mixer { unsigned int volume_left; unsigned int volume_right; -} audio\_mixer_t; +} audio_mixer_t; \end{verbatim} \devsubsubsec{audio encodings} @@ -94,25 +100,31 @@ the following bits set according to the hardwares capabilities. \end{verbatim} -\devsubsubsec{audio karaoke} +\devsubsubsec{struct audio\_karaoke} \label{audiokaraoke} The ioctl AUDIO\_SET\_KARAOKE uses the following format: \begin{verbatim} typedef -struct audio\_karaoke{ /* if Vocal1 or Vocal2 are non-zero, they get mixed */ - int vocal1; /* into left and right t at 70% each */ - int vocal2; /* if both, Vocal1 and Vocal2 are non-zero, Vocal1 gets */ - int melody; /* mixed into the left channel and */ - /* Vocal2 into the right channel at 100% each. */ - /* if Melody is non-zero, the melody channel gets mixed */ /* into left and right */ -} audio\_karaoke_t; +struct audio_karaoke{ + int vocal1; + int vocal2; + int melody; +} audio_karaoke_t; \end{verbatim} +If Vocal1 or Vocal2 are non-zero, they get mixed +into left and right t at 70\% each. +If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets +mixed into the left channel and +Vocal2 into the right channel at 100\% each. +Ff Melody is non-zero, the melody channel gets mixed +into left and right. + \devsubsubsec{audio attributes} \label{aattrib} The following attributes can be set by a call to AUDIO\_SET\_ATTRIBUTES: \begin{verbatim} -typedef uint16_t audio\_attributes_t; +typedef uint16_t audio_attributes_t; /* bits: descr. */ /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ /* 12 multichannel extension */ @@ -130,7 +142,7 @@ typedef uint16_t audio\_attributes_t; \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named audio device (e.g. /dev/ost/audio) for subsequent + This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0) for subsequent use. When an open() call has succeeded, the device will be ready for use. The significance of blocking or non-blocking mode is described in the documentation for functions where there is a difference. It does not affect @@ -225,7 +237,7 @@ typedef uint16_t audio\_attributes_t; \ifunction{AUDIO\_SELECT\_SOURCE}{ int ioctl(int fd, int request = AUDIO\_SELECT\_SOURCE, - audioStreamSource\_t source);}{ + audio\_stream\_source\_t source);}{ 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 @@ -233,7 +245,7 @@ typedef uint16_t audio\_attributes_t; }{ 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\_source\_t source& Indicates the source that shall be used for the Audio stream. }{ EBADF& fd is not a valid open file descriptor.\\ @@ -295,13 +307,13 @@ typedef uint16_t audio\_attributes_t; \ifunction{AUDIO\_CHANNEL\_SELECT}{ int ioctl(int fd, int request = AUDIO\_CHANNEL\_SELECT, - audioChannelSelect\_t);}{ + audio\_channel\_select\_t);}{ This ioctl call asks the Audio Device to select the requested channel if possible. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_CHANNEL\_SELECT for this command.\\ - audioChannelSelect\_t ch & + audio\_channel\_select\_t ch & Select the output format of the audio (mono left/right, stereo). }{ EBADF& fd is not a valid open file descriptor.\\ @@ -412,13 +424,13 @@ typedef uint16_t audio\_attributes_t; } \ifunction{AUDIO\_SET\_ATTRIBUTES}{ - int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audioAttributes\_t attr );}{ + int ioctl(fd, int request = AUDIO\_SET\_ATTRIBUTES, audio\_attributes\_t attr );}{ This ioctl is intended for DVD playback and allows you to set certain information about the audio stream. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals AUDIO\_SET\_ATTRIBUTES for this command.\\ - iaudioAttributes\_t attr & audio attributes according to section \ref{aattrib}\\ + audio\_attributes\_t attr & audio attributes according to section \ref{aattrib}\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& attr is not a valid or supported attribute setting.\\ diff --git a/dvb-spec/dvbapi/ca.tex b/dvb-spec/dvbapi/ca.tex index eba512b1b..fe76da454 100644 --- a/dvb-spec/dvbapi/ca.tex +++ b/dvb-spec/dvbapi/ca.tex @@ -1,7 +1,9 @@ \devsec{DVB CA Device} The DVB CA device controls the conditional access hardware. -It can be accessed through \texttt{/dev/ost/ca}. +It can be accessed through \texttt{/dev/dvb/adapter0/ca0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/ca.h} in your application. \devsubsec{CA Data Types} diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex index c74b133ec..dd032f58d 100644 --- a/dvb-spec/dvbapi/demux.tex +++ b/dvb-spec/dvbapi/demux.tex @@ -1,16 +1,14 @@ \devsec{DVB Demux Device} The DVB demux device controls the filters of the DVB hardware/software. -It can be accessed through \texttt{/dev/ost/demux}. +It can be accessed through \texttt{/dev/adapter0/demux0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/dmx.h} in your application. \devsubsec{Demux Data Types} -\begin{verbatim} -typedef uint16_t uint16_t; -\end{verbatim} - -\devsubsubsec{dmxOutput\_t} +\devsubsubsec{dmx\_output\_t} \label{dmxoutput} \begin{verbatim} @@ -19,26 +17,30 @@ typedef enum DMX_OUT_DECODER, DMX_OUT_TAP, DMX_OUT_TS_TAP -} dmx\_output_t; +} dmx_output_t; \end{verbatim} -/* Output multiplexed into a new TS */ -/* (to be retrieved by reading from the */ -/* logical DVR device). */ + +\noindent\texttt{DMX\_OUT\_TAP} delivers the stream output to the demux device +on which the ioctl is called. + +\noindent\texttt{DMX\_OUT\_TS\_TAP} routes output to the logical DVR device +\texttt{/dev/dvb/adapter0/dvr0}, which delivers a TS multiplexed from +all filters for which \texttt{DMX\_OUT\_TS\_TAP} was specified. -\devsubsubsec{dmxInput\_t} +\devsubsubsec{dmx\_input\_t} \label{dmxinput} \begin{verbatim} typedef enum { - DMX_IN_FRONTEND, /* Input from a front-end device. */ - DMX_IN_DVR /* Input from the logical DVR device. */ -} dmx\_input_t; + DMX_IN_FRONTEND, + DMX_IN_DVR +} dmx_input_t; \end{verbatim} -\devsubsubsec{dmxPesType\_t} +\devsubsubsec{dmx\_pes\_type\_t} \label{dmxpestype} \begin{verbatim} @@ -50,7 +52,7 @@ typedef enum DMX_PES_SUBTITLE, DMX_PES_PCR, DMX_PES_OTHER -} dmx\_pes\_type_t; +} dmx_pes_type_t; \end{verbatim} @@ -62,11 +64,11 @@ typedef enum { DMX_SCRAMBLING_EV, DMX_FRONTEND_EV -} dmx\_event_t; +} dmx_event_t; \end{verbatim} -\devsubsubsec{dmxScramblingStatus\_t} +\devsubsubsec{dmx\_scrambling\_status\_t} \label{dmxscramblingstatus} \begin{verbatim} @@ -74,32 +76,32 @@ typedef enum { DMX_SCRAMBLING_OFF, DMX_SCRAMBLING_ON -} dmx\_scrambling_status_t; +} dmx_scrambling_status_t; \end{verbatim} -\devsubsubsec{dmx\_filter\_t} +\devsubsubsec{struct dmx\_filter} \label{dmxfilter} \begin{verbatim} -typedef struct dmx\_filter +typedef struct dmx_filter { uint8_t filter[DMX_FILTER_SIZE]; uint8_t mask[DMX_FILTER_SIZE]; -} dmx\_filter\_t; +} dmx_filter_t; \end{verbatim} -\devsubsubsec{dmx\_sct\_filter\_params} +\devsubsubsec{struct dmx\_sct\_filter\_params} \label{dmxsctfilterparams} \begin{verbatim} -struct dmx\_sct\_filter\_params +struct dmx_sct_filter_params { - uint16_t pid; - dmx\_filter\_t filter; - uint32_t timeout; - uint32_t flags; + uint16_t pid; + dmx_filter_t filter; + uint32_t timeout; + uint32_t flags; #define DMX_CHECK_CRC 1 #define DMX_ONESHOT 2 #define DMX_IMMEDIATE_START 4 @@ -107,32 +109,32 @@ struct dmx\_sct\_filter\_params \end{verbatim} -\devsubsubsec{dmx\_pes\_filter\_params} +\devsubsubsec{struct dmx\_pes\_filter\_params} \label{dmxpesfilterparams} \begin{verbatim} -struct dmx\_pes\_filter\_params +struct dmx_pes_filter_params { - uint16_t pid; - dmx\_input_t input; - dmx\_output_t output; - dmx\_pes\_type_t pes\_type; - uint32_t flags; + uint16_t pid; + dmx_input_t input; + dmx_output_t output; + dmx_pes_type_t pes_type; + uint32_t flags; }; \end{verbatim} -\devsubsubsec{dmx\_event} +\devsubsubsec{struct dmx\_event} \label{dmxevent} \begin{verbatim} -struct dmx\_event +struct dmx_event { - dmx\_event_t event; - time_t timeStamp; + dmx_event_t event; + time_t timeStamp; union { - dmx\_scrambling_status_t scrambling; + dmx_scrambling_status_t scrambling; } u; }; \end{verbatim} @@ -142,16 +144,15 @@ struct dmx\_event \devsubsec{Demux Function Calls} \function{open()}{ int open(const char *deviceName, int flags);}{ - 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 + This system call, used with a device name of /dev/dvb/adapter0/demux0, + allocates a new filter and returns a handle which can be used for subsequent control of that filter. This call has to be made for each filter to be used, i.e. every returned file descriptor is a reference to a single filter. - /dev/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 functionality. When reading from + /dev/dvb/adapter0/dvr0 is a logical device to be used for retrieving Transport + Streams for digital video recording. When reading from this device a transport stream containing the packets from all PES - filters set in the corresponding demux device (/dev/ost/demuxn) + filters set in the corresponding demux device (/dev/dvb/adapter0/demux0) having the output set to DMX\_OUT\_TS\_TAP. A recorded Transport Stream is replayed by writing to this device. % This device can only be opened in read-write mode. @@ -211,7 +212,7 @@ struct dmx\_event 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 + in the corresponding demux device /dev/dvb/adapter0/demux0 having the output set to DMX\_OUT\_TS\_TAP. }{ int fd & File descriptor returned by a previous call to open().\\ @@ -236,11 +237,11 @@ struct dmx\_event \function{write()}{ ssize\_t write(int fd, const void *buf, size\_t count); }{ - This system call is only provided by the logical device /dev/ost/dvrn, - where n identifies the physical demux device that provides the actual + This system call is only provided by the logical device /dev/dvb/adapter0/dvr0, + associated with the physical demux device that provides the actual DVR functionality. It is used for replay of a digitally recorded Transport Stream. Matching filters have to be defined in the - corresponding physical demux device, /dev/ost/demuxn. + corresponding physical demux device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is implied by count. }{ int fd & File descriptor returned by a previous call to open().\\ diff --git a/dvb-spec/dvbapi/devices.tex b/dvb-spec/dvbapi/devices.tex index 9c561e853..11eccd897 100644 --- a/dvb-spec/dvbapi/devices.tex +++ b/dvb-spec/dvbapi/devices.tex @@ -1,9 +1,9 @@ -\input{video.tex} -\input{audio.tex} \input{frontend.tex} -\input{sec.tex} \input{demux.tex} +\input{video.tex} +\input{audio.tex} \input{ca.tex} +\input{net.tex} \input{kdapi.tex} %%% Local Variables: diff --git a/dvb-spec/dvbapi/dvbapi.tex b/dvb-spec/dvbapi/dvbapi.tex index ad0251c01..d75c2417f 100644 --- a/dvb-spec/dvbapi/dvbapi.tex +++ b/dvb-spec/dvbapi/dvbapi.tex @@ -1,4 +1,4 @@ -\documentclass[10pt]{book} +\documentclass[a4paper,10pt]{book} \usepackage[dvips,colorlinks=true]{hyperref} \usepackage{times} @@ -131,7 +131,7 @@ \renewcommand{\sectionmark}[1]{\markright{\thesection.\ #1}{}} \lhead[\fancyplain{}{\bfseries \thepage}]{\bfseries \rightmark} \rhead[\fancyplain{}{\bfseries \leftmark}]{\bfseries \thepage} -\cfoot{\copyright 2002 convergence GmbH} +%\cfoot{\copyright\ 2002, 2003 Convergence GmbH} \input{intro.tex} @@ -145,6 +145,10 @@ \cleardoublepage +\input{fdl.tex} + +\cleardoublepage + \thispagestyle{plain}\chaptermark{Bibliography} \addcontentsline{toc}{chapter}{Bibliography} \bibliographystyle{bibsec} diff --git a/dvb-spec/dvbapi/examples.tex b/dvb-spec/dvbapi/examples.tex index 126268c5d..c9a19ba29 100644 --- a/dvb-spec/dvbapi/examples.tex +++ b/dvb-spec/dvbapi/examples.tex @@ -1,6 +1,10 @@ \chapter{Examples} In this section we would like to present some examples for using the DVB API. +Maintainer note: This section is out of date. Please refer to the sample +programs packaged with the driver distribution from +\texttt{http://linuxtv.org/}. + \section{Tuning} We will start with a generic tuning subroutine that uses the frontend and SEC, as well as the demux devices. The example is given for QPSK @@ -17,14 +21,14 @@ tuners, but can easily be adjusted for QAM. #include #include -#include -#include -#include +#include +#include +#include #include -#define DMX "/dev/ost/demux" -#define FRONT "/dev/ost/frontend" -#define SEC "/dev/ost/sec" +#define DMX "/dev/dvb/adapter0/demux1" +#define FRONT "/dev/dvb/adapter0/frontend1" +#define SEC "/dev/dvb/adapter0/sec1" /* routine for checking if we have a signal and other status information*/ int FEReadStatus(int fd, fe_status_t *stat) @@ -234,12 +238,12 @@ recording. #include #include -#include -#include +#include +#include #include -#define DVR "/dev/ost/dvr" -#define AUDIO "/dev/ost/audio" -#define VIDEO "/dev/ost/video" +#define DVR "/dev/dvb/adapter0/dvr1" +#define AUDIO "/dev/dvb/adapter0/audio1" +#define VIDEO "/dev/dvb/adapter0/video1" #define BUFFY (188*20) #define MAX_LENGTH (1024*1024*5) /* record 5MB */ diff --git a/dvb-spec/dvbapi/fdl.tex b/dvb-spec/dvbapi/fdl.tex new file mode 100644 index 000000000..c0fcbe3f3 --- /dev/null +++ b/dvb-spec/dvbapi/fdl.tex @@ -0,0 +1,367 @@ +% fdl.tex +% This file is a chapter. It must be included in a larger document to work +% properly. + +\chapter{GNU Free Documentation License} + +Version 1.1, March 2000\\ + + Copyright \copyright\ 2000 Free Software Foundation, Inc.\\ + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA\\ + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + +\section*{Preamble} + +The purpose of this License is to make a manual, textbook, or other +written document ``free'' in the sense of freedom: to assure everyone +the effective freedom to copy and redistribute it, with or without +modifying it, either commercially or noncommercially. Secondarily, +this License preserves for the author and publisher a way to get +credit for their work, while not being considered responsible for +modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +\section{Applicability and Definitions} + +This License applies to any manual or other work that contains a +notice placed by the copyright holder saying it can be distributed +under the terms of this License. The ``Document'', below, refers to any +such manual or work. Any member of the public is a licensee, and is +addressed as ``you''. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (For example, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, whose contents can be viewed and edited directly and +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, \LaTeX~input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML designed for human modification. Opaque formats include +PostScript, PDF, proprietary formats that can be read and edited only +by proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML produced by some word processors for output +purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + + +\section{Verbatim Copying} + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +\section{Copying in Quantity} + +If you publish printed copies of the Document numbering more than 100, +and the Document's license notice requires Cover Texts, you must enclose +the copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + + +\section{Modifications} + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +\begin{itemize} + +\item Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission. +\item List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than five). +\item State on the Title page the name of the publisher of the + Modified Version, as the publisher. +\item Preserve all the copyright notices of the Document. +\item Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. +\item Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below. +\item Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice. +\item Include an unaltered copy of this License. +\item Preserve the section entitled ``History'', and its title, and add to + it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. +\item Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. +\item In any section entitled ``Acknowledgements'' or ``Dedications'', + preserve the section's title, and preserve in the section all the + substance and tone of each of the contributor acknowledgements + and/or dedications given therein. +\item Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles. +\item Delete any section entitled ``Endorsements''. Such a section + may not be included in the Modified Version. +\item Do not retitle any existing section as ``Endorsements'' + or to conflict in title with any Invariant Section. + +\end{itemize} + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties -- for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + + +\section{Combining Documents} + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled ``History'' +in the various original documents, forming one section entitled +``History''; likewise combine any sections entitled ``Acknowledgements'', +and any sections entitled ``Dedications''. You must delete all sections +entitled ``Endorsements.'' + + +\section{Collections of Documents} + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + + +\section{Aggregation With Independent Works} + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, does not as a whole count as a Modified Version +of the Document, provided no compilation copyright is claimed for the +compilation. Such a compilation is called an ``aggregate'', and this +License does not apply to the other self-contained works thus compiled +with the Document, on account of their being thus compiled, if they +are not themselves derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one quarter +of the entire aggregate, the Document's Cover Texts may be placed on +covers that surround only the Document within the aggregate. +Otherwise they must appear on covers around the whole aggregate. + + +\section{Translation} + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the +original English version of this License. In case of a disagreement +between the translation and the original English version of this +License, the original English version will prevail. + + +\section{Termination} + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + + +\section{Future Revisions of This License} + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License "or any later version" applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +\section*{ADDENDUM: How to use this License for your documents} + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +\begin{quote} + + Copyright \copyright\ YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + +\end{quote} + +If you have no Invariant Sections, write ``with no Invariant Sections'' +instead of saying which ones are invariant. If you have no +Front-Cover Texts, write ``no Front-Cover Texts'' instead of +``Front-Cover Texts being LIST''; likewise for Back-Cover Texts. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index e41ef3d54..bb177df1b 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -1,52 +1,176 @@ \devsec{DVB Frontend API} The DVB frontend device controls the tuner and DVB demodulator hardware. -It can be accessed through \texttt{/dev/ost/frontend}. -If you are using \texttt{devfs} you can use \texttt{/dev/dvb/card0/frontend}. -The frontend device will only be made visible through \texttt{devfs} -if the corresponding card actually has a frontend. Cards which support -the DVB API but, e.g., only can play back recordings, will not offer the -frontend device. +It can be accessed through \texttt{/dev/dvb/adapter0/frontend0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/frontend.h} in your application. + +DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) +and DVB-T (terrestrial). Transmission via the internet (DVB-IP) is +not handled by this API. +For DVB-S the frontend device also supports satellite equipment control +(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification +is available from Eutelsat \texttt{http://www.eutelsat.org/}. + +Note that the DVB API may also be used for MPEG decoder-only PCI cards, +in which case there exists no frontend device. \devsubsec{Frontend Data Types} -\devsubsubsec{frontend status} -\label{frontendstatus} +\devsubsubsec{frontend type} +\label{frontendtype} + +For historic reasons frontend types are named after the +type of modulation used in transmission. -Several functions of the frontend device use the feStatus data -type defined by \begin{verbatim} -typedef uint32_t feStatus; +typedef enum fe_type { + FE_QPSK, /* DVB-S */ + FE_QAM, /* DVB-C */ + FE_OFDM /* DVB-T */ +} fe_type_t; \end{verbatim} -to indicate the current state and/or state changes of -the frontend hardware. -\noindent -It can take on the values +\devsubsubsec{frontend capabilities} +\label{frontendcaps} + +Capabilities describe what a frontend can do. Some capabilities +can only be supported for a specific frontend type. + +\begin{verbatim} +typedef enum fe_caps { + FE_IS_STUPID = 0, + FE_CAN_INVERSION_AUTO = 0x1, + FE_CAN_FEC_1_2 = 0x2, + FE_CAN_FEC_2_3 = 0x4, + FE_CAN_FEC_3_4 = 0x8, + FE_CAN_FEC_4_5 = 0x10, + FE_CAN_FEC_5_6 = 0x20, + FE_CAN_FEC_6_7 = 0x40, + FE_CAN_FEC_7_8 = 0x80, + FE_CAN_FEC_8_9 = 0x100, + FE_CAN_FEC_AUTO = 0x200, + FE_CAN_QPSK = 0x400, + FE_CAN_QAM_16 = 0x800, + FE_CAN_QAM_32 = 0x1000, + FE_CAN_QAM_64 = 0x2000, + FE_CAN_QAM_128 = 0x4000, + FE_CAN_QAM_256 = 0x8000, + FE_CAN_QAM_AUTO = 0x10000, + FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000, + FE_CAN_BANDWIDTH_AUTO = 0x40000, + FE_CAN_GUARD_INTERVAL_AUTO = 0x80000, + FE_CAN_HIERARCHY_AUTO = 0x100000, + FE_CAN_MUTE_TS = 0x80000000, + FE_CAN_CLEAN_SETUP = 0x40000000 +} fe_caps_t; +\end{verbatim} + +\devsubsubsec{frontend information} +\label{frontendinfo} + +Information about the frontend ca be queried with +FE\_GET\_INFO (\ref{fegetinfo}). + +\begin{verbatim} +struct dvb_frontend_info { + char name[128]; + fe_type_t type; + uint32_t frequency_min; + uint32_t frequency_max; + uint32_t frequency_stepsize; + uint32_t frequency_tolerance; + uint32_t symbol_rate_min; + uint32_t symbol_rate_max; + uint32_t symbol_rate_tolerance; /* ppm */ + uint32_t notifier_delay; /* ms */ + fe_caps_t caps; +}; +\end{verbatim} + +\devsubsubsec{diseqc master command} +\label{diseqcmastercmd} + +A message sent from the frontend to DiSEqC capable equipment. + +\begin{verbatim} +struct dvb_diseqc_master_cmd { + uint8_t msg [6]; /* { framing, address, command, data[3] } */ + uint8_t msg_len; /* valid values are 3...6 */ +}; +\end{verbatim} + +\devsubsubsec{diseqc slave reply} +\label{diseqcslavereply} + +A reply to the frontend from DiSEqC 2.0 capable equipment. + +\begin{verbatim} +struct dvb_diseqc_slave_reply { + uint8_t msg [4]; /* { framing, data [3] } */ + uint8_t msg_len; /* valid values are 0...4, 0 means no msg */ + int timeout; /* return from ioctl after timeout ms with */ +}; /* errorcode when no message was received */ +\end{verbatim} + +\devsubsubsec{SEC voltage} +\label{secvoltage} + +The voltage is usually used with non-DiSEqC capable LNBs to +switch the polarzation (horizontal/vertical). + +\begin{verbatim} +typedef enum fe_sec_voltage { + SEC_VOLTAGE_13, + SEC_VOLTAGE_18 +} fe_sec_voltage_t; +\end{verbatim} + +\devsubsubsec{SEC continuous tone} +\label{sectone} + +The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to +switch the high/low band of a dual-band LNB. + +\begin{verbatim} +typedef enum fe_sec_tone_mode { + SEC_TONE_ON, + SEC_TONE_OFF +} fe_sec_tone_mode_t; +\end{verbatim} + +\devsubsubsec{SEC tone burst} +\label{sectoneburst} + +The 22KHz tone burst is usually used with non-DiSEqC capable +switches to select between two connected LNBs/satellites. + \begin{verbatim} -#define FE_HAS_POWER 1 -#define FE_HAS_SIGNAL 2 -#define FE_SPECTRUM_INV 4 -#define FE_HAS_LOCK 8 -#define FE_HAS_CARRIER 16 -#define FE_HAS_VITERBI 32 -#define FE_HAS_SYNC 64 -#define TUNER_HAS_LOCK 128 +typedef enum fe_sec_mini_cmd { + SEC_MINI_A, + SEC_MINI_B +} fe_sec_mini_cmd_t; \end{verbatim} -which can be ORed together and have the following meaning: -\medskip -\begin{tabular}{lp{11cm}} -FE\_HAS\_POWER & the frontend is powered up and is ready to be used\\ -FE\_HAS\_SIGNAL & the frontend detects a signal above the normal noise level\\ -FE\_SPECTRUM\_INV & spectrum inversion is enabled/was necessary for lock\\ -FE\_HAS\_LOCK & frontend successfully locked to a DVB signal \\ -FE\_HAS\_CARRIER & carrier detected in signal\\ -FE\_HAS\_VITERBI & lock at viterbi decoder stage\\ -FE\_HAS\_SYNC & TS sync bytes detected \\ -TUNER\_HAS\_LOCK & the tuner has a frequency lock -\end{tabular} +\devsubsubsec{frontend status} +\label{frontendstatus} + +Several functions of the frontend device use the fe\_status data +type defined by +\begin{verbatim} +typedef enum fe_status { + FE_HAS_SIGNAL = 0x01, /* found something above the noise level */ + FE_HAS_CARRIER = 0x02, /* found a DVB signal */ + FE_HAS_VITERBI = 0x04, /* FEC is stable */ + FE_HAS_SYNC = 0x08, /* found sync bytes */ + FE_HAS_LOCK = 0x10, /* everything's working... */ + FE_TIMEDOUT = 0x20, /* no lock within the last ~2 seconds */ + FE_REINIT = 0x40 /* frontend was reinitialized, */ +} fe_status_t; /* application is recommned to reset */ +\end{verbatim} +to indicate the current state and/or state changes of +the frontend hardware. \devsubsubsec{frontend parameters} @@ -57,45 +181,44 @@ depend on the kind of hardware you are using. All kinds of parameters are combined as a union in the FrontendParameters structure: \begin{verbatim} -typedef struct { - __u32 Frequency; /* (absolute) frequency in Hz for QAM/OFDM */ - /* intermediate frequency in kHz for QPSK */ - fe_spectral_inversion_t Inversion; /* spectral inversion */ +struct dvb_frontend_parameters { + uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */ + /* intermediate frequency in kHz for QPSK */ + fe_spectral_inversion_t inversion; union { - QPSKParameters qpsk; - QAMParameters qam; - OFDMParameters ofdm; + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; } u; -} FrontendParameters; +}; \end{verbatim} For satellite QPSK frontends you have to use QPSKParameters defined by \begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - fe_code_rate_t FEC_inner; /* forward error correction (see above) */ -} QPSKParameters; +struct dvb_qpsk_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ +}; \end{verbatim} for cable QAM frontend you use the QAMParameters structure \begin{verbatim} -typedef struct { - __u32 SymbolRate; /* symbol rate in Symbols per second */ - fe_code_rate_t FEC_outer; /* forward error correction (see above) */ - fe_code_rate_t FEC_inner; /* forward error correction (see above) */ - fe_modulation_t QAM; /* modulation type (see above) */ -} QAMParameters; +struct dvb_qam_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ + fe_modulation_t modulation; /* modulation type (see above) */ +}; \end{verbatim} DVB-T frontends are supported by the OFDMParamters structure \begin{verbatim} -typedef struct { - fe_bandwidth_t bandWidth; - fe_code_rate_t HP_fe_code_rate_t; /* high priority stream code rate */ - fe_code_rate_t LP_fe_code_rate_t; /* low priority stream code rate */ - fe_modulation_t Constellation; /* modulation type (see above) */ - fe_transmit_mode_t TransmissionMode; - fe_guard_interval_t guardInterval; - fe_hierarchy_t fe_hierarchy_tInformation; -} OFDMParameters; +struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /* high priority stream code rate */ + fe_code_rate_t code_rate_LP; /* low priority stream code rate */ + fe_modulation_t constellation; /* modulation type (see above) */ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; +}; \end{verbatim} In the case of QPSK frontends the Frequency field specifies the intermediate @@ -107,7 +230,7 @@ and is given in Hz. The Inversion field can take one of these values: \begin{verbatim} -typedef enum { +typedef enum fe_spectral_inversion { INVERSION_OFF, INVERSION_ON, INVERSION_AUTO @@ -120,15 +243,18 @@ try to figure out the correct setting by itself. \noindent The possible values for the FEC\_inner field are \begin{verbatim} -enum { - FEC_AUTO, +typedef enum fe_code_rate { + FEC_NONE = 0, FEC_1_2, FEC_2_3, FEC_3_4, + FEC_4_5, FEC_5_6, + FEC_6_7, FEC_7_8, - FEC_NONE -}; + FEC_8_9, + FEC_AUTO +} fe_code_rate_t; \end{verbatim} which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., no error correction or auto detection. @@ -137,47 +263,52 @@ no error correction or auto detection. For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature modulation mode which can be one of the following: \begin{verbatim} -typedef enum -{ QPSK, +typedef enum fe_modulation { + QPSK, QAM_16, QAM_32, QAM_64, QAM_128, - QAM_256 -} QAM_TYPE; + QAM_256, + QAM_AUTO +} fe_modulation_t; \end{verbatim} Finally, there are several more parameters for OFDM: \begin{verbatim} -typedef enum { +typedef enum fe_transmit_mode { TRANSMISSION_MODE_2K, - TRANSMISSION_MODE_8K + TRANSMISSION_MODE_8K, + TRANSMISSION_MODE_AUTO } fe_transmit_mode_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_bandwidth { BANDWIDTH_8_MHZ, BANDWIDTH_7_MHZ, - BANDWIDTH_6_MHZ + BANDWIDTH_6_MHZ, + BANDWIDTH_AUTO } fe_bandwidth_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_guard_interval { GUARD_INTERVAL_1_32, GUARD_INTERVAL_1_16, GUARD_INTERVAL_1_8, - GUARD_INTERVAL_1_4 + GUARD_INTERVAL_1_4, + GUARD_INTERVAL_AUTO } fe_guard_interval_t; \end{verbatim} \begin{verbatim} -typedef enum { +typedef enum fe_hierarchy { HIERARCHY_NONE, HIERARCHY_1, HIERARCHY_2, - HIERARCHY_4 + HIERARCHY_4, + HIERARCHY_AUTO } fe_hierarchy_t; \end{verbatim} @@ -186,78 +317,12 @@ typedef enum { \label{frontendevents} \begin{verbatim} -enum { - FE_UNEXPECTED_EV, - FE_COMPLETION_EV, - FE_FAILURE_EV +struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; }; \end{verbatim} -\begin{verbatim} -typedef struct { - EventType type; /* type of event, FE_UNEXPECTED_EV, ... */ - long timestamp; /* time in seconds since 1970-01-01 */ - - union { - struct { - fe_status_t previousStatus; /* status before event */ - fe_status_t currentStatus; /* status during event */ - } unexpectedEvent; - FrontendParameters completionEvent; /* parameters for which the - tuning succeeded */ - fe_status_t failureEvent; /* status at failure (e.g. no lock) */ - } u; -} FrontendEvent; -\end{verbatim} - -\begin{verbatim} -struct qpskRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qamRegister { - uint8_t chipId; - uint8_t address; - uint8_t value; -}; -\end{verbatim} - -\begin{verbatim} -struct qpskFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -struct qamFrontendInfo { - uint32_t minFrequency; - uint32_t maxFrequency; - uint32_t maxSymbolRate; - uint32_t minSymbolRate; - uint32_t hwType; - uint32_t hwVersion; -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - FE_POWER_ON, - FE_POWER_STANDBY, - FE_POWER_SUSPEND, - FE_POWER_OFF -} powerState_t; -\end{verbatim} - - \clearpage @@ -265,9 +330,9 @@ typedef enum { \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named frontend device (e.g. /dev/ost/qpskfe - for a satellite frontend or /dev/ost/qamfe for a cable frontend) - for subsequent use. + This system call opens a named frontend device (/dev/dvb/adapter0/frontend0) + for subsequent use. Usually the first thing to do after a successful open + is to find out the frontend type with FE\_GET\_INFO. The device can be opened in read-only mode, which only allows monitoring of device status and statistics, or read/write mode, which allows @@ -303,119 +368,21 @@ typedef enum { int close(int fd);}{ 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. + powered down automatically. }{ int fd & File descriptor returned by a previous call to open().\\ }{ EBADF & fd is not a valid open file descriptor.\\ } -\ifunction{OST\_SELFTEST}{ - int ioctl(int fd, int request = OST\_SELFTEST);}{ - This ioctl call initiates an automatic self-test of the front-end hardware. - This call requires read/write access to the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SELFTEST for this command.\\ - }{ - -1& Self test failure.\\ -} - -\ifunction{OST\_SET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_SET\_POWER\_STATE, uint32\_t state);}{ - 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 supports 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: \\ - \begin{center} - \begin{tabular}[h]{cll} - number of low-power & requested state & resulting state\\ - states supported &&\\ - \\ - 1 & standby & suspend \\ - 1 & suspend & suspend \\ - 0 & standby & on \\ - 0 & suspend & on - \end{tabular} - \end{center}\\ - 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.) - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_SET\_POWER\_STATE for this command.\\ - uint32\_t state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - 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\\ - \end{tabular} - }{ - 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. -} - -\ifunction{FE\_GET\_POWER\_STATE}{ - int ioctl(int fd, int request = OST\_GET\_POWER\_STATE, uint32\_t *state);}{ - 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals OST\_GET\_POWER\_STATE for this command.\\ - uint32\_t *state & Requested power state. One of: \\ - & - \begin{tabular}[h]{ll} - 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\\ - \end{tabular} - }{ - EBADF& fd is not a valid open file descriptor.\\ - EINVAL& Illegal state, or not available on this device.\\ - EFAULT& state points to invalid address.\\ - ENOSYS& Function not available for this device. -} - \ifunction{FE\_READ\_STATUS}{ - int ioctl(int fd, int request = FE\_READ\_STATUS, feStatus *status);}{ + int ioctl(int fd, int request = FE\_READ\_STATUS, fe\_status\_t *status);}{ This ioctl call returns status information about the front-end. This call only requires read-only access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_STATUS for this command.\\ - struct feStatus *status&Points to the location where the front-end + struct fe\_status\_t *status & Points to the location where the front-end status word is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ @@ -430,10 +397,7 @@ typedef enum { }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_BER for this command.\\ - uint32\_t *ber & 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\cdot 10^{-6}$, or 1 error in 400000 bits. + uint32\_t *ber & The bit error rate is stored into *ber.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& ber points to invalid address.\\ @@ -443,17 +407,14 @@ typedef enum { } \ifunction{FE\_READ\_SNR}{ - int ioctl(int fd, int request = FE\_READ\_SNR, int32\_t *snr);}{ + int ioctl(int fd, int request = FE\_READ\_SNR, int16\_t *snr);}{ 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. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_SNR for this command.\\ - int32\_t *snr& 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. + int16\_t *snr& The signal-to-noise ratio is stored into *snr.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& snr points to invalid address.\\ @@ -463,7 +424,7 @@ typedef enum { } \ifunction{FE\_READ\_SIGNAL\_STRENGTH}{ - int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int32\_t *strength); + int ioctl( int fd, int request = FE\_READ\_SIGNAL\_STRENGTH, int16\_t *strength); }{ 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 @@ -471,11 +432,7 @@ is sufficient. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_READ\_SIGNAL\_STRENGTH for this command.\\ -int32\_t *strength & 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. +int16\_t *strength & The signal strength value is stored into *strength.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& status points to invalid address.\\ @@ -505,59 +462,8 @@ by the driver so far. } -\ifunction{FE\_GET\_NEXT\_FREQUENCY}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_FREQUENCY, uint32\_t *freq);}{ - 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 efficient 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.\\ - Note that scanning may still be excruciatingly slow on some hardware, for - other reasons than a non-optimal scanning step size. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_FREQUENCY for this command.\\ - uint32\_t *freq& Input: a given frequency \\ - & Output: the frequency corresponding to - the next higher frequency setting.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& freq points to invalid address.\\ - EINVAL& Maximum supported frequency reached.\\ - ENOSYS& Function not available for this device. -} - -\ifunction{FE\_GET\_NEXT\_SYMBOL\_RATE}{ - int ioctl( int fd, int request = FE\_GET\_NEXT\_SYMBOL\_RATE, uint32\_t *symbolRate); - }{ - 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 efficient 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. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_GET\_NEXT\_SYMBOL\_RATE for this command.\\ - uint32\_t *symbolRate& Input: a given symbol rate \\ - & Output: the symbol rate corresponding to - the next higher symbol rate.\\ - }{ - EBADF& fd is not a valid open file descriptor.\\ - EFAULT& symbolRate points to invalid address.\\ - EINVAL& Maximum supported symbol rate reached.\\ - ENOSYS& Function not available for this device. -} - \ifunction{FE\_SET\_FRONTEND}{ - int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct FrontendParameters *p);}{ + int ioctl(int fd, int request = FE\_SET\_FRONTEND, struct dvb\_frontend\_parameters *p);}{ 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. @@ -571,7 +477,21 @@ by the driver so far. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_SET\_FRONTEND for this command.\\ - struct FrontendParameters *p& Points to parameters for tuning operation.\\ + struct dvb\_frontend\_parameters *p& Points to parameters for tuning operation.\\ + }{ + EBADF& fd is not a valid open file descriptor.\\ + EFAULT& p points to invalid address.\\ + EINVAL& Maximum supported symbol rate reached.\\ +} + +\ifunction{FE\_GET\_FRONTEND}{ + int ioctl(int fd, int request = FE\_GET\_FRONTEND, struct dvb\_frontend\_parameters *p);}{ + This ioctl call queries the currently effective frontend parameters. + For this command, read-only access to the device is sufficient. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_SET\_FRONTEND for this command.\\ + struct dvb\_frontend\_parameters *p& Points to parameters for tuning operation.\\ }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& p points to invalid address.\\ @@ -579,8 +499,8 @@ by the driver so far. } \ifunction{FE\_GET\_EVENT}{ - int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct qpskEvent *ev);}{ - This ioctl call returns an event of type qpskEvent if available. If an event + int ioctl(int fd, int request = QPSK\_GET\_EVENT, struct dvb\_frontend\_event *ev);}{ + This ioctl call returns a frontend event if available. If an event is not available, the behavior depends on whether the device is in blocking or non-blocking mode. In the latter case, the call fails immediately with errno set to EWOULDBLOCK. In the former case, the call blocks until an event @@ -593,14 +513,15 @@ by the driver so far. must be serviced regularly to avoid overflow. If an overflow happens, the oldest event is discarded from the queue, and an error (EOVERFLOW) occurs the next time the queue is read. After reporting the error condition in this - fashion, subsequent QPSK\_GET\_EVENT calls will return events from the queue as + fashion, subsequent FE\_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. }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals QPSK\_GET\_EVENT for this command.\\ - struct qpskEvent *ev&Points to the location where the event, if any, is to be stored. + int request & Equals FE\_GET\_EVENT for this command.\\ + struct dvb\_frontend\_event *ev & Points to the location where the event,\\ + & if any, is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& ev points to invalid address.\\ @@ -611,19 +532,133 @@ by the driver so far. } \ifunction{FE\_GET\_INFO}{ - int ioctl(int fd, int request = FE\_GET\_INFO, struct FrontendInfo *info);}{ +\label{fegetinfo} + int ioctl(int fd, int request = FE\_GET\_INFO, struct dvb\_frontend\_info *info);}{ This ioctl call returns information about the front-end. This call only requires read-only access to the device. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_GET\_INFO for this command.\\ - struct qpskFrontendInfo *info & Points to the location where the front-end + struct dvb\_frontend\_info *info & Points to the location where the front-end information is to be stored. }{ EBADF& fd is not a valid open file descriptor.\\ EFAULT& info points to invalid address.\\ } +\ifunction{FE\_DISEC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = FE\_DISEC\_RESET\_OVERLOAD);}{ + If the bus has been automatically powered off due to power overload, this + ioctl call restores the power to the bus. The call requires read/write + access to the device. + This call has no effect if the device is manually powered off. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_RESET\_OVERLOAD for this command.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{FE\_DISEC\_SEND\_MASTER\_CMD}{ +int ioctl(int fd, int request = FE\_DISEC\_SEND\_MASTER\_CMD, struct dvb\_diseqc\_master\_cmd *cmd);}{ + This ioctl call is used to send a a DiSEqC command.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_SEND\_MASTER\_CMD for this command.\\ + struct dvb\_diseqc\_master\_cmd *cmd & Pointer to the command to be transmitted.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & Seq points to an invalid address.\\ + EINVAL & The data structure referred to by seq is invalid in some way.\\ + EPERM & Permission denied (needs read/write access).\\ + EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{FE\_DISEC\_RECV\_SLAVE\_REPLY}{ +int ioctl(int fd, int request = FE\_DISEC\_RECV\_SLAVE\_REPLY, struct dvb\_diseqc\_slave\_reply *reply);}{ +This ioctl call is used to receive reply to a DiSEqC 2.0 command.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_RECV\_SLAVE\_REPLY for this command.\\ + struct dvb\_diseqc\_slave\_reply *reply & Pointer to the command to be received.\\ + }{ + 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.\\ +} + +\ifunction{FE\_DISEC\_SEND\_BURST}{ +int ioctl(int fd, int request = FE\_DISEC\_SEND\_BURST, fe\_sec\_mini\_cmd\_t burst);}{ +This ioctl call is used to send a 22KHz tone burst.\\ + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals FE\_DISEC\_SEND\_BURST for this command.\\ + fe\_sec\_mini\_cmd\_t burst & burst A or B.\\ + }{ + 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.\\ +} + + +\ifunction{FE\_SET\_TONE}{ +int ioctl(int fd, int request = FE\_SET\_TONE, fe\_sec\_tone\_mode\_t tone);}{ +This call is used to set the generation of the continuous 22kHz tone. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_SET\_TONE for this command.\\ +fe\_sec\_tone\_mode\_t tone & The requested tone generation mode (on/off).\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + + +\ifunction{FE\_SET\_VOLTAGE}{ +int ioctl(int fd, int request = FE\_SET\_VOLTAGE, fe\_sec\_voltage\_t voltage);}{ +This call is used to set the bus voltage. +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_SET\_VOLTAGE for this command.\\ +fe\_sec\_voltage\_t voltage & The requested bus voltage.\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + +\ifunction{FE\_ENABLE\_HIGH\_LNB\_VOLTAGE}{ +int ioctl(int fd, int request = FE\_ENABLE\_HIGH\_LNB\_VOLTAGE, int high);}{ +If high != 0 enables slightly higher voltages instead of 13/18V +(to compensate for long cables). +This call requires read/write permissions. +}{ +int fd & File descriptor returned by a previous call to open().\\ +int request & Equals FE\_SET\_VOLTAGE for this command.\\ +int high & The requested bus voltage.\\ +}{ +ENODEV & Device driver not loaded/available.\\ +EBUSY & Device or resource busy.\\ +EINVAL & Invalid argument.\\ +EPERM & File not opened with read permissions.\\ +EINTERNAL & Internal error in the device driver.\\ +} + + %%% Local Variables: %%% mode: latex %%% TeX-master: "dvbapi" diff --git a/dvb-spec/dvbapi/intro.tex b/dvb-spec/dvbapi/intro.tex index 1d859fadb..613bcd6c8 100644 --- a/dvb-spec/dvbapi/intro.tex +++ b/dvb-spec/dvbapi/intro.tex @@ -1,15 +1,21 @@ \chapter{Introduction} %\addcontentsline{toc}{part}{Introduction} %\chaptermark{Introduction} + \section{What you need to know} + The reader of this document is required to have some knowledge in the area of digital video broadcasting (DVB) and should be familiar with -part I of ISO/IEC 13818, i.e you should know what a -program/transport stream (PS/TS) is and what is meant by a packetized elementary -stream (PES) or an I-frame. +part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), +i.e you should know what a program/transport stream (PS/TS) is and what is +meant by a packetized elementary stream (PES) or an I-frame. + +Various DVB standards documents are available from +\texttt{http://www.dvb.org/} and/or \texttt{http://www.etsi.org/}. It is also necessary to know how to access unix/linux devices and how to use ioctl calls. This also includes the knowledge of C or C++. + \section{History} The first API for DVB cards we used at Convergence in late 1999 @@ -26,11 +32,12 @@ Nokia and Convergence made it available to all Linux developers and published it on \texttt{http://www.linuxtv.org/} in September 2000. Convergence is the maintainer of the Linux DVB API. Together with the LinuxTV community (i.e. you, the reader of this document), -the Linux DVB API will be constantly reviewed and improved upon. +the Linux DVB API will be constantly reviewed and improved. With the Linux driver for the Siemens/Hauppauge DVB PCI card Convergence provides a first implementation of the Linux DVB API. +\newpage \section{Overview} \begin{figure}[htbp] @@ -49,14 +56,10 @@ main hardware components: Here the raw signal reaches the DVB hardware from a satellite dish or antenna or directly from cable. The frontend down-converts and demodulates -this signal into an MPEG transport stream (TS). - -\item SEC for controlling external hardware like LNBs and antennas - -This part of the hardware can send signals back through the satellite -cable to control the polarization of the LNB, to switch between -different LNBs or even to control the movements of a dish rotor. - +this signal into an MPEG transport stream (TS). In case of a satellite +frontend, this includes a facility for satellite equipment control (SEC), +which allows control of LNB polarization, multi feed switches or +dish rotors. \item Conditional Access (CA) hardware like CI adapters and smartcard slots @@ -74,10 +77,11 @@ or other streams of the same provider. \item MPEG2 audio and video decoder The main targets of the demultiplexer are the MPEG2 audio and video -decoders. After decoding the pass on the uncompressed audio +decoders. After decoding they pass on the uncompressed audio and video to the computer screen or (through a PAL/NTSC encoder) to a TV set. \end{itemize} + Figure \ref{fig:dvbstb} shows a crude schematic of the control and data flow between those components. @@ -91,11 +95,9 @@ Also not every card or STB provides conditional access hardware. The Linux DVB API lets you control these hardware components through currently six Unix-style character devices for -video, audio, frontend, SEC, demux and CA. +video, audio, frontend, demux, CA and IP-over-DVB networking. The video and audio devices control the MPEG2 decoder hardware, the frontend device the tuner and the DVB demodulator. -External hardware like DiSEqC switches and rotors can be controlled -through the SEC device. The demux device gives you control over the PES and section filters of the hardware. If the hardware does not support filtering these filters can be implemented in software. @@ -104,78 +106,41 @@ of the hardware. It can depend on the individual security requirements of the platform, if and how many of the CA functions are made available to the application through this device. +\smallskip All devices can be found in the \texttt{/dev} tree under -\texttt{/dev/ost}, where OST stands for Open Standards Terminal. -The individual devices are called +\texttt{/dev/dvb}. The individual devices are called \begin{itemize} -\item \texttt{/dev/ost/audio}, -\item \texttt{/dev/ost/video}, -\item \texttt{/dev/ost/frontend}, -\item \texttt{/dev/ost/sec}, -\item \texttt{/dev/ost/demux}, -\item \texttt{/dev/ost/ca}, +\item \texttt{/dev/dvb/adapterN/audioM}, +\item \texttt{/dev/dvb/adapterN/videoM}, +\item \texttt{/dev/dvb/adapterN/frontendM}, +\item \texttt{/dev/dvb/adapterN/netM}, +\item \texttt{/dev/dvb/adapterN/demuxM}, +\item \texttt{/dev/dvb/adapterN/caM}, \end{itemize} -but we will omit the ``\texttt{/dev/ost/}'' in the further dicussion of -these devices. - -If more than one card is present in the system the other cards -can be accessed through the corresponding devices with the -card's number appended. \texttt{/dev/ost/demux0} (which -is identical to \texttt{/dev/ost/demux}) would, e.g., control the -demultiplexer of the first card, while \texttt{/dev/ost/demux1} -would control the demultiplexer of the second card, and so on. +where N enumerates the DVB PCI cards in a system starting from~0, +and M enumerates the devices of each type within each adapter, starting +from~0, too. +We will omit the ``\texttt{/dev/dvb/adapterN/}'' in the further dicussion of +these devices. The naming scheme for the devices is the same wheter devfs +is used or not. More details about the data structures and function calls of all the devices are described in the following chapters. +\section{API include files} -\section{DVB Devices with Devfs} - -Recent Linux kernel versions support a special file system called -\textsl{devfs} which is a replacement for the traditional -device directory. -With devfs a Linux DVB driver will only create those device file entries -which actually exist. -It also makes dealing with more complex DVB hardware much easier. -The device structure described above is not well suited to deal -with multiple DVB cards with more than one frontend or demultiplexer. -Consider, e.g., two DVB cards, one with two frontends and -one demultiplexer, the other with one frontend and two demultiplexers. -If we just assign them consecutive numbers, there would be a demultiplexer -and a frontend which do not belong to the same card but have -the same number. - -With \textsl{devfs} we propose a different scheme for the device names. -The root directory for all DVB cards will be \texttt{/dev/dvb}. -Each card gets assigned a sub-directory with the name \texttt{/dev/card0}, -\texttt{/dev/card1}, etc. -The files created in these sub-directories will correspond directly to the -hardware actually present on the card. -Thus, if the first card has one QAM frontend, one demultiplexer -and otherwise no other hardware, -only \texttt{/dev/dvb/card0/qamfe0} and \texttt{/dev/dvb/card0/demux0} -will be created. -When a second DVB-S card with one frontend (including SEC) device, -two demultiplexers and an MPEG2 audio/video decoder is added, the -complete \texttt{/dev/dvb} tree will look like this: +For each of the DVB devices a corresponding include file +exists. The DVB API include files should be included +in application sources with a partial path like: \begin{verbatim} -/dev/dvb/card0/frontend0 - demux0 - -/dev/dvb/card1/video0 - audio0 - demux0 - demux1 - frontend0 - sec0 +#include \end{verbatim} - -\section{Using the Devices} - -\dots - +To enable applications to support different API version, an additional +include file \texttt{linux/dvb/version.h} exists, which defines the +constant \texttt{DVB\_API\_VERSION}. This document describes +\texttt{DVB\_API\_VERSION~3}. %%% Local Variables: %%% mode: latex diff --git a/dvb-spec/dvbapi/kdapi.tex b/dvb-spec/dvbapi/kdapi.tex index 59490299b..f7fc69353 100644 --- a/dvb-spec/dvbapi/kdapi.tex +++ b/dvb-spec/dvbapi/kdapi.tex @@ -1,6 +1,13 @@ \devsec{Kernel Demux API} -The kernel demux API +The kernel demux API defines a driver-internal interface +for registering low-level, hardware specific driver to a +hardware independent demux layer. It is only of interest +for DVB device driver writers. The header file for this +API is named \texttt{demux.h} and located in +\texttt{drivers/media/dvb/dvb-core}. + +Maintainer note: This section must be reviewed. It is probably out of date. \devsubsec{Kernel Demux Data Types} diff --git a/dvb-spec/dvbapi/net.tex b/dvb-spec/dvbapi/net.tex new file mode 100644 index 000000000..dc6566633 --- /dev/null +++ b/dvb-spec/dvbapi/net.tex @@ -0,0 +1,19 @@ +\devsec{DVB Network API} + +The DVB net device enables feeding of MPE (multi protocol +encapsulation) packets received via DVB into the Linux network +protocol stack, e.g. for internet via satellite applications. +It can be accessed through \texttt{/dev/dvb/adapter0/net0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/net.h} in your application. + + +\devsubsec{DVB Net Data Types} + +To be written\dots + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "dvbapi" +%%% End: diff --git a/dvb-spec/dvbapi/sec.tex b/dvb-spec/dvbapi/sec.tex deleted file mode 100644 index 88342c3a6..000000000 --- a/dvb-spec/dvbapi/sec.tex +++ /dev/null @@ -1,282 +0,0 @@ -\devsec{DVB SEC API} - -The DVB SEC device controls the Satellite Equipment Control of -the DVB hardware, i.e. DiSEqC and V-SEC. -It is accessed through \texttt{/dev/ost/sec}. - -\devsubsec{SEC Data Types} - -\devsubsubsec{secDiseqcCmd} -\label{secdiseqccmd} - -\begin{verbatim} -struct secDiseqcCmd { - uint8_t addr; - uint8_t cmd; - uint8_t numParams; - uint8_t params[SEC_MAX_DISEQC_PARAMS]; -}; -\end{verbatim} - - -\devsubsubsec{secVoltage} -\label{secvoltage} - -\begin{verbatim} -typedef uint32_t secVoltage; -\end{verbatim} -\begin{verbatim} -enum { - SEC_VOLTAGE_OFF, - SEC_VOLTAGE_LT, - SEC_VOLTAGE_13, - SEC_VOLTAGE_13_5, - SEC_VOLTAGE_18, - SEC_VOLTAGE_18_5 -}; -\end{verbatim} - - -\devsubsubsec{secToneMode} -\label{sectonemode} - -\begin{verbatim} -typedef uint32_t secToneMode; -\end{verbatim} -\begin{verbatim} -typedef enum { - SEC_TONE_ON, - SEC_TONE_OFF -} secToneMode_t; -\end{verbatim} - - -\devsubsubsec{secMiniCmd} -\label{secminicmd} - -\begin{verbatim} -typedef uint32_t secMiniCmd; -\end{verbatim} -\begin{verbatim} -typedef enum { - SEC_MINI_NONE, - SEC_MINI_A, - SEC_MINI_B -} secMiniCmd_t; -\end{verbatim} -\begin{verbatim} -struct secStatus { - int32_t busMode; - secVoltage selVolt; - secToneMode contTone; -}; -\end{verbatim} - -\begin{verbatim} -enum { - SEC_BUS_IDLE, - SEC_BUS_BUSY, - SEC_BUS_OFF, - SEC_BUS_OVERLOAD -}; -\end{verbatim} - - -\devsubsubsec{secCommand} -\label{seccommand} - -\begin{verbatim} -struct secCommand { - int32_t type; - union { - struct secDiseqcCmd diseqc; - uint8_t vsec; - uint32_t pause; - } u; -}; -\end{verbatim} - - -\devsubsubsec{secCmdSequence} -\label{seccmdsequence} - -\begin{verbatim} -struct secCmdSequence { - secVoltage voltage; - secMiniCmd miniCommand; - secToneMode continuousTone; - - uint32_t numCommands; - struct secCommand* commands; -}; -\end{verbatim} - -\begin{verbatim} -enum { - SEC_CMDTYPE_DISEQC, - SEC_CMDTYPE_VSEC, - SEC_CMDTYPE_PAUSE -}; -\end{verbatim} - -\begin{verbatim} -typedef enum { - SEC_DISEQC_SENT, - SEC_VSEC_SENT, - SEC_PAUSE_COMPLETE, - SEC_CALLBACK_ERROR -} secCallback_t; -\end{verbatim} - -\clearpage - -\devsubsec{SEC Function Calls} - -\function{open()}{ - int open(const char *deviceName, int flags);}{ - This system call opens a named SEC device for subsequent use. - If the device is opened in read-only mode, only status and statistics - monitoring is allowed. If the device is opened in read/write mode, all - types of operations can be performed. - Any number of applications can have simultaneous access to the device. - }{ - const char *deviceName & Name of specific SEC device.\\ - int flags & A bit-wise OR of the following flags:\\ - & \hspace{1em} O\_RDONLY read-only access\\ - & \hspace{1em} O\_RDWR read/write access\\ - & The optional flag O\_NONBLOCK is not supported. If O\_NONBLOCK is set, - open() and most other subsequent calls to the device will return -1 and - set errno to EWOULDBLOCK. - The communication with the peripheral devices is sequential by nature, - so it is probably preferable to use the device in synchronous mode. - This is the motivation for not going through the extra effort of - implementing asynchronous operation of the device. - }{ - ENODEV & Device driver not loaded/available.\\ - EFAULT & deviceName does not refer to a valid memory area.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ -} - -\function{close()}{ - int close(int fd);}{ - This system call closes a previously opened SEC device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - }{ - EBADF & fd is not a valid open file descriptor.\\ -} - -\ifunction{SEC\_GET\_STATUS}{ - int ioctl(int fd, int request = SEC\_GET\_STATUS, struct secStatus* status);}{ - This call gets the status of the device. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_GET\_STATUS for this command.\\ - struct secStatus* status & The status of the device.\\ - }{ - ENODEV & Device driver not loaded/available.\\ - EFAULT & status is an invalid pointer.\\ - EBUSY & Device or resource busy.\\ - EINVAL & Invalid argument.\\ - EPERM & File not opened with read permissions.\\ - EINTERNAL & Internal error in the device driver.\\ -} - -\ifunction{SEC\_RESET\_OVERLOAD}{ - int ioctl(int fd, int request = SEC\_RESET\_OVERLOAD);}{ - If the bus has been automatically powered off due to power overload, this - ioctl call restores the power to the bus. The call requires read/write - access to the device. - This call has no effect if the device is manually powered off. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_RESET\_OVERLOAD for this command.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EPERM & Permission denied (needs read/write access).\\ - EINTERNAL & Internal error in the device driver.\\ -} - -\ifunction{SEC\_SEND\_SEQUENCE}{ -int ioctl(int fd, int request = SEC\_SEND\_SEQUENCE, struct secCmdSequence *seq); -}{ -This ioctl call is used to send a sequence of DiSEqCTM and/or V-SEC -commands. The first version of the SEC device does not support V-SEC -signaling and it aborts the operation with an error code if a V-SEC -command is detected in the input data.\\ -\begin{itemize} -\item[$\bullet$] The call will fail with errno set to EBUSOVERLOAD if the bus is -overloaded. If the bus is overloaded, SEC\_RESET\_OVERLOAD can be -called and the operation can be retried. -\item[$\bullet$] If seq.numCommands equals 0 and seq.miniCommand equals SEC\_MINI\_NONE, -the bus voltage will be switched and the continuous 22kHz tone -generation enabled/disabled immediately. -\end{itemize}\\ -This operation is atomic. If several processes calls this ioctl -simultaneously, the operations will be serialized so a complete sequence -is sent at a time. - }{ - int fd & File descriptor returned by a previous call to open().\\ - int request & Equals SEC\_SEND\_SEQUENCE for this command.\\ - struct secCmdSequence *seq & Pointer to the command sequence to be transmitted.\\ - }{ - EBADF & fd is not a valid file descriptor.\\ - EFAULT & Seq points to an invalid address.\\ - EINVAL & The data structure referred to by seq is invalid in some way.\\ - EPERM & Permission denied (needs read/write access).\\ - EINTERNAL & Internal error in the device driver.\\ - EBUSMODE & The device is not prepared for transmission - (e.g. it might be manually powered off).\\ - EBUSOVERLOAD & Bus overload has occurred.\\ -} - - -\ifunction{SEC\_SET\_TONE}{ -int ioctl(int fd, int request = SEC\_SET\_TONE, secToneMode tone); -}{ -This call is used to set the generation of the continuous 22kHz tone. -The possibility to just change the tone mode is already provided by -ioctl SEC\_SEND\_SEQUENCE, but SEC\_SET\_TONE is an easier to use interface. -To keep the transmission of a command sequence as -an atomic operation, SEC\_SET\_TONE will block if a transmission is in -progress. This call requires read/write permissions. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals SEC\_SET\_TONE for this command.\\ -secToneMode tone & The requested tone generation mode (on/off).\\ -}{ -ENODEV & Device driver not loaded/available.\\ -EBUSY & Device or resource busy.\\ -EINVAL & Invalid argument.\\ -EPERM & File not opened with read permissions.\\ -EINTERNAL & Internal error in the device driver.\\ -} - - -\ifunction{SEC\_SET\_VOLTAGE}{ -int ioctl(int fd, int request = SEC\_SET\_VOLTAGE, secVoltage voltage); -}{ -This call is used to set the bus voltage. The possibility to just change -the bus voltage is already provided by ioctl SEC\_SEND\_SEQUENCE, but -SEC\_SET\_VOLTAGE is an easier to use interface. -To keep the transmission of a command sequence as -an atomic operation, SEC\_SET\_VOLTAGE will block if a transmission is in -progress. -This call requires read/write permissions. -}{ -int fd & File descriptor returned by a previous call to open().\\ -int request & Equals SEC\_SET\_VOLTAGE for this command.\\ -secVoltage voltage & The requested bus voltage.\\ -}{ -ENODEV & Device driver not loaded/available.\\ -EBUSY & Device or resource busy.\\ -EINVAL & Invalid argument.\\ -EPERM & File not opened with read permissions.\\ -EINTERNAL & Internal error in the device driver.\\ -} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: "dvbapi" -%%% End: diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex index 574464d23..29aca30d6 100644 --- a/dvb-spec/dvbapi/title.tex +++ b/dvb-spec/dvbapi/title.tex @@ -1,23 +1,27 @@ \pagenumbering{arabic} \pagestyle{empty} -\title{\huge\textbf{LINUX DVB API}} +\title{\huge\textbf{LINUX DVB API Version 3}} \author{ \includegraphics{cimlogo.psi}\\ - Convergence integrated media GmbH\\\\ - Dr. Ralph J.K. Metzler\\ - \texttt{}\\\\ - Dr. Marcus O.C. Metzler\\ - \texttt{} -% Rosenthalerstr. 51\\ -% 10178 Berlin\\Germany + Copyright 2002, 2003 Convergence GmbH\\\\ + Written by Dr. Ralph J.K. Metzler\\ + \texttt{}\\\\ + and Dr. Marcus O.C. Metzler\\ + \texttt{}\\ } -\date{02/14/2002\\V 0.9.4} +\date{02/10/2003\\V 1.0.0-pre1} + \maketitle +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation. +A copy of the license is included in the chapter entitled "GNU +Free Documentation License". + \newpage -%\end{titlepage} % Local Variables: % mode: latex % TeX-master: "dvbapi" diff --git a/dvb-spec/dvbapi/video.tex b/dvb-spec/dvbapi/video.tex index 7300c95c0..3fa066b87 100644 --- a/dvb-spec/dvbapi/video.tex +++ b/dvb-spec/dvbapi/video.tex @@ -1,11 +1,22 @@ \devsec{DVB Video Device} The DVB video device controls the MPEG2 video decoder of the DVB hardware. -It can be accessed through \texttt{/dev/ost/video}. -The include file \texttt{ost/video.h} defines the data types and lists -all I/O calls. Please note that some DVB cards don't have their own -MPEG decoder, which results in the omission of the audio and video -device as well as the video4linux device. +It can be accessed through \texttt{/dev/dvb/adapter0/video0}. +Data types and and ioctl definitions can be accessed by including +\texttt{linux/dvb/video.h} in your application. + + +Note that the DVB video device only controls decoding of the MPEG +video stream, not its presentation on the TV or computer screen. +On PCs this is typically handled by an associated video4linux device, e.g. +\texttt{/dev/video}, which allows scaling and defining output windows. + +Some DVB cards don't have their own MPEG decoder, which results in the omission +of the audio and video device as well as the video4linux device. + +The ioctls that deal with SPUs (sub picture units) and navigation +packets are only supported on some MPEG decoders made for DVD playback. + \devsubsec{Video Data Types} @@ -17,7 +28,7 @@ The \texttt{video\_format\_t} data type defined by typedef enum { VIDEO_FORMAT_4_3, VIDEO_FORMAT_16_9 -} video\_format_t; +} video_format_t; \end{verbatim} is used in the VIDEO\_SET\_FORMAT function (\ref{videosetformat}) to tell the driver which aspect ratio the output hardware (e.g. TV) has. @@ -26,7 +37,7 @@ returned by VIDEO\_GET\_STATUS (\ref{videogetstatus}) and video\_event (\ref{videoevent}) returned by VIDEO\_GET\_EVENT (\ref{videogetevent}) which report about the display format of the current video stream. -\devsubsubsec{videoDisplayFormat\_t} +\devsubsubsec{video\_display\_format\_t} \label{videodispformat} In case the display format of the video stream and of the @@ -39,7 +50,7 @@ typedef enum { VIDEO_PAN_SCAN, VIDEO_LETTER_BOX, VIDEO_CENTER_CUT_OUT -} video\_displayformat_t; +} video_display_format_t; \end{verbatim} as argument. @@ -53,7 +64,7 @@ replaying from an internal (demuxer) or external (user write) source. typedef enum { VIDEO_SOURCE_DEMUX, VIDEO_SOURCE_MEMORY -} video\_stream\_source_t; +} video_stream_source_t; \end{verbatim} VIDEO\_SOURCE\_DEMUX selects the demultiplexer (fed either by the frontend or the DVR device) as the source of @@ -71,35 +82,35 @@ typedef enum { VIDEO_STOPPED, VIDEO_PLAYING, VIDEO_FREEZED -} video\_play\_state_t; +} video_play_state_t; \end{verbatim} -\devsubsubsec{video event} +\devsubsubsec{struct video\_event} \label{videoevent} The following is the structure of a video event as it is returned by the VIDEO\_GET\_EVENT call. \begin{verbatim} -struct video\_event { +struct video_event { int32_t type; time_t timestamp; union { - video\_format_t video\_format; + video_format_t video_format; } u; }; \end{verbatim} -\devsubsubsec{video status} +\devsubsubsec{struct video\_status} \label{videostatus} The VIDEO\_GET\_STATUS call returns the following structure informing about various states of the playback operation. \begin{verbatim} -struct video\_status { - boolean video\_blank; - video\_play\_state_t play\_state; - video\_stream\_source_t stream\_source; - video\_format_t video\_format; - video\_displayformat_t display\_format; +struct video_status { + boolean video_blank; + video_play_state_t play_state; + video_stream_source_t stream_source; + video_format_t video_format; + video_displayformat_t display_format; }; \end{verbatim} If video\_blank is set video will be blanked out if the channel is changed or @@ -113,13 +124,13 @@ Finally, display\_format corresponds to the selected cropping mode in case the source video format is not the same as the format of the output device. -\devsubsubsec{video display still picture} +\devsubsubsec{struct video\_still\_picture} \label{videostill} An I-frame displayed via the VIDEO\_STILLPICTURE call is passed on within the following structure. \begin{verbatim} /* pointer to and size of a single iframe in memory */ -struct video\_still\_picture { +struct video_still_picture { char *iFrame; int32_t size; }; @@ -162,19 +173,19 @@ typedef enum { VIDEO_SYSTEM_NTSC60, VIDEO_SYSTEM_PAL60, VIDEO_SYSTEM_PALM60 -} video\_system_t; +} video_system_t; \end{verbatim} -\devsubsubsec{video highlights} +\devsubsubsec{struct video\_highlight} \label{vhilite} Calling the ioctl VIDEO\_SET\_HIGHLIGHTS posts the SPU highlight information. The call expects the following format for that information: - + \begin{verbatim} typedef -struct video\_highlight { +struct video_highlight { boolean active; /* 1=show highlight, 0=hide highlight */ uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ /* 3- 0 Background pixel contrast */ @@ -190,7 +201,7 @@ struct video\_highlight { uint32_t xpos; /* 23-22 button color number */ /* 21-12 start x */ /* 9- 0 end x */ -} video\_highlight_t; +} video_highlight_t; \end{verbatim} @@ -200,10 +211,10 @@ Calling VIDEO\_SET\_SPU deactivates or activates SPU decoding, according to the following format: \begin{verbatim} typedef -struct video\_spu { +struct video_spu { boolean active; - int stream\_id; -} video\_spu\_t; + int stream_id; +} video_spu_t; \end{verbatim} @@ -212,10 +223,10 @@ struct video\_spu { The following structure is used to set the SPU palette by calling VIDEO\_SPU\_PALETTE: \begin{verbatim} typedef -struct video\_spu\_palette{ /* SPU Palette information */ +struct video_spu_palette{ int length; uint8_t *palette; -} video\_spu\_palette_t; +} video_spu_palette_t; \end{verbatim} \devsubsubsec{video NAVI pack} @@ -224,10 +235,10 @@ In order to get the navigational data the following structure has to be passed to the ioctl VIDEO\_GET\_NAVI: \begin{verbatim} typedef -struct video\_navi\_pack{ - int length; /* 0 ... 1024 */ +struct video_navi_pack{ + int length; /* 0 ... 1024 */ uint8_t data[1024]; -} video\_navi\_pack_t; +} video_navi_pack_t; \end{verbatim} @@ -235,7 +246,7 @@ struct video\_navi\_pack{ \label{vattrib} The following attributes can be set by a call to VIDEO\_SET\_ATTRIBUTES: \begin{verbatim} -typedef uint16_t video\_attributes_t; +typedef uint16_t video_attributes_t; /* bits: descr. */ /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ /* 13-12 TV system (0=525/60, 1=625/50) */ @@ -255,7 +266,7 @@ typedef uint16_t video\_attributes_t; \function{open()}{ int open(const char *deviceName, int flags);}{ - This system call opens a named video device (e.g. /dev/ost/video) + This system call opens a named video device (e.g. /dev/dvb/adapter0/video0) for subsequent use. When an open() call has succeeded, the device will be ready for use. @@ -376,7 +387,7 @@ EINTERNAL & Internal error, possibly in the communication with \ifunction{VIDEO\_SELECT\_SOURCE}{ - int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, videoStreamSource\_t source);}{ + int ioctl(fd, int request = VIDEO\_SELECT\_SOURCE, video\_stream\_source\_t source);}{ This ioctl call informs the video device which source shall be used for the input data. The possible sources are demux or memory. If memory is selected, the data is fed to the video device through @@ -384,7 +395,7 @@ EINTERNAL & Internal error, possibly in the communication with }{ 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.\\ + video\_stream\_source\_t source&Indicates which source shall be used for the Video stream.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINTERNAL & Internal error, possibly in the communication with the DVB subsystem.\\ @@ -446,13 +457,13 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_DISPLAY\_FORMAT}{ \label{videosetdisplayformat} - int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, videoDisplayFormat\_t format);}{ + int ioctl(fd, int request = VIDEO\_SET\_DISPLAY\_FORMAT, video\_display\_format\_t format);}{ This ioctl call asks the Video Device to select the video format to be applied by the MPEG chip on the video. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_DISPLAY\_FORMAT for this command.\\ - videoDisplayFormat\_t format & Selects the video format to be used.\\ + video\_display\_format\_t format & Selects the video format to be used.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINTERNAL & Internal error.\\ @@ -578,7 +589,7 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_SYSTEM}{ \label{videosetsystem} - int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , videoSystem\_t system); + int ioctl(fd, int request = VIDEO\_SET\_SYSTEM , video\_system\_t system); }{ This ioctl sets the television output format. The format (see section \ref{videosys}) may vary from the color format of the displayed MPEG @@ -587,7 +598,7 @@ EOVERFLOW & \\ }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_FORMAT for this command.\\ - videoSystem\_t system& video system of TV output.\\ + video\_system\_t system& video system of TV output.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& system is not a valid or supported video system.\\ @@ -663,7 +674,7 @@ EOVERFLOW & \\ \ifunction{VIDEO\_SET\_ATTRIBUTES}{ \label{videosetattributes} - int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,videoAttributes\_t + int ioctl(fd, int request = VIDEO\_SET\_ATTRIBUTE ,video\_attributes\_t vattr) }{ This ioctl is intended for DVD playback and allows you to set @@ -673,7 +684,7 @@ EOVERFLOW & \\ }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals VIDEO\_SET\_ATTRIBUTE for this command.\\ - videoAttributes\_t vattr& video attributes according to section \ref{vattrib}.\\ + video\_attributes\_t vattr& video attributes according to section \ref{vattrib}.\\ }{ EBADF& fd is not a valid open file descriptor \\ EINVAL& input is not a valid attribute setting.\\ -- cgit v1.2.3 From e2d96061a03942dabe4a4248f41c7aea300f6680 Mon Sep 17 00:00:00 2001 From: holger Date: Mon, 10 Feb 2003 11:06:51 -0200 Subject: fix some minor typos --- dvb-spec/dvbapi/frontend.tex | 57 +++++++++++++++++++++++++------------------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index bb177df1b..cbd646b93 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -7,7 +7,7 @@ Data types and and ioctl definitions can be accessed by including DVB frontends come in three varieties: DVB-S (satellite), DVB-C (cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP) is -not handled by this API. +not yet handled by this API but a future extension is possible. For DVB-S the frontend device also supports satellite equipment control (SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC) specification is available from Eutelsat \texttt{http://www.eutelsat.org/}. @@ -20,7 +20,7 @@ in which case there exists no frontend device. \devsubsubsec{frontend type} \label{frontendtype} -For historic reasons frontend types are named after the +For historical reasons frontend types are named after the type of modulation used in transmission. \begin{verbatim} @@ -117,7 +117,9 @@ struct dvb_diseqc_slave_reply { \label{secvoltage} The voltage is usually used with non-DiSEqC capable LNBs to -switch the polarzation (horizontal/vertical). +switch the polarzation (horizontal/vertical). +When using DiSEqC epuipment this voltage has to be switched consistently +to the DiSEqC commands as described in the DiSEqC spec. \begin{verbatim} typedef enum fe_sec_voltage { @@ -131,6 +133,8 @@ typedef enum fe_sec_voltage { The continous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the high/low band of a dual-band LNB. +When using DiSEqC epuipment this voltage has to be switched consistently +to the DiSEqC commands as described in the DiSEqC spec. \begin{verbatim} typedef enum fe_sec_tone_mode { @@ -144,6 +148,8 @@ typedef enum fe_sec_tone_mode { The 22KHz tone burst is usually used with non-DiSEqC capable switches to select between two connected LNBs/satellites. +When using DiSEqC epuipment this voltage has to be switched consistently +to the DiSEqC commands as described in the DiSEqC spec. \begin{verbatim} typedef enum fe_sec_mini_cmd { @@ -193,14 +199,15 @@ struct dvb_frontend_parameters { }; \end{verbatim} -For satellite QPSK frontends you have to use QPSKParameters defined by +For satellite QPSK frontends you have to use the \verb|QPSKParameters| member +defined by \begin{verbatim} struct dvb_qpsk_parameters { uint32_t symbol_rate; /* symbol rate in Symbols per second */ fe_code_rate_t fec_inner; /* forward error correction (see above) */ }; \end{verbatim} -for cable QAM frontend you use the QAMParameters structure +for cable QAM frontend you use the \verb|QAMParameters| structure \begin{verbatim} struct dvb_qam_parameters { uint32_t symbol_rate; /* symbol rate in Symbols per second */ @@ -208,7 +215,7 @@ struct dvb_qam_parameters { fe_modulation_t modulation; /* modulation type (see above) */ }; \end{verbatim} -DVB-T frontends are supported by the OFDMParamters structure +DVB-T frontends are supported by the \verb|OFDMParamters| structure \begin{verbatim} struct dvb_ofdm_parameters { fe_bandwidth_t bandwidth; @@ -221,9 +228,9 @@ struct dvb_ofdm_parameters { }; \end{verbatim} -In the case of QPSK frontends the Frequency field specifies the intermediate -frequency, i.e. the offset which is effectively added to the local oscillator -frequency (LOF) of the LNB. +In the case of QPSK frontends the \verb|Frequency| field specifies the +intermediate frequency, i.e. the offset which is effectively added to the +local oscillator frequency (LOF) of the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and OFDM frontends the Frequency specifies the absolute frequency and is given in Hz. @@ -237,11 +244,11 @@ typedef enum fe_spectral_inversion { } fe_spectral_inversion_t; \end{verbatim} It indicates if spectral inversion should be presumed or not. -In the automatic setting (\verb INVERSION\_AUTO) the hardware will +In the automatic setting (\verb|INVERSION_AUTO|) the hardware will try to figure out the correct setting by itself. \noindent -The possible values for the FEC\_inner field are +The possible values for the \verb|FEC_inner| field are \begin{verbatim} typedef enum fe_code_rate { FEC_NONE = 0, @@ -256,7 +263,7 @@ typedef enum fe_code_rate { FEC_AUTO } fe_code_rate_t; \end{verbatim} -which correspond to error correction rates of $1\over 2$, $2\over 3$, etc., +which correspond to error correction rates of $1/2$, $2/3$, etc., no error correction or auto detection. \noindent @@ -546,15 +553,16 @@ by the driver so far. EFAULT& info points to invalid address.\\ } -\ifunction{FE\_DISEC\_RESET\_OVERLOAD}{ - int ioctl(int fd, int request = FE\_DISEC\_RESET\_OVERLOAD);}{ +\ifunction{FE\_DISEQC\_RESET\_OVERLOAD}{ + int ioctl(int fd, int request = FE\_DISEQC\_RESET\_OVERLOAD);}{ If the bus has been automatically powered off due to power overload, this ioctl call restores the power to the bus. The call requires read/write access to the device. This call has no effect if the device is manually powered off. + Not all DVB adapters support this ioctl. }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_DISEC\_RESET\_OVERLOAD for this command.\\ + int request & Equals FE\_DISEQC\_RESET\_OVERLOAD for this command.\\ }{ EBADF & fd is not a valid file descriptor.\\ EPERM & Permission denied (needs read/write access).\\ @@ -562,12 +570,12 @@ by the driver so far. } -\ifunction{FE\_DISEC\_SEND\_MASTER\_CMD}{ -int ioctl(int fd, int request = FE\_DISEC\_SEND\_MASTER\_CMD, struct dvb\_diseqc\_master\_cmd *cmd);}{ +\ifunction{FE\_DISEQC\_SEND\_MASTER\_CMD}{ +int ioctl(int fd, int request = FE\_DISEQC\_SEND\_MASTER\_CMD, struct dvb\_diseqc\_master\_cmd *cmd);}{ This ioctl call is used to send a a DiSEqC command.\\ }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_DISEC\_SEND\_MASTER\_CMD for this command.\\ + int request & Equals FE\_DISEQC\_SEND\_MASTER\_CMD for this command.\\ struct dvb\_diseqc\_master\_cmd *cmd & Pointer to the command to be transmitted.\\ }{ EBADF & fd is not a valid file descriptor.\\ @@ -577,12 +585,12 @@ int ioctl(int fd, int request = FE\_DISEC\_SEND\_MASTER\_CMD, struct dvb\_diseqc EINTERNAL & Internal error in the device driver.\\ } -\ifunction{FE\_DISEC\_RECV\_SLAVE\_REPLY}{ -int ioctl(int fd, int request = FE\_DISEC\_RECV\_SLAVE\_REPLY, struct dvb\_diseqc\_slave\_reply *reply);}{ +\ifunction{FE\_DISEQC\_RECV\_SLAVE\_REPLY}{ +int ioctl(int fd, int request = FE\_DISEQC\_RECV\_SLAVE\_REPLY, struct dvb\_diseqc\_slave\_reply *reply);}{ This ioctl call is used to receive reply to a DiSEqC 2.0 command.\\ }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_DISEC\_RECV\_SLAVE\_REPLY for this command.\\ + int request & Equals FE\_DISEQC\_RECV\_SLAVE\_REPLY for this command.\\ struct dvb\_diseqc\_slave\_reply *reply & Pointer to the command to be received.\\ }{ EBADF & fd is not a valid file descriptor.\\ @@ -592,12 +600,12 @@ This ioctl call is used to receive reply to a DiSEqC 2.0 command.\\ EINTERNAL & Internal error in the device driver.\\ } -\ifunction{FE\_DISEC\_SEND\_BURST}{ -int ioctl(int fd, int request = FE\_DISEC\_SEND\_BURST, fe\_sec\_mini\_cmd\_t burst);}{ +\ifunction{FE\_DISEQC\_SEND\_BURST}{ +int ioctl(int fd, int request = FE\_DISEQC\_SEND\_BURST, fe\_sec\_mini\_cmd\_t burst);}{ This ioctl call is used to send a 22KHz tone burst.\\ }{ int fd & File descriptor returned by a previous call to open().\\ - int request & Equals FE\_DISEC\_SEND\_BURST for this command.\\ + int request & Equals FE\_DISEQC\_SEND\_BURST for this command.\\ fe\_sec\_mini\_cmd\_t burst & burst A or B.\\ }{ EBADF & fd is not a valid file descriptor.\\ @@ -646,6 +654,7 @@ int ioctl(int fd, int request = FE\_ENABLE\_HIGH\_LNB\_VOLTAGE, int high);}{ If high != 0 enables slightly higher voltages instead of 13/18V (to compensate for long cables). This call requires read/write permissions. +Not all DVB adapters support this ioctl. }{ int fd & File descriptor returned by a previous call to open().\\ int request & Equals FE\_SET\_VOLTAGE for this command.\\ -- cgit v1.2.3 From f005fb88fdf382126eb5e52a0910b5d60f750d5d Mon Sep 17 00:00:00 2001 From: oberritter Date: Mon, 3 Mar 2003 02:31:56 -0300 Subject: updated valgrind patch to version 1.0.4 and added checks for audio-, ca-, net-, osd- and video ioctl()s. note that NET_REMOVE_IF and VIDEO_SET_ATTRIBUTES both are _IO('o', 53), so VIDEO_SET_ATTRIBUTES can not checked. --- dvb-spec/valgrind-1.0.4.diff | 353 ++++++++++++++++++++++++++++++++++++ dvb-spec/valgrind-1.0pre3-dvb.patch | 154 ---------------- 2 files changed, 353 insertions(+), 154 deletions(-) create mode 100644 dvb-spec/valgrind-1.0.4.diff delete mode 100644 dvb-spec/valgrind-1.0pre3-dvb.patch diff --git a/dvb-spec/valgrind-1.0.4.diff b/dvb-spec/valgrind-1.0.4.diff new file mode 100644 index 000000000..20ddcc956 --- /dev/null +++ b/dvb-spec/valgrind-1.0.4.diff @@ -0,0 +1,353 @@ +diff -Naur valgrind-1.0.4.orig/vg_syscall_mem.c valgrind-1.0.4/vg_syscall_mem.c +--- valgrind-1.0.4.orig/vg_syscall_mem.c 2002-10-13 17:04:49.000000000 +0200 ++++ valgrind-1.0.4/vg_syscall_mem.c 2003-03-03 06:17:15.000000000 +0100 +@@ -2323,6 +2323,332 @@ + sizeof(struct cdrom_msf)); + KERNEL_DO_SYSCALL(tid,res); + break; ++ ++ /* DVB (Digital Video Broadcasting) related stuff ++ * http://www.linuxtv.org ++ */ ++ case AUDIO_STOP: ++ case AUDIO_PLAY: ++ case AUDIO_PAUSE: ++ case AUDIO_CONTINUE: ++ case AUDIO_SELECT_SOURCE: ++ case AUDIO_SET_MUTE: ++ case AUDIO_SET_AV_SYNC: ++ case AUDIO_SET_BYPASS_MODE: ++ case AUDIO_CHANNEL_SELECT: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_GET_STATUS: ++ must_be_writable(tst, "ioctl(AUDIO_GET_STATUS)", arg3, ++ sizeof(audio_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(audio_status_t)); ++ break; ++ case AUDIO_GET_CAPABILITIES: ++ must_be_writable(tst, "ioctl(AUDIO_GET_CAPABILITIES)", arg3, ++ sizeof(unsigned int)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(unsigned int)); ++ break; ++ case AUDIO_CLEAR_BUFFER: ++ case AUDIO_SET_ID: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_MIXER: ++ must_be_readable(tst, "ioctl(AUDIO_SET_MIXER)", arg3, ++ sizeof(audio_mixer_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_STREAMTYPE: ++ case AUDIO_SET_EXT_ID: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_ATTRIBUTES: ++ must_be_readable(tst, "ioctl(AUDIO_SET_ATTRIBUTES)", arg3, ++ sizeof(audio_attributes_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_KARAOKE: ++ must_be_readable(tst, "ioctl(AUDIO_SET_KARAOKE)", arg3, ++ sizeof(audio_karaoke_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_RESET: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_GET_CAP: ++ must_be_writable(tst, "ioctl(CA_GET_CAP)", arg3, ++ sizeof(ca_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(ca_caps_t)); ++ break; ++ case CA_GET_SLOT_INFO: ++ must_be_writable(tst, "ioctl(CA_GET_SLOT_INFO)", arg3, ++ sizeof(ca_slot_info_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(ca_slot_info_t)); ++ break; ++ case CA_GET_DESCR_INFO: ++ must_be_writable(tst, "ioctl(CA_GET_DESCR_INFO)", arg3, ++ sizeof(ca_descr_info_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(ca_descr_info_t)); ++ break; ++ case CA_GET_MSG: ++ must_be_writable(tst, "ioctl(CA_GET_MSG)", arg3, ++ sizeof(ca_msg_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(ca_msg_t)); ++ break; ++ case CA_SEND_MSG: ++ must_be_readable(tst, "ioctl(CA_SEND_MSG)", arg3, ++ sizeof(ca_msg_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_SET_DESCR: ++ must_be_readable(tst, "ioctl(CA_SET_DESCR)", arg3, ++ sizeof(ca_descr_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_SET_PID: ++ must_be_readable(tst, "ioctl(CA_SET_PID)", arg3, ++ sizeof(ca_pid_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_START: ++ case DMX_STOP: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_FILTER: ++ must_be_readable(tst, "ioctl(DMX_SET_FILTER)", arg3, ++ sizeof(struct dmx_sct_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_PES_FILTER: ++ must_be_readable(tst, "ioctl(DMX_SET_PES_FILTER)", arg3, ++ sizeof(struct dmx_pes_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_BUFFER_SIZE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_GET_EVENT: ++ must_be_writable(tst, "ioctl(DMX_GET_EVENT)", arg3, ++ sizeof(struct dmx_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dmx_event)); ++ break; ++ case DMX_GET_PES_PIDS: ++ must_be_writable(tst, "ioctl(DMX_GET_PES_PIDS)", arg3, ++ 5*sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, 5*sizeof(uint16_t)); ++ break; ++ case DMX_GET_CAPS: ++ must_be_writable(tst, "ioctl(DMX_GET_CAPS)", arg3, ++ sizeof(dmx_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(dmx_caps_t)); ++ break; ++ case DMX_SET_SOURCE: ++ must_be_readable(tst, "ioctl(DMX_SET_SOURCE)", arg3, ++ sizeof(dmx_source_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_INFO: ++ must_be_writable(tst, "ioctl(FE_GET_INFO)", arg3, ++ sizeof(struct dvb_frontend_info)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_frontend_info)); ++ break; ++ case FE_DISEQC_RESET_OVERLOAD: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_SEND_MASTER_CMD: ++ must_be_readable(tst, "ioctl(FE_DISEQC_SEND_MASTER_CMD)", arg3, ++ sizeof(struct dvb_diseqc_master_cmd)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_RECV_SLAVE_REPLY: ++ must_be_writable(tst, "ioctl(FE_DISEQC_RECV_SLAVE_REPLY)", arg3, ++ sizeof(struct dvb_diseqc_slave_reply)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_diseqc_slave_reply)); ++ break; ++ case FE_DISEQC_SEND_BURST: ++ case FE_SET_TONE: ++ case FE_SET_VOLTAGE: ++ case FE_ENABLE_HIGH_LNB_VOLTAGE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_READ_STATUS: ++ must_be_writable(tst, "ioctl(FE_READ_STATUS)", arg3, ++ sizeof(fe_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(fe_status_t)); ++ break; ++ case FE_READ_BER: ++ must_be_writable(tst, "ioctl(FE_READ_BER)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint32_t)); ++ break; ++ case FE_READ_SIGNAL_STRENGTH: ++ must_be_writable(tst, "ioctl(FE_READ_SIGNAL_STRENGTH)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_SNR: ++ must_be_writable(tst, "ioctl(FE_READ_SNR)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_UNCORRECTED_BLOCKS: ++ must_be_writable(tst, "ioctl(FE_READ_UNCORRECTED_BLOCKS)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(uint32_t)); ++ break; ++ case FE_SET_FRONTEND: ++ must_be_readable(tst, "ioctl(FE_SET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_FRONTEND: ++ must_be_writable(tst, "ioctl(FE_GET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_frontend_parameters)); ++ break; ++ case FE_GET_EVENT: ++ must_be_writable(tst, "ioctl(FE_GET_EVENT)", arg3, ++ sizeof(struct dvb_frontend_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_frontend_event)); ++ break; ++ case NET_ADD_IF: ++ must_be_readable(tst, "ioctl(NET_ADD_IF)", arg3, ++ sizeof(struct dvb_net_if)); ++ must_be_writable(tst, "ioctl(NET_ADD_IF)", arg3, ++ sizeof(struct dvb_net_if)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_net_if)); ++ break; ++ case NET_REMOVE_IF: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case NET_GET_IF: ++ must_be_readable(tst, "ioctl(NET_GET_IF)", arg3, ++ sizeof(struct dvb_net_if)); ++ must_be_writable(tst, "ioctl(NET_GET_IF)", arg3, ++ sizeof(struct dvb_net_if)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct dvb_net_if)); ++ break; ++ case OSD_SEND_CMD: ++ must_be_readable(tst, "ioctl(OSD_SEND_CMD)", arg3, ++ sizeof(osd_cmd_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_STOP: ++ case VIDEO_PLAY: ++ case VIDEO_FREEZE: ++ case VIDEO_CONTINUE: ++ case VIDEO_SELECT_SOURCE: ++ case VIDEO_SET_BLANK: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_STATUS: ++ must_be_writable(tst, "ioctl(VIDEO_GET_STATUS)", arg3, ++ sizeof(struct video_status)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct video_status)); ++ break; ++ case VIDEO_GET_EVENT: ++ must_be_writable(tst, "ioctl(VIDEO_GET_EVENT)", arg3, ++ sizeof(struct video_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(struct video_event)); ++ break; ++ case VIDEO_SET_DISPLAY_FORMAT: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_STILLPICTURE: ++ must_be_readable(tst, "ioctl(VIDEO_STILLPICTURE)", arg3, ++ sizeof(struct video_still_picture)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_FAST_FORWARD: ++ case VIDEO_SLOWMOTION: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_CAPABILITIES: ++ must_be_writable(tst, "ioctl(VIDEO_GET_CAPABILITIES)", arg3, ++ sizeof(unsigned int)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(unsigned int)); ++ break; ++ case VIDEO_CLEAR_BUFFER: ++ case VIDEO_SET_ID: ++ case VIDEO_SET_STREAMTYPE: ++ case VIDEO_SET_FORMAT: ++ case VIDEO_SET_SYSTEM: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_HIGHLIGHT: ++ must_be_readable(tst, "ioctl(VIDEO_SET_HIGHLIGHT)", arg3, ++ sizeof(video_highlight_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_SPU: ++ must_be_readable(tst, "ioctl(VIDEO_SET_SPU)", arg3, ++ sizeof(video_spu_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_SPU_PALETTE: ++ must_be_readable(tst, "ioctl(VIDEO_SET_SPU_PALETTE)", arg3, ++ sizeof(video_spu_palette_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_NAVI: ++ must_be_writable(tst, "ioctl(VIDEO_GET_NAVI)", arg3, ++ sizeof(video_navi_pack_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ make_readable (arg3, sizeof(video_navi_pack_t)); ++ break; ++#if 0 ++ /* FIXME: conflicts with NET_REMOVE_IF - both are _IO('o', 53) */ ++ case VIDEO_SET_ATTRIBUTES: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++#endif ++ + /* We don't have any specific information on it, so + try to do something reasonable based on direction and + size bits. The encoding scheme is described in +diff -Naur valgrind-1.0.4.orig/vg_unsafe.h valgrind-1.0.4/vg_unsafe.h +--- valgrind-1.0.4.orig/vg_unsafe.h 2002-09-17 16:31:08.000000000 +0200 ++++ valgrind-1.0.4/vg_unsafe.h 2003-03-03 06:12:23.000000000 +0100 +@@ -86,6 +86,13 @@ + + #include + ++#include ++#include ++#include ++#include ++#include ++#include ++#include + + /*--------------------------------------------------------------------*/ + /*--- end vg_unsafe.h ---*/ diff --git a/dvb-spec/valgrind-1.0pre3-dvb.patch b/dvb-spec/valgrind-1.0pre3-dvb.patch deleted file mode 100644 index 173aaecc5..000000000 --- a/dvb-spec/valgrind-1.0pre3-dvb.patch +++ /dev/null @@ -1,154 +0,0 @@ -diff -ur valgrind-1.0pre3.orig/vg_syscall_mem.c valgrind-1.0pre3/vg_syscall_mem.c ---- valgrind-1.0pre3.orig/vg_syscall_mem.c Thu Jun 20 09:23:49 2002 -+++ valgrind-1.0pre3/vg_syscall_mem.c Mon Jul 8 19:55:45 2002 -@@ -2038,6 +2038,136 @@ - sizeof(struct cdrom_msf)); - KERNEL_DO_SYSCALL(tid,res); - break; -+ -+ /* DVB (Digital Video Broadcasting) related stuff -+ * http://www.linuxtv.org -+ */ -+ case FE_GET_INFO: -+ must_be_writable(tst, "ioctl(FE_GET_INFO)", arg3, -+ sizeof(struct dvb_frontend_info)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(struct dvb_frontend_info)); -+ break; -+ case FE_DISEQC_RESET_OVERLOAD: -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case FE_DISEQC_SEND_MASTER_CMD: -+ must_be_readable(tst, "ioctl(FE_DISEQC_SEND_MASTER_CMD)", arg3, -+ sizeof(struct dvb_diseqc_master_cmd)); -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case FE_DISEQC_RECV_SLAVE_REPLY: -+ must_be_writable(tst, "ioctl(FE_DISEQC_RECV_SLAVE_REPLY)", arg3, -+ sizeof(struct dvb_diseqc_slave_reply)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(struct dvb_diseqc_slave_reply)); -+ break; -+ case FE_DISEQC_SEND_BURST: -+ case FE_SET_TONE: -+ case FE_SET_VOLTAGE: -+ case FE_ENABLE_HIGH_LNB_VOLTAGE: -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case FE_READ_STATUS: -+ must_be_writable(tst, "ioctl(FE_READ_STATUS)", arg3, -+ sizeof(fe_status_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(fe_status_t)); -+ break; -+ case FE_READ_BER: -+ must_be_writable(tst, "ioctl(FE_READ_BER)", arg3, -+ sizeof(uint32_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(uint32_t)); -+ break; -+ case FE_READ_SIGNAL_STRENGTH: -+ must_be_writable(tst, "ioctl(FE_READ_SIGNAL_STRENGTH)", arg3, -+ sizeof(uint16_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(uint16_t)); -+ break; -+ case FE_READ_SNR: -+ must_be_writable(tst, "ioctl(FE_READ_SNR)", arg3, -+ sizeof(uint16_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(uint16_t)); -+ break; -+ case FE_READ_UNCORRECTED_BLOCKS: -+ must_be_writable(tst, "ioctl(FE_READ_UNCORRECTED_BLOCKS)", arg3, -+ sizeof(uint32_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(uint32_t)); -+ break; -+ case FE_SET_FRONTEND: -+ must_be_readable(tst, "ioctl(FE_SET_FRONTEND)", arg3, -+ sizeof(struct dvb_frontend_parameters)); -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case FE_GET_FRONTEND: -+ must_be_writable(tst, "ioctl(FE_GET_FRONTEND)", arg3, -+ sizeof(struct dvb_frontend_parameters)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(struct dvb_frontend_parameters)); -+ break; -+ case FE_GET_EVENT: -+ must_be_writable(tst, "ioctl(FE_GET_EVENT)", arg3, -+ sizeof(struct dvb_frontend_event)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(struct dvb_frontend_event)); -+ break; -+ case DMX_START: -+ case DMX_STOP: -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case DMX_SET_FILTER: -+ must_be_readable(tst, "ioctl(DMX_SET_FILTER)", arg3, -+ sizeof(struct dmx_sct_filter_params)); -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case DMX_SET_PES_FILTER: -+ must_be_readable(tst, "ioctl(DMX_SET_PES_FILTER)", arg3, -+ sizeof(struct dmx_pes_filter_params)); -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case DMX_SET_BUFFER_SIZE: -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ case DMX_GET_EVENT: -+ must_be_writable(tst, "ioctl(DMX_GET_EVENT)", arg3, -+ sizeof(struct dmx_event)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(struct dmx_event)); -+ break; -+ case DMX_GET_PES_PIDS: -+ must_be_writable(tst, "ioctl(DMX_GET_PES_PIDS)", arg3, -+ 5*sizeof(uint16_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, 5*sizeof(uint16_t)); -+ break; -+ case DMX_GET_CAPS: -+ must_be_writable(tst, "ioctl(DMX_GET_CAPS)", arg3, -+ sizeof(dmx_caps_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ if (!VG_(is_kerror)(res) && res == 0) -+ make_readable (arg3, sizeof(dmx_caps_t)); -+ break; -+ case DMX_SET_SOURCE: -+ must_be_readable(tst, "ioctl(DMX_SET_SOURCE)", arg3, -+ sizeof(dmx_source_t)); -+ KERNEL_DO_SYSCALL(tid,res); -+ break; -+ - /* We don't have any specific information on it, so - try to do something reasonable based on direction and - size bits. The encoding scheme is described in -diff -ur valgrind-1.0pre3.orig/vg_unsafe.h valgrind-1.0pre3/vg_unsafe.h ---- valgrind-1.0pre3.orig/vg_unsafe.h Thu Jun 13 18:02:37 2002 -+++ valgrind-1.0pre3/vg_unsafe.h Mon Jul 8 19:56:20 2002 -@@ -85,6 +85,10 @@ - - #include - -+#include -+#include -+#include -+#include - - /*--------------------------------------------------------------------*/ - /*--- end vg_unsafe.h ---*/ -- cgit v1.2.3 From 0c835747fef0c13496f773a754bf557183734387 Mon Sep 17 00:00:00 2001 From: oberritter Date: Mon, 3 Mar 2003 03:42:29 -0300 Subject: fixed NET_ADD_IF/NET_GET_IF which are _IOWR and added diff for valgrind version 1.9.4 --- dvb-spec/valgrind-1.0.4.diff | 24 +-- dvb-spec/valgrind-1.9.4.diff | 356 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 370 insertions(+), 10 deletions(-) create mode 100644 dvb-spec/valgrind-1.9.4.diff diff --git a/dvb-spec/valgrind-1.0.4.diff b/dvb-spec/valgrind-1.0.4.diff index 20ddcc956..0e77afe14 100644 --- a/dvb-spec/valgrind-1.0.4.diff +++ b/dvb-spec/valgrind-1.0.4.diff @@ -1,7 +1,7 @@ diff -Naur valgrind-1.0.4.orig/vg_syscall_mem.c valgrind-1.0.4/vg_syscall_mem.c --- valgrind-1.0.4.orig/vg_syscall_mem.c 2002-10-13 17:04:49.000000000 +0200 -+++ valgrind-1.0.4/vg_syscall_mem.c 2003-03-03 06:17:15.000000000 +0100 -@@ -2323,6 +2323,332 @@ ++++ valgrind-1.0.4/vg_syscall_mem.c 2003-03-03 07:34:50.000000000 +0100 +@@ -2323,6 +2323,336 @@ sizeof(struct cdrom_msf)); KERNEL_DO_SYSCALL(tid,res); break; @@ -229,10 +229,12 @@ diff -Naur valgrind-1.0.4.orig/vg_syscall_mem.c valgrind-1.0.4/vg_syscall_mem.c + make_readable (arg3, sizeof(struct dvb_frontend_event)); + break; + case NET_ADD_IF: -+ must_be_readable(tst, "ioctl(NET_ADD_IF)", arg3, -+ sizeof(struct dvb_net_if)); -+ must_be_writable(tst, "ioctl(NET_ADD_IF)", arg3, -+ sizeof(struct dvb_net_if)); ++ must_be_readable(tst, "ioctl(NET_ADD_IF (pid, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->pid), ++ sizeof(((struct dvb_net_if *) arg3)->pid)); ++ must_be_writable(tst, "ioctl(NET_ADD_IF (if_num, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->if_num), ++ sizeof(((struct dvb_net_if *) arg3)->if_num)); + KERNEL_DO_SYSCALL(tid,res); + if (!VG_(is_kerror)(res) && res == 0) + make_readable (arg3, sizeof(struct dvb_net_if)); @@ -241,10 +243,12 @@ diff -Naur valgrind-1.0.4.orig/vg_syscall_mem.c valgrind-1.0.4/vg_syscall_mem.c + KERNEL_DO_SYSCALL(tid,res); + break; + case NET_GET_IF: -+ must_be_readable(tst, "ioctl(NET_GET_IF)", arg3, -+ sizeof(struct dvb_net_if)); -+ must_be_writable(tst, "ioctl(NET_GET_IF)", arg3, -+ sizeof(struct dvb_net_if)); ++ must_be_readable(tst, "ioctl(NET_GET_IF (if_num, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->if_num), ++ sizeof(((struct dvb_net_if *) arg3)->if_num)); ++ must_be_writable(tst, "ioctl(NET_GET_IF (pid, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->pid), ++ sizeof(((struct dvb_net_if *) arg3)->pid)); + KERNEL_DO_SYSCALL(tid,res); + if (!VG_(is_kerror)(res) && res == 0) + make_readable (arg3, sizeof(struct dvb_net_if)); diff --git a/dvb-spec/valgrind-1.9.4.diff b/dvb-spec/valgrind-1.9.4.diff new file mode 100644 index 000000000..bcc9de6ea --- /dev/null +++ b/dvb-spec/valgrind-1.9.4.diff @@ -0,0 +1,356 @@ +diff -Naur valgrind-1.9.4.orig/coregrind/vg_syscalls.c valgrind-1.9.4/coregrind/vg_syscalls.c +--- valgrind-1.9.4.orig/coregrind/vg_syscalls.c 2003-02-24 22:58:01.000000000 +0100 ++++ valgrind-1.9.4/coregrind/vg_syscalls.c 2003-03-03 07:25:43.000000000 +0100 +@@ -2365,6 +2365,335 @@ + KERNEL_DO_SYSCALL(tid,res); + break; + ++ /* DVB (Digital Video Broadcasting) related stuff ++ * http://www.linuxtv.org ++ */ ++ case AUDIO_STOP: ++ case AUDIO_PLAY: ++ case AUDIO_PAUSE: ++ case AUDIO_CONTINUE: ++ case AUDIO_SELECT_SOURCE: ++ case AUDIO_SET_MUTE: ++ case AUDIO_SET_AV_SYNC: ++ case AUDIO_SET_BYPASS_MODE: ++ case AUDIO_CHANNEL_SELECT: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_GET_STATUS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(AUDIO_GET_STATUS)", arg3, ++ sizeof(audio_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(audio_status_t)); ++ break; ++ case AUDIO_GET_CAPABILITIES: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(AUDIO_GET_CAPABILITIES)", arg3, ++ sizeof(unsigned int)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(unsigned int)); ++ break; ++ case AUDIO_CLEAR_BUFFER: ++ case AUDIO_SET_ID: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_MIXER: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(AUDIO_SET_MIXER)", arg3, ++ sizeof(audio_mixer_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_STREAMTYPE: ++ case AUDIO_SET_EXT_ID: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_ATTRIBUTES: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(AUDIO_SET_ATTRIBUTES)", arg3, ++ sizeof(audio_attributes_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_KARAOKE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(AUDIO_SET_KARAOKE)", arg3, ++ sizeof(audio_karaoke_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_RESET: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_GET_CAP: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_CAP)", arg3, ++ sizeof(ca_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_caps_t)); ++ break; ++ case CA_GET_SLOT_INFO: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_SLOT_INFO)", arg3, ++ sizeof(ca_slot_info_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_slot_info_t)); ++ break; ++ case CA_GET_DESCR_INFO: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_DESCR_INFO)", arg3, ++ sizeof(ca_descr_info_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_descr_info_t)); ++ break; ++ case CA_GET_MSG: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_MSG)", arg3, ++ sizeof(ca_msg_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_msg_t)); ++ break; ++ case CA_SEND_MSG: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(CA_SEND_MSG)", arg3, ++ sizeof(ca_msg_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_SET_DESCR: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(CA_SET_DESCR)", arg3, ++ sizeof(ca_descr_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_SET_PID: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(CA_SET_PID)", arg3, ++ sizeof(ca_pid_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_START: ++ case DMX_STOP: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_FILTER: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(DMX_SET_FILTER)", arg3, ++ sizeof(struct dmx_sct_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_PES_FILTER: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(DMX_SET_PES_FILTER)", arg3, ++ sizeof(struct dmx_pes_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_BUFFER_SIZE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_GET_EVENT: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_EVENT)", arg3, ++ sizeof(struct dmx_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dmx_event)); ++ break; ++ case DMX_GET_PES_PIDS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_PES_PIDS)", arg3, ++ 5*sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, 5*sizeof(uint16_t)); ++ break; ++ case DMX_GET_CAPS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_CAPS)", arg3, ++ sizeof(dmx_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(dmx_caps_t)); ++ break; ++ case DMX_SET_SOURCE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(DMX_SET_SOURCE)", arg3, ++ sizeof(dmx_source_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_INFO: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_GET_INFO)", arg3, ++ sizeof(struct dvb_frontend_info)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_frontend_info)); ++ break; ++ case FE_DISEQC_RESET_OVERLOAD: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_SEND_MASTER_CMD: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(FE_DISEQC_SEND_MASTER_CMD)", arg3, ++ sizeof(struct dvb_diseqc_master_cmd)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_RECV_SLAVE_REPLY: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_DISEQC_RECV_SLAVE_REPLY)", arg3, ++ sizeof(struct dvb_diseqc_slave_reply)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_diseqc_slave_reply)); ++ break; ++ case FE_DISEQC_SEND_BURST: ++ case FE_SET_TONE: ++ case FE_SET_VOLTAGE: ++ case FE_ENABLE_HIGH_LNB_VOLTAGE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_READ_STATUS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_STATUS)", arg3, ++ sizeof(fe_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(fe_status_t)); ++ break; ++ case FE_READ_BER: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_BER)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint32_t)); ++ break; ++ case FE_READ_SIGNAL_STRENGTH: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_SIGNAL_STRENGTH)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_SNR: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_SNR)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_UNCORRECTED_BLOCKS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_UNCORRECTED_BLOCKS)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint32_t)); ++ break; ++ case FE_SET_FRONTEND: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(FE_SET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_FRONTEND: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_GET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_frontend_parameters)); ++ break; ++ case FE_GET_EVENT: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_GET_EVENT)", arg3, ++ sizeof(struct dvb_frontend_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_frontend_event)); ++ break; ++ case NET_ADD_IF: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(NET_ADD_IF (pid, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->pid), ++ sizeof(((struct dvb_net_if *) arg3)->pid)); ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(NET_ADD_IF (if_num, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->if_num), ++ sizeof(((struct dvb_net_if *) arg3)->if_num)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_net_if)); ++ break; ++ case NET_REMOVE_IF: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case NET_GET_IF: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(NET_GET_IF (if_num, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->if_num), ++ sizeof(((struct dvb_net_if *) arg3)->if_num)); ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(NET_GET_IF (pid, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->pid), ++ sizeof(((struct dvb_net_if *) arg3)->pid)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_net_if)); ++ break; ++ case OSD_SEND_CMD: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(OSD_SEND_CMD)", arg3, ++ sizeof(osd_cmd_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_STOP: ++ case VIDEO_PLAY: ++ case VIDEO_FREEZE: ++ case VIDEO_CONTINUE: ++ case VIDEO_SELECT_SOURCE: ++ case VIDEO_SET_BLANK: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_STATUS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_STATUS)", arg3, ++ sizeof(struct video_status)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct video_status)); ++ break; ++ case VIDEO_GET_EVENT: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_EVENT)", arg3, ++ sizeof(struct video_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct video_event)); ++ break; ++ case VIDEO_SET_DISPLAY_FORMAT: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_STILLPICTURE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_STILLPICTURE)", arg3, ++ sizeof(struct video_still_picture)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_FAST_FORWARD: ++ case VIDEO_SLOWMOTION: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_CAPABILITIES: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_CAPABILITIES)", arg3, ++ sizeof(unsigned int)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(unsigned int)); ++ break; ++ case VIDEO_CLEAR_BUFFER: ++ case VIDEO_SET_ID: ++ case VIDEO_SET_STREAMTYPE: ++ case VIDEO_SET_FORMAT: ++ case VIDEO_SET_SYSTEM: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_HIGHLIGHT: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_SET_HIGHLIGHT)", arg3, ++ sizeof(video_highlight_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_SPU: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_SET_SPU)", arg3, ++ sizeof(video_spu_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_SPU_PALETTE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_SET_SPU_PALETTE)", arg3, ++ sizeof(video_spu_palette_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_NAVI: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_NAVI)", arg3, ++ sizeof(video_navi_pack_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(video_navi_pack_t)); ++ break; ++#if 0 ++ /* FIXME: conflicts with NET_REMOVE_IF - both are _IO('o', 53) */ ++ case VIDEO_SET_ATTRIBUTES: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++#endif ++ + /* We don't have any specific information on it, so + try to do something reasonable based on direction and + size bits. The encoding scheme is described in +diff -Naur valgrind-1.9.4.orig/coregrind/vg_unsafe.h valgrind-1.9.4/coregrind/vg_unsafe.h +--- valgrind-1.9.4.orig/coregrind/vg_unsafe.h 2002-10-05 17:18:27.000000000 +0200 ++++ valgrind-1.9.4/coregrind/vg_unsafe.h 2003-03-03 07:00:37.000000000 +0100 +@@ -86,6 +86,13 @@ + + #include + ++#include ++#include ++#include ++#include ++#include ++#include ++#include + + /*--------------------------------------------------------------------*/ + /*--- end vg_unsafe.h ---*/ -- cgit v1.2.3 From e3a855eb32a18c8a10cf2a5d35a6d8c43e06bc7f Mon Sep 17 00:00:00 2001 From: endriss Date: Sun, 4 May 2003 19:14:01 -0300 Subject: updated --- dvb-spec/README.CABLE | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/dvb-spec/README.CABLE b/dvb-spec/README.CABLE index de13af020..0a8466f6d 100644 --- a/dvb-spec/README.CABLE +++ b/dvb-spec/README.CABLE @@ -1,5 +1,5 @@ -- The analog module is not fully supported yet. - The MSP3400 module will have to be extended to handle then audio and - video switching for the module. - If you want sound you will have to remove the module for now. - +- The analog module of the DVB-C should be detected automatically. + +- If you are using a Technotrend/Hauppauge DVB-C card *without* analog module, + you might have to use module parameter adac=-1 (dvb-ttpci.o). + -- cgit v1.2.3 From 8c9b6d3513b11e6f02a76a8d2a938a547c3b6d92 Mon Sep 17 00:00:00 2001 From: js Date: Thu, 24 Jul 2003 12:57:26 -0300 Subject: rm'ed leftover from Metzler's libdvb --- dvb-spec/channel | 104 ------------------------------------------------------- 1 file changed, 104 deletions(-) delete mode 100644 dvb-spec/channel diff --git a/dvb-spec/channel b/dvb-spec/channel deleted file mode 100644 index f17e8cb19..000000000 --- a/dvb-spec/channel +++ /dev/null @@ -1,104 +0,0 @@ -This file describes the format of the new channel config file. - -Comments start with # -Each section starts with one of the identifiers: LNB, DISEQC, ROTOR, ... - -IDs are either the official transponder, network, etc. id if it exists -and is unique, otherwise it is just a consecutive number assigned by -the application. -An LNB can also describe a cable TV outlet or a terrestrial antenna. -Names (as all parameters in brackets) are optional. In this case the -application should use the ID as name. - -The application should offer selection sorted by channel number, network, -satellite, bouquet. - - -# satellite definition -SAT - ID satid # ID = xxxy, sat is at position xxx.y degrees - [NAME name] - LNBID lnbid # LNB this sat is received with - [ROTORID rotorid] # rotor commands to position it on this sat - -# LNB definition -LNB - ID lnbid - [NAME name] - [INPUT input] # input of card which the lnb is connected to (default 0) - TYPE type # LNB, CATV or terrestrial antenna? - LOF1 offset1 # local oscillator frequency 1 - LOF2 offset2 # local oscillator frequency 2 - SLOF switchfreq # switching frequency - [DISEQCNR diseqcnr] # simple 2- or 4-switch DiSEqC - [DISEQCID diseqcid] - [INPUT input] - [SWITCHID switchid] - -# A transponder definition -TRANSPONDER - ID tpid - TYPE type # digital (DVB-S(1), C(2) or T(3)) or analog(0) ? - SATID satid - [NAME name] # if analog this is the channel name - FREQ freq - POL H/V - [QAM qam] # only needed if DVB-C - [SRATE sr] # only if DVB - [FEC fec] # only if DVB - [PICID picid] # picture attributes for all channels on this transponder - -# channel definition (only if DVB) -CHANNEL - ID channelid - [NAME name] - TPID tpid - TYPE type - PNR pnr - VPID vpid - APID apid - TPID tpid - [PMTPID pmtpid] - [PCRPID pcrpid] - [APID apid2 APID apid3 ... APID apidn] # more audio PIDs for several languages - [AC3PID ac3] - [NETWID networkid] - [BOUQID bouquetid] - [PICID picid] - -# network definition -NETWORK - ID nwid - [NAME name] - -# bouquet definition -BOUQUET - ID bqid - [NAME name] - - - -# These will be implemented later - -# DiSEqC command sequence -DISEQC - ID disid - [NAME name] - MESSAGE data1 [ ... datan ] BURST 0/1 END - [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] - -# DiSEqC switch -SWITCH - ID switchid - SWITCHID switchid # next "higher" switch - [NAME name] - MESSAGE data1 [ ... datan ] BURST 0/1 END - - -# DiSEqC rotor command sequence leading to a certain rotor position -ROTOR - ID rotid - POS degrees - MESSAGE data1 [ ... datan ] BURST 0/1 END - [MESSAGE data1 [ ... datan ] BURST 0/1 END ...] - -- cgit v1.2.3 From 904b355be5e52d80295f03db1f48301d2a28628e Mon Sep 17 00:00:00 2001 From: js Date: Thu, 24 Jul 2003 13:31:30 -0300 Subject: updated for latest (1.9.6+) valgrind release, added DMX_GET_STC --- dvb-spec/valgrind-20030716.diff | 361 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 dvb-spec/valgrind-20030716.diff diff --git a/dvb-spec/valgrind-20030716.diff b/dvb-spec/valgrind-20030716.diff new file mode 100644 index 000000000..af0adc806 --- /dev/null +++ b/dvb-spec/valgrind-20030716.diff @@ -0,0 +1,361 @@ +--- valgrind-20030716/coregrind/vg_syscalls.c.orig 2003-07-05 17:44:45.000000000 +0200 ++++ valgrind-20030716/coregrind/vg_syscalls.c 2003-07-24 18:26:48.000000000 +0200 +@@ -2430,6 +2430,342 @@ void VG_(perform_assumed_nonblocking_sys + KERNEL_DO_SYSCALL(tid,res); + break; + ++ /* DVB (Digital Video Broadcasting) related stuff ++ * http://www.linuxtv.org ++ */ ++ case AUDIO_STOP: ++ case AUDIO_PLAY: ++ case AUDIO_PAUSE: ++ case AUDIO_CONTINUE: ++ case AUDIO_SELECT_SOURCE: ++ case AUDIO_SET_MUTE: ++ case AUDIO_SET_AV_SYNC: ++ case AUDIO_SET_BYPASS_MODE: ++ case AUDIO_CHANNEL_SELECT: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_GET_STATUS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(AUDIO_GET_STATUS)", arg3, ++ sizeof(audio_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(audio_status_t)); ++ break; ++ case AUDIO_GET_CAPABILITIES: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(AUDIO_GET_CAPABILITIES)", arg3, ++ sizeof(unsigned int)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(unsigned int)); ++ break; ++ case AUDIO_CLEAR_BUFFER: ++ case AUDIO_SET_ID: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_MIXER: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(AUDIO_SET_MIXER)", arg3, ++ sizeof(audio_mixer_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_STREAMTYPE: ++ case AUDIO_SET_EXT_ID: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_ATTRIBUTES: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(AUDIO_SET_ATTRIBUTES)", arg3, ++ sizeof(audio_attributes_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case AUDIO_SET_KARAOKE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(AUDIO_SET_KARAOKE)", arg3, ++ sizeof(audio_karaoke_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_RESET: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_GET_CAP: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_CAP)", arg3, ++ sizeof(ca_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_caps_t)); ++ break; ++ case CA_GET_SLOT_INFO: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_SLOT_INFO)", arg3, ++ sizeof(ca_slot_info_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_slot_info_t)); ++ break; ++ case CA_GET_DESCR_INFO: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_DESCR_INFO)", arg3, ++ sizeof(ca_descr_info_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_descr_info_t)); ++ break; ++ case CA_GET_MSG: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(CA_GET_MSG)", arg3, ++ sizeof(ca_msg_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(ca_msg_t)); ++ break; ++ case CA_SEND_MSG: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(CA_SEND_MSG)", arg3, ++ sizeof(ca_msg_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_SET_DESCR: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(CA_SET_DESCR)", arg3, ++ sizeof(ca_descr_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case CA_SET_PID: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(CA_SET_PID)", arg3, ++ sizeof(ca_pid_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_START: ++ case DMX_STOP: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_FILTER: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(DMX_SET_FILTER)", arg3, ++ sizeof(struct dmx_sct_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_PES_FILTER: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(DMX_SET_PES_FILTER)", arg3, ++ sizeof(struct dmx_pes_filter_params)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_SET_BUFFER_SIZE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case DMX_GET_EVENT: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_EVENT)", arg3, ++ sizeof(struct dmx_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dmx_event)); ++ break; ++ case DMX_GET_PES_PIDS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_PES_PIDS)", arg3, ++ 5*sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, 5*sizeof(uint16_t)); ++ break; ++ case DMX_GET_CAPS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_CAPS)", arg3, ++ sizeof(dmx_caps_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(dmx_caps_t)); ++ break; ++ case DMX_GET_STC: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(DMX_GET_STC)", arg3, ++ sizeof(struct dmx_stc)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dmx_stc)); ++ break; ++ case DMX_SET_SOURCE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(DMX_SET_SOURCE)", arg3, ++ sizeof(dmx_source_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_INFO: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_GET_INFO)", arg3, ++ sizeof(struct dvb_frontend_info)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_frontend_info)); ++ break; ++ case FE_DISEQC_RESET_OVERLOAD: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_SEND_MASTER_CMD: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(FE_DISEQC_SEND_MASTER_CMD)", arg3, ++ sizeof(struct dvb_diseqc_master_cmd)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_DISEQC_RECV_SLAVE_REPLY: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_DISEQC_RECV_SLAVE_REPLY)", arg3, ++ sizeof(struct dvb_diseqc_slave_reply)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_diseqc_slave_reply)); ++ break; ++ case FE_DISEQC_SEND_BURST: ++ case FE_SET_TONE: ++ case FE_SET_VOLTAGE: ++ case FE_ENABLE_HIGH_LNB_VOLTAGE: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_READ_STATUS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_STATUS)", arg3, ++ sizeof(fe_status_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(fe_status_t)); ++ break; ++ case FE_READ_BER: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_BER)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint32_t)); ++ break; ++ case FE_READ_SIGNAL_STRENGTH: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_SIGNAL_STRENGTH)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_SNR: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_SNR)", arg3, ++ sizeof(uint16_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint16_t)); ++ break; ++ case FE_READ_UNCORRECTED_BLOCKS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_READ_UNCORRECTED_BLOCKS)", arg3, ++ sizeof(uint32_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(uint32_t)); ++ break; ++ case FE_SET_FRONTEND: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(FE_SET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case FE_GET_FRONTEND: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_GET_FRONTEND)", arg3, ++ sizeof(struct dvb_frontend_parameters)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_frontend_parameters)); ++ break; ++ case FE_GET_EVENT: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(FE_GET_EVENT)", arg3, ++ sizeof(struct dvb_frontend_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_frontend_event)); ++ break; ++ case NET_ADD_IF: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(NET_ADD_IF (pid, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->pid), ++ sizeof(((struct dvb_net_if *) arg3)->pid)); ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(NET_ADD_IF (if_num, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->if_num), ++ sizeof(((struct dvb_net_if *) arg3)->if_num)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_net_if)); ++ break; ++ case NET_REMOVE_IF: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case NET_GET_IF: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(NET_GET_IF (if_num, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->if_num), ++ sizeof(((struct dvb_net_if *) arg3)->if_num)); ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(NET_GET_IF (pid, uint16_t))", ++ (int) &(((struct dvb_net_if *) arg3)->pid), ++ sizeof(((struct dvb_net_if *) arg3)->pid)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct dvb_net_if)); ++ break; ++ case OSD_SEND_CMD: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(OSD_SEND_CMD)", arg3, ++ sizeof(osd_cmd_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_STOP: ++ case VIDEO_PLAY: ++ case VIDEO_FREEZE: ++ case VIDEO_CONTINUE: ++ case VIDEO_SELECT_SOURCE: ++ case VIDEO_SET_BLANK: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_STATUS: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_STATUS)", arg3, ++ sizeof(struct video_status)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct video_status)); ++ break; ++ case VIDEO_GET_EVENT: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_EVENT)", arg3, ++ sizeof(struct video_event)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(struct video_event)); ++ break; ++ case VIDEO_SET_DISPLAY_FORMAT: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_STILLPICTURE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_STILLPICTURE)", arg3, ++ sizeof(struct video_still_picture)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_FAST_FORWARD: ++ case VIDEO_SLOWMOTION: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_CAPABILITIES: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_CAPABILITIES)", arg3, ++ sizeof(unsigned int)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(unsigned int)); ++ break; ++ case VIDEO_CLEAR_BUFFER: ++ case VIDEO_SET_ID: ++ case VIDEO_SET_STREAMTYPE: ++ case VIDEO_SET_FORMAT: ++ case VIDEO_SET_SYSTEM: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_HIGHLIGHT: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_SET_HIGHLIGHT)", arg3, ++ sizeof(video_highlight_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_SPU: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_SET_SPU)", arg3, ++ sizeof(video_spu_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_SET_SPU_PALETTE: ++ SYSCALL_TRACK( pre_mem_read,tst, "ioctl(VIDEO_SET_SPU_PALETTE)", arg3, ++ sizeof(video_spu_palette_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++ case VIDEO_GET_NAVI: ++ SYSCALL_TRACK( pre_mem_write,tst, "ioctl(VIDEO_GET_NAVI)", arg3, ++ sizeof(video_navi_pack_t)); ++ KERNEL_DO_SYSCALL(tid,res); ++ if (!VG_(is_kerror)(res) && res == 0) ++ VG_TRACK( post_mem_write,arg3, sizeof(video_navi_pack_t)); ++ break; ++#if 0 ++ /* FIXME: conflicts with NET_REMOVE_IF - both are _IO('o', 53) */ ++ case VIDEO_SET_ATTRIBUTES: ++ KERNEL_DO_SYSCALL(tid,res); ++ break; ++#endif ++ + /* We don't have any specific information on it, so + try to do something reasonable based on direction and + size bits. The encoding scheme is described in +--- valgrind-20030716/coregrind/vg_unsafe.h.orig 2003-06-14 10:50:27.000000000 +0200 ++++ valgrind-20030716/coregrind/vg_unsafe.h 2003-07-24 18:22:55.000000000 +0200 +@@ -88,6 +88,13 @@ + + #include + ++#include ++#include ++#include ++#include ++#include ++#include ++#include + + /*--------------------------------------------------------------------*/ + /*--- end vg_unsafe.h ---*/ -- cgit v1.2.3 From b51e4627e2053a7434d1f308123a6a9b07e4e78f Mon Sep 17 00:00:00 2001 From: js Date: Thu, 24 Jul 2003 14:08:21 -0300 Subject: - document DMX_GET_STC - bump version to 1.0.0 --- dvb-spec/dvbapi/demux.tex | 32 +++++++++++++++++++++++++++++++- dvb-spec/dvbapi/title.tex | 2 +- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/dvb-spec/dvbapi/demux.tex b/dvb-spec/dvbapi/demux.tex index dd032f58d..882463090 100644 --- a/dvb-spec/dvbapi/demux.tex +++ b/dvb-spec/dvbapi/demux.tex @@ -139,6 +139,17 @@ struct dmx_event }; \end{verbatim} +\devsubsubsec{struct dmx\_stc} +\label{dmxstc} + +\begin{verbatim} +struct dmx_stc { + unsigned int num; /* input : which STC? 0..N */ + unsigned int base; /* output: divisor for stc to get 90 kHz clock */ + uint64_t stc; /* output: stc in 'base'*90 kHz units */ +}; +\end{verbatim} + \clearpage \devsubsec{Demux Function Calls} @@ -367,7 +378,7 @@ struct dmx_event \ifunction{DMX\_GET\_EVENT}{ int ioctl( int fd, int request = DMX\_GET\_EVENT, struct dmx\_event *ev); }{ - This ioctl call returns an event if available. If an event is not + 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 @@ -387,6 +398,25 @@ struct dmx_event EWOULDBLOCK & There is no event pending, and the device is in non-blocking mode.\\ } +\ifunction{DMX\_GET\_STC}{ + int ioctl( int fd, int request = DMX\_GET\_STC, struct dmx\_stc *stc); + }{ + This ioctl call returns the current value of the system time counter + (which is driven by a PES filter of type DMX\_PES\_PCR). Some hardware + supports more than one STC, so you must specify which one by setting + the num field of stc before the ioctl (range 0...n). The result is returned in form + of a ratio with a 64 bit numerator and a 32 bit denominator, so the + real 90kHz STC value is \begin{ttfamily}stc->stc / stc->base\end{ttfamily}. + }{ + int fd & File descriptor returned by a previous call to open().\\ + int request & Equals DMX\_GET\_STC for this command.\\ + struct dmx\_stc *stc & Pointer to the location where the stc is to be stored.\\ + }{ + EBADF & fd is not a valid file descriptor.\\ + EFAULT & stc points to an invalid address.\\ + EINVAL & Invalid stc number.\\ +} + %%% Local Variables: %%% mode: latex %%% TeX-master: "dvbapi" diff --git a/dvb-spec/dvbapi/title.tex b/dvb-spec/dvbapi/title.tex index 29aca30d6..857492b7e 100644 --- a/dvb-spec/dvbapi/title.tex +++ b/dvb-spec/dvbapi/title.tex @@ -10,7 +10,7 @@ and Dr. Marcus O.C. Metzler\\ \texttt{}\\ } -\date{02/10/2003\\V 1.0.0-pre1} +\date{24/07/2003\\V 1.0.0} \maketitle -- cgit v1.2.3 From 56a4ef5b2748552e9f28020a1dad9dec2119542c Mon Sep 17 00:00:00 2001 From: js Date: Fri, 25 Jul 2003 16:07:49 -0300 Subject: added HTML target --- dvb-spec/dvbapi/.cvsignore | 2 ++ dvb-spec/dvbapi/Makefile | 7 ++++--- dvb-spec/dvbapi/frontend.tex | 2 +- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/dvb-spec/dvbapi/.cvsignore b/dvb-spec/dvbapi/.cvsignore index fb6974f6b..71db27b0a 100644 --- a/dvb-spec/dvbapi/.cvsignore +++ b/dvb-spec/dvbapi/.cvsignore @@ -9,3 +9,5 @@ dvbapi.log dvbapi.pdf dvbapi.out dvbapi.toc +dvbapi.ind +dvbapi.ilg diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile index 83a5e5f7a..1158360e2 100644 --- a/dvb-spec/dvbapi/Makefile +++ b/dvb-spec/dvbapi/Makefile @@ -10,9 +10,6 @@ dvbapi.ps: dvbapi.dvi dvips $< dvbapi.dvi: dvbapi.bbl $(TEXS) - -latex dvbapi - -bibtex dvbapi - -makeindex dvbapi -latex dvbapi -latex dvbapi @@ -21,6 +18,9 @@ dvbapi.bbl: $(TEXS) -bibtex dvbapi -makeindex dvbapi +html: dvbapi.dvi + latex2html -address "LinuxTV DVB API" -long_titles 4 -split 3 dvbapi.tex + %.ps: %.fig ./fig2pstex $< @@ -28,3 +28,4 @@ clean: rm -f dvbapi.dvi rm -f *.aux *.bbl *.blg *.idx *.ilg *.ind *.log *.out *.toc rm -f *.pdf *.pst *.ps + rm -rf dvbapi diff --git a/dvb-spec/dvbapi/frontend.tex b/dvb-spec/dvbapi/frontend.tex index cbd646b93..9ae8a343e 100644 --- a/dvb-spec/dvbapi/frontend.tex +++ b/dvb-spec/dvbapi/frontend.tex @@ -263,7 +263,7 @@ typedef enum fe_code_rate { FEC_AUTO } fe_code_rate_t; \end{verbatim} -which correspond to error correction rates of $1/2$, $2/3$, etc., +which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto detection. \noindent -- cgit v1.2.3 From e09b3f6768a32a3ac714c8a44fa5ec64f986a41f Mon Sep 17 00:00:00 2001 From: js Date: Tue, 29 Jul 2003 14:05:03 -0300 Subject: ignore html output dir --- dvb-spec/dvbapi/.cvsignore | 1 + 1 file changed, 1 insertion(+) diff --git a/dvb-spec/dvbapi/.cvsignore b/dvb-spec/dvbapi/.cvsignore index 71db27b0a..89f9afcb7 100644 --- a/dvb-spec/dvbapi/.cvsignore +++ b/dvb-spec/dvbapi/.cvsignore @@ -11,3 +11,4 @@ dvbapi.out dvbapi.toc dvbapi.ind dvbapi.ilg +dvbapi -- cgit v1.2.3 From 8d72af7c80177c51843d0b0326d0a4a01099cb04 Mon Sep 17 00:00:00 2001 From: hunold Date: Fri, 23 Apr 2004 03:38:10 -0300 Subject: - standard dvips sends output to the default printer! use "-o $@" to send it to the destination file instead. (ever wondered who prints out the dvb api regularly on your laser printer? ;-) --- dvb-spec/dvbapi/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile index 1158360e2..6d349c80d 100644 --- a/dvb-spec/dvbapi/Makefile +++ b/dvb-spec/dvbapi/Makefile @@ -4,10 +4,10 @@ TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex net.tex frontend.tex \ demux.tex kdapi.tex examples.tex intro.tex title.tex dvbstb.ps dvbapi.pdf: dvbapi.dvi - dvipdf $< + dvipdf -f $< -o $@ dvbapi.ps: dvbapi.dvi - dvips $< + dvips -f $< -o $@ dvbapi.dvi: dvbapi.bbl $(TEXS) -latex dvbapi -- cgit v1.2.3 From 6236b63ea391dfb73f0ade028a1ea7889eb5319c Mon Sep 17 00:00:00 2001 From: hunold Date: Fri, 23 Apr 2004 08:55:10 -0300 Subject: - fix dvipdf --- dvb-spec/dvbapi/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile index 6d349c80d..e741df6da 100644 --- a/dvb-spec/dvbapi/Makefile +++ b/dvb-spec/dvbapi/Makefile @@ -4,7 +4,7 @@ TEXS= dvbapi.tex devices.tex video.tex audio.tex ca.tex net.tex frontend.tex \ demux.tex kdapi.tex examples.tex intro.tex title.tex dvbstb.ps dvbapi.pdf: dvbapi.dvi - dvipdf -f $< -o $@ + dvipdf $< $@ dvbapi.ps: dvbapi.dvi dvips -f $< -o $@ -- cgit v1.2.3 From 03bcc8695fb4334e4e30d03a9dc0867361615c1a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 16 Feb 2009 15:27:44 -0300 Subject: Revert changeset aa3e5cc1d833 From: Mauro Carvalho Chehab On Mon, 02 Feb 2009, Hartmut wrote: This change set is wrong. The affected functions cannot be called from an interrupt context, because they may process large buffers. In this case, interrupts are disabled for a long time. Functions, like dvb_dmx_swfilter_packets(), could be called only from a tasklet. This change set does hide some strong design bugs in dm1105.c and au0828-dvb.c. Please revert this change set and do fix the bugs in dm1105.c and au0828-dvb.c (and other files). On Sun, 15 Feb 2009, Oliver Endriss wrote: This changeset _must_ be reverted! It breaks all kernels since 2.6.27 for applications which use DVB and require a low interrupt latency. It is a very bad idea to call the demuxer to process data buffers with interrupts disabled! On Mon, 16 Feb 2009, Trent Piepho wrote: I agree, this is bad. The demuxer is far too much work to be done with IRQs off. IMHO, even doing it under a spin-lock is excessive. It should be a mutex. Drivers should use a work-queue to feed the demuxer. Thank you for testing this changeset and discovering the issues on it. Priority: high CC: Trent Piepho CC: Hartmut CC: Oliver Endriss CC: Andreas Oberritter Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/dvb/dvb-core/dmxdev.c | 16 +++++++--------- linux/drivers/media/dvb/dvb-core/dvb_demux.c | 16 ++++++---------- 2 files changed, 13 insertions(+), 19 deletions(-) diff --git a/linux/drivers/media/dvb/dvb-core/dmxdev.c b/linux/drivers/media/dvb/dvb-core/dmxdev.c index cc143929a..c35fbb8d8 100644 --- a/linux/drivers/media/dvb/dvb-core/dmxdev.c +++ b/linux/drivers/media/dvb/dvb-core/dmxdev.c @@ -364,16 +364,15 @@ static int dvb_dmxdev_section_callback(const u8 *buffer1, size_t buffer1_len, enum dmx_success success) { struct dmxdev_filter *dmxdevfilter = filter->priv; - unsigned long flags; int ret; if (dmxdevfilter->buffer.error) { wake_up(&dmxdevfilter->buffer.queue); return 0; } - spin_lock_irqsave(&dmxdevfilter->dev->lock, flags); + spin_lock(&dmxdevfilter->dev->lock); if (dmxdevfilter->state != DMXDEV_STATE_GO) { - spin_unlock_irqrestore(&dmxdevfilter->dev->lock, flags); + spin_unlock(&dmxdevfilter->dev->lock); return 0; } del_timer(&dmxdevfilter->timer); @@ -392,7 +391,7 @@ static int dvb_dmxdev_section_callback(const u8 *buffer1, size_t buffer1_len, } if (dmxdevfilter->params.sec.flags & DMX_ONESHOT) dmxdevfilter->state = DMXDEV_STATE_DONE; - spin_unlock_irqrestore(&dmxdevfilter->dev->lock, flags); + spin_unlock(&dmxdevfilter->dev->lock); wake_up(&dmxdevfilter->buffer.queue); return 0; } @@ -404,12 +403,11 @@ static int dvb_dmxdev_ts_callback(const u8 *buffer1, size_t buffer1_len, { struct dmxdev_filter *dmxdevfilter = feed->priv; struct dvb_ringbuffer *buffer; - unsigned long flags; int ret; - spin_lock_irqsave(&dmxdevfilter->dev->lock, flags); + spin_lock(&dmxdevfilter->dev->lock); if (dmxdevfilter->params.pes.output == DMX_OUT_DECODER) { - spin_unlock_irqrestore(&dmxdevfilter->dev->lock, flags); + spin_unlock(&dmxdevfilter->dev->lock); return 0; } @@ -419,7 +417,7 @@ static int dvb_dmxdev_ts_callback(const u8 *buffer1, size_t buffer1_len, else buffer = &dmxdevfilter->dev->dvr_buffer; if (buffer->error) { - spin_unlock_irqrestore(&dmxdevfilter->dev->lock, flags); + spin_unlock(&dmxdevfilter->dev->lock); wake_up(&buffer->queue); return 0; } @@ -430,7 +428,7 @@ static int dvb_dmxdev_ts_callback(const u8 *buffer1, size_t buffer1_len, dvb_ringbuffer_flush(buffer); buffer->error = ret; } - spin_unlock_irqrestore(&dmxdevfilter->dev->lock, flags); + spin_unlock(&dmxdevfilter->dev->lock); wake_up(&buffer->queue); return 0; } diff --git a/linux/drivers/media/dvb/dvb-core/dvb_demux.c b/linux/drivers/media/dvb/dvb-core/dvb_demux.c index a2c1fd5d2..e2eca0b1f 100644 --- a/linux/drivers/media/dvb/dvb-core/dvb_demux.c +++ b/linux/drivers/media/dvb/dvb-core/dvb_demux.c @@ -399,9 +399,7 @@ static void dvb_dmx_swfilter_packet(struct dvb_demux *demux, const u8 *buf) void dvb_dmx_swfilter_packets(struct dvb_demux *demux, const u8 *buf, size_t count) { - unsigned long flags; - - spin_lock_irqsave(&demux->lock, flags); + spin_lock(&demux->lock); while (count--) { if (buf[0] == 0x47) @@ -409,17 +407,16 @@ void dvb_dmx_swfilter_packets(struct dvb_demux *demux, const u8 *buf, buf += 188; } - spin_unlock_irqrestore(&demux->lock, flags); + spin_unlock(&demux->lock); } EXPORT_SYMBOL(dvb_dmx_swfilter_packets); void dvb_dmx_swfilter(struct dvb_demux *demux, const u8 *buf, size_t count) { - unsigned long flags; int p = 0, i, j; - spin_lock_irqsave(&demux->lock, flags); + spin_lock(&demux->lock); if (demux->tsbufp) { i = demux->tsbufp; @@ -452,18 +449,17 @@ void dvb_dmx_swfilter(struct dvb_demux *demux, const u8 *buf, size_t count) } bailout: - spin_unlock_irqrestore(&demux->lock, flags); + spin_unlock(&demux->lock); } EXPORT_SYMBOL(dvb_dmx_swfilter); void dvb_dmx_swfilter_204(struct dvb_demux *demux, const u8 *buf, size_t count) { - unsigned long flags; int p = 0, i, j; u8 tmppack[188]; - spin_lock_irqsave(&demux->lock, flags); + spin_lock(&demux->lock); if (demux->tsbufp) { i = demux->tsbufp; @@ -504,7 +500,7 @@ void dvb_dmx_swfilter_204(struct dvb_demux *demux, const u8 *buf, size_t count) } bailout: - spin_unlock_irqrestore(&demux->lock, flags); + spin_unlock(&demux->lock); } EXPORT_SYMBOL(dvb_dmx_swfilter_204); -- cgit v1.2.3 From 6d5737990907617f67f5d8a9633ed16c8714171d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 16 Feb 2009 15:54:29 -0300 Subject: v4l2-framework.txt: Whitespace clenups From: Mauro Carvalho Chehab Signed-off-by: Mauro Carvalho Chehab --- linux/Documentation/video4linux/v4l2-framework.txt | 48 +++++++++++----------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/linux/Documentation/video4linux/v4l2-framework.txt b/linux/Documentation/video4linux/v4l2-framework.txt index a6005257a..48cdf8624 100644 --- a/linux/Documentation/video4linux/v4l2-framework.txt +++ b/linux/Documentation/video4linux/v4l2-framework.txt @@ -531,11 +531,11 @@ struct v4l2_device *v4l2_dev = vdev->v4l2_dev; video buffer helper functions ----------------------------- -The v4l2 core API provides a standard method for dealing with video -buffers. Those methods allow a driver to implement read(), mmap() and +The v4l2 core API provides a standard method for dealing with video +buffers. Those methods allow a driver to implement read(), mmap() and overlay() on a consistent way. -There are currently methods for using video buffers on devices that +There are currently methods for using video buffers on devices that supports DMA with scatter/gather method (videobuf-dma-sg), DMA with linear access (videobuf-dma-contig), and vmalloced buffers, mostly used on USB drivers (videobuf-vmalloc). @@ -544,50 +544,50 @@ Any driver using videobuf should provide operations (callbacks) for four handlers: ops->buf_setup - calculates the size of the video buffers and avoid they - to waste more than some maximum limit of RAM; + to waste more than some maximum limit of RAM; ops->buf_prepare - fills the video buffer structs and calls videobuf_iolock() to alloc and prepare mmaped memory; ops->buf_queue - advices the driver that another buffer were - requested (by read() or by QBUF); + requested (by read() or by QBUF); ops->buf_release - frees any buffer that were allocated. In order to use it, the driver need to have a code (generally called at interrupt context) that will properly handle the buffer request lists, announcing that a new buffer were filled. -The irq handling code should handle the videobuf task lists, in order -to advice videobuf that a new frame were filled, in order to honor to a +The irq handling code should handle the videobuf task lists, in order +to advice videobuf that a new frame were filled, in order to honor to a request. The code is generally like this one: - if (list_empty(&dma_q->active)) + if (list_empty(&dma_q->active)) return; - buf = list_entry(dma_q->active.next, struct vbuffer, vb.queue); + buf = list_entry(dma_q->active.next, struct vbuffer, vb.queue); - if (!waitqueue_active(&buf->vb.done)) + if (!waitqueue_active(&buf->vb.done)) return; /* Some logic to handle the buf may be needed here */ - list_del(&buf->vb.queue); - do_gettimeofday(&buf->vb.ts); - wake_up(&buf->vb.done); + list_del(&buf->vb.queue); + do_gettimeofday(&buf->vb.ts); + wake_up(&buf->vb.done); -Those are the videobuffer functions used on drivers, implemented on +Those are the videobuffer functions used on drivers, implemented on videobuf-core: - Videobuf init functions videobuf_queue_sg_init() - Initializes the videobuf infrastructure. This function should be - called before any other videobuf function on drivers that uses DMA + Initializes the videobuf infrastructure. This function should be + called before any other videobuf function on drivers that uses DMA Scatter/Gather buffers. videobuf_queue_dma_contig_init - Initializes the videobuf infrastructure. This function should be - called before any other videobuf function on drivers that need DMA + Initializes the videobuf infrastructure. This function should be + called before any other videobuf function on drivers that need DMA contiguous buffers. videobuf_queue_vmalloc_init() - Initializes the videobuf infrastructure. This function should be + Initializes the videobuf infrastructure. This function should be called before any other videobuf function on USB (and other drivers) that need a vmalloced type of videobuf. @@ -607,12 +607,12 @@ videobuf-core: Stops video handling, ends mmap and frees mmap and other buffers. - V4L2 api functions. Those functions correspond to VIDIOC_foo ioctls: - videobuf_reqbufs(), videobuf_querybuf(), videobuf_qbuf(), + videobuf_reqbufs(), videobuf_querybuf(), videobuf_qbuf(), videobuf_dqbuf(), videobuf_streamon(), videobuf_streamoff(). - V4L1 api function (corresponds to VIDIOCMBUF ioctl): videobuf_cgmbuf() - This function is used to provide backward compatibility with V4L1 + This function is used to provide backward compatibility with V4L1 API. - Some help functions for read()/poll() operations: @@ -623,7 +623,7 @@ videobuf-core: videobuf_poll_stream() polling help function -The better way to understand it is to take a look at vivi driver. One -of the main reasons for vivi is to be a videobuf usage example. the -vivi_thread_tick() does the task that the IRQ callback would do on PCI +The better way to understand it is to take a look at vivi driver. One +of the main reasons for vivi is to be a videobuf usage example. the +vivi_thread_tick() does the task that the IRQ callback would do on PCI drivers (or the irq callback on USB). -- cgit v1.2.3 From 7c429cdbe8e7fa93d0c24d10749fe2a2bdd5e524 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 15 Jan 2009 21:58:55 +0900 Subject: saa7134: fix Avermedia E506R composite input From: Tim Farrington Make correction to composite input plus svideo input to Avermedia E506R Signed-off-by: Tim Farrington Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/video/saa7134/saa7134-cards.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/linux/drivers/media/video/saa7134/saa7134-cards.c b/linux/drivers/media/video/saa7134/saa7134-cards.c index 01cc9543f..e565d437b 100644 --- a/linux/drivers/media/video/saa7134/saa7134-cards.c +++ b/linux/drivers/media/video/saa7134/saa7134-cards.c @@ -4362,13 +4362,13 @@ struct saa7134_board saa7134_boards[] = { .amux = TV, .tv = 1, }, { - .name = name_comp, - .vmux = 0, + .name = name_comp1, + .vmux = 3, .amux = LINE1, }, { .name = name_svideo, .vmux = 8, - .amux = LINE1, + .amux = LINE2, } }, .radio = { .name = name_radio, -- cgit v1.2.3 From a341145919a0d3bf91e657926a06bebca10a94ba Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 20 Jan 2009 15:34:43 -0600 Subject: V4L2: Add COLORFX user control From: Sergio Aguirre This is a common feature on many cameras. the options are: Default colors, B & W, Sepia Signed-off-by: Sergio Aguirre Signed-off-by: Mauro Carvalho Chehab --- linux/include/linux/videodev2.h | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/linux/include/linux/videodev2.h b/linux/include/linux/videodev2.h index e5be28ac6..6969c3086 100644 --- a/linux/include/linux/videodev2.h +++ b/linux/include/linux/videodev2.h @@ -880,8 +880,15 @@ enum v4l2_power_line_frequency { #define V4L2_CID_BACKLIGHT_COMPENSATION (V4L2_CID_BASE+28) #define V4L2_CID_CHROMA_AGC (V4L2_CID_BASE+29) #define V4L2_CID_COLOR_KILLER (V4L2_CID_BASE+30) +#define V4L2_CID_COLORFX (V4L2_CID_BASE+31) +enum v4l2_colorfx { + V4L2_COLORFX_NONE = 0, + V4L2_COLORFX_BW = 1, + V4L2_COLORFX_SEPIA = 2, +}; + /* last CID + 1 */ -#define V4L2_CID_LASTP1 (V4L2_CID_BASE+31) +#define V4L2_CID_LASTP1 (V4L2_CID_BASE+32) /* MPEG-class control IDs defined by V4L2 */ #define V4L2_CID_MPEG_BASE (V4L2_CTRL_CLASS_MPEG | 0x900) -- cgit v1.2.3 -- cgit v1.2.3 From 398b32c3c4e7f3675a104de6c037024e7803bf08 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 16 Feb 2009 21:38:08 -0300 Subject: Add dvb API docs at hgignore From: Mauro Carvalho Chehab In order to compile dvb API, it is needed to have tetex-latex and Xfig packages. This patch adds the generated docs at hgignore. Signed-off-by: Mauro Carvalho Chehab --- .hgignore | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.hgignore b/.hgignore index cc9eea282..c47aa55bb 100644 --- a/.hgignore +++ b/.hgignore @@ -24,6 +24,7 @@ v4l/oss v4l/Modules.symvers$ v4l/Module.symvers$ v4l/modules.order$ +v4l/Module.markers$ v4l/config-compat.h$ v4l/.myconfig$ v4l/.snapshot$ @@ -73,3 +74,14 @@ v4l/firmware/dabusb/firmware.fw v4l/firmware/ihex2fw v4l/firmware/ttusb-budget/dspbootcode.bin v4l/firmware/vicam/firmware.fw +dvb-spec/dvbapi/dvbapi.aux +dvb-spec/dvbapi/dvbapi.bbl +dvb-spec/dvbapi/dvbapi.blg +dvb-spec/dvbapi/dvbapi.dvi +dvb-spec/dvbapi/dvbapi.log +dvb-spec/dvbapi/dvbapi.out +dvb-spec/dvbapi/dvbapi.pdf +dvb-spec/dvbapi/dvbapi.ps +dvb-spec/dvbapi/dvbapi.toc +dvb-spec/dvbapi/dvbstb.ps +dvb-spec/dvbapi/dvbstb.pst -- cgit v1.2.3 From fb3a9246d433dda2f7ace056abb2574ed3a9da42 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Jan 2009 06:02:41 +0000 Subject: tw9910: color format check is added on set_fmt From: Kuninori Morimoto Signed-off-by: Kuninori Morimoto Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/video/tw9910.c | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/linux/drivers/media/video/tw9910.c b/linux/drivers/media/video/tw9910.c index c670b23a1..4593cdea7 100644 --- a/linux/drivers/media/video/tw9910.c +++ b/linux/drivers/media/video/tw9910.c @@ -645,6 +645,19 @@ static int tw9910_set_fmt(struct soc_camera_device *icd, __u32 pixfmt, struct tw9910_priv *priv = container_of(icd, struct tw9910_priv, icd); int ret = -EINVAL; u8 val; + int i; + + /* + * check color format + */ + for (i = 0 ; i < ARRAY_SIZE(tw9910_color_fmt) ; i++) { + if (pixfmt == tw9910_color_fmt[i].fourcc) { + ret = 0; + break; + } + } + if (ret < 0) + goto tw9910_set_fmt_error; /* * select suitable norm -- cgit v1.2.3 From 13e2e59a82953d5b837a02c7115ae6fad1c0f1d4 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 14 Feb 2009 23:58:33 +0100 Subject: ivtv: fix decoder crash regression From: Hans Verkuil The video_ioctl2 conversion of ivtv in kernel 2.6.27 introduced a bug causing decoder commands to crash. The decoder commands should have been handled from the video_ioctl2 default handler, ensuring correct mapping of the argument between user and kernel space. Unfortunately they ended up before the video_ioctl2 call, causing random crashes. Thanks to hannes@linus.priv.at for testing and helping me track down the cause! Priority: high Signed-off-by: Hans Verkuil --- linux/drivers/media/video/ivtv/ivtv-ioctl.c | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/linux/drivers/media/video/ivtv/ivtv-ioctl.c b/linux/drivers/media/video/ivtv/ivtv-ioctl.c index aa55a3cc4..d7a708ad3 100644 --- a/linux/drivers/media/video/ivtv/ivtv-ioctl.c +++ b/linux/drivers/media/video/ivtv/ivtv-ioctl.c @@ -1752,6 +1752,18 @@ static long ivtv_default(struct file *file, void *fh, int cmd, void *arg) break; } + case IVTV_IOC_DMA_FRAME: + case VIDEO_GET_PTS: + case VIDEO_GET_FRAME_COUNT: + case VIDEO_GET_EVENT: + case VIDEO_PLAY: + case VIDEO_STOP: + case VIDEO_FREEZE: + case VIDEO_CONTINUE: + case VIDEO_COMMAND: + case VIDEO_TRY_COMMAND: + return ivtv_decoder_ioctls(file, cmd, (void *)arg); + default: return -EINVAL; } @@ -1794,18 +1806,6 @@ static long ivtv_serialized_ioctl(struct ivtv *itv, struct file *filp, ivtv_vapi(itv, CX2341X_DEC_SET_AUDIO_MODE, 2, itv->audio_bilingual_mode, itv->audio_stereo_mode); return 0; - case IVTV_IOC_DMA_FRAME: - case VIDEO_GET_PTS: - case VIDEO_GET_FRAME_COUNT: - case VIDEO_GET_EVENT: - case VIDEO_PLAY: - case VIDEO_STOP: - case VIDEO_FREEZE: - case VIDEO_CONTINUE: - case VIDEO_COMMAND: - case VIDEO_TRY_COMMAND: - return ivtv_decoder_ioctls(filp, cmd, (void *)arg); - default: break; } -- cgit v1.2.3 From 337e145d4f292cbeeb8dd95c70ecef641230a657 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Mon, 16 Feb 2009 08:25:32 +0100 Subject: ivtv: fix regression in get sliced vbi format From: Hans Verkuil The new v4l2_subdev_call used s_fmt instead of g_fmt. Priority: high Signed-off-by: Hans Verkuil Thanks-to: Andy Walls --- linux/drivers/media/video/ivtv/ivtv-ioctl.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linux/drivers/media/video/ivtv/ivtv-ioctl.c b/linux/drivers/media/video/ivtv/ivtv-ioctl.c index d7a708ad3..9a0424298 100644 --- a/linux/drivers/media/video/ivtv/ivtv-ioctl.c +++ b/linux/drivers/media/video/ivtv/ivtv-ioctl.c @@ -391,7 +391,7 @@ static int ivtv_g_fmt_sliced_vbi_cap(struct file *file, void *fh, struct v4l2_fo return 0; } - v4l2_subdev_call(itv->sd_video, video, s_fmt, fmt); + v4l2_subdev_call(itv->sd_video, video, g_fmt, fmt); vbifmt->service_set = ivtv_get_service_set(vbifmt); return 0; } -- cgit v1.2.3 From fa940b36a68186b4e5b77a5afb929f68603b52bf Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 9 Feb 2009 21:06:49 +0000 Subject: V4L: Storage class should be before const qualifier From: Tobias Klauser The C99 specification states in section 6.11.5: The placement of a storage-class specifier other than at the beginning of the declaration specifiers in a declaration is an obsolescent feature. Signed-off-by: Tobias Klauser CC: Jean-Francois Moine CC: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/video/gspca/t613.c | 2 +- linux/drivers/media/video/tcm825x.c | 22 +++++++++++----------- linux/drivers/media/video/tcm825x.h | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/linux/drivers/media/video/gspca/t613.c b/linux/drivers/media/video/gspca/t613.c index adec0767c..c04836ed2 100644 --- a/linux/drivers/media/video/gspca/t613.c +++ b/linux/drivers/media/video/gspca/t613.c @@ -272,7 +272,7 @@ struct additional_sensor_data { const u8 stream[4]; }; -const static struct additional_sensor_data sensor_data[] = { +static const struct additional_sensor_data sensor_data[] = { { /* OM6802 */ .data1 = {0xc2, 0x28, 0x0f, 0x22, 0xcd, 0x27, 0x2c, 0x06, diff --git a/linux/drivers/media/video/tcm825x.c b/linux/drivers/media/video/tcm825x.c index 2f823f27a..559ade821 100644 --- a/linux/drivers/media/video/tcm825x.c +++ b/linux/drivers/media/video/tcm825x.c @@ -50,7 +50,7 @@ struct tcm825x_sensor { }; /* list of image formats supported by TCM825X sensor */ -const static struct v4l2_fmtdesc tcm825x_formats[] = { +static const struct v4l2_fmtdesc tcm825x_formats[] = { { .description = "YUYV (YUV 4:2:2), packed", .pixelformat = V4L2_PIX_FMT_UYVY, @@ -76,15 +76,15 @@ const static struct v4l2_fmtdesc tcm825x_formats[] = { * TCM825X register configuration for all combinations of pixel format and * image size */ -const static struct tcm825x_reg subqcif = { 0x20, TCM825X_PICSIZ }; -const static struct tcm825x_reg qcif = { 0x18, TCM825X_PICSIZ }; -const static struct tcm825x_reg cif = { 0x14, TCM825X_PICSIZ }; -const static struct tcm825x_reg qqvga = { 0x0c, TCM825X_PICSIZ }; -const static struct tcm825x_reg qvga = { 0x04, TCM825X_PICSIZ }; -const static struct tcm825x_reg vga = { 0x00, TCM825X_PICSIZ }; +static const struct tcm825x_reg subqcif = { 0x20, TCM825X_PICSIZ }; +static const struct tcm825x_reg qcif = { 0x18, TCM825X_PICSIZ }; +static const struct tcm825x_reg cif = { 0x14, TCM825X_PICSIZ }; +static const struct tcm825x_reg qqvga = { 0x0c, TCM825X_PICSIZ }; +static const struct tcm825x_reg qvga = { 0x04, TCM825X_PICSIZ }; +static const struct tcm825x_reg vga = { 0x00, TCM825X_PICSIZ }; -const static struct tcm825x_reg yuv422 = { 0x00, TCM825X_PICFMT }; -const static struct tcm825x_reg rgb565 = { 0x02, TCM825X_PICFMT }; +static const struct tcm825x_reg yuv422 = { 0x00, TCM825X_PICFMT }; +static const struct tcm825x_reg rgb565 = { 0x02, TCM825X_PICFMT }; /* Our own specific controls */ #define V4L2_CID_ALC V4L2_CID_PRIVATE_BASE @@ -248,10 +248,10 @@ static struct vcontrol { }; -const static struct tcm825x_reg *tcm825x_siz_reg[NUM_IMAGE_SIZES] = +static const struct tcm825x_reg *tcm825x_siz_reg[NUM_IMAGE_SIZES] = { &subqcif, &qqvga, &qcif, &qvga, &cif, &vga }; -const static struct tcm825x_reg *tcm825x_fmt_reg[NUM_PIXEL_FORMATS] = +static const struct tcm825x_reg *tcm825x_fmt_reg[NUM_PIXEL_FORMATS] = { &yuv422, &rgb565 }; /* diff --git a/linux/drivers/media/video/tcm825x.h b/linux/drivers/media/video/tcm825x.h index 770ebacfa..5b7e69682 100644 --- a/linux/drivers/media/video/tcm825x.h +++ b/linux/drivers/media/video/tcm825x.h @@ -188,7 +188,7 @@ struct tcm825x_platform_data { /* Array of image sizes supported by TCM825X. These must be ordered from * smallest image size to largest. */ -const static struct capture_size tcm825x_sizes[] = { +static const struct capture_size tcm825x_sizes[] = { { 128, 96 }, /* subQCIF */ { 160, 120 }, /* QQVGA */ { 176, 144 }, /* QCIF */ -- cgit v1.2.3 From ae420af84b9a311c94b8c41557e700a13fe2f520 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 9 Feb 2009 21:57:06 +0000 Subject: tvp514x: try_count reaches 0, not -1 From: Roel Kluin with while (try_count-- > 0) { ... } try_count reaches 0, not -1. Signed-off-by: Roel Kluin CC: Vaibhav Hiremath Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/video/tvp514x.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linux/drivers/media/video/tvp514x.c b/linux/drivers/media/video/tvp514x.c index 8e23aa53c..5f4cbc2b2 100644 --- a/linux/drivers/media/video/tvp514x.c +++ b/linux/drivers/media/video/tvp514x.c @@ -686,7 +686,7 @@ static int ioctl_s_routing(struct v4l2_int_device *s, break; /* Input detected */ } - if ((current_std == STD_INVALID) || (try_count < 0)) + if ((current_std == STD_INVALID) || (try_count <= 0)) return -EINVAL; decoder->current_std = current_std; -- cgit v1.2.3 From de8d080a697cf4a8c8c997f7f3b76ea1f49a51bd Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 11 Feb 2009 09:34:11 +0000 Subject: V4L/DVB: calibration still successful at 10 From: Roel Kluin With while (i++ < 10) { ... } i can reach 11, so callibration still succeeds at i == 10. Signed-off-by: Roel Kluin Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/common/tuners/mt2060.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linux/drivers/media/common/tuners/mt2060.c b/linux/drivers/media/common/tuners/mt2060.c index d1962bb24..1f1fe90cb 100644 --- a/linux/drivers/media/common/tuners/mt2060.c +++ b/linux/drivers/media/common/tuners/mt2060.c @@ -285,7 +285,7 @@ static void mt2060_calibrate(struct mt2060_priv *priv) while (i++ < 10 && mt2060_readreg(priv, REG_MISC_STAT, &b) == 0 && (b & (1 << 6)) == 0) msleep(20); - if (i < 10) { + if (i <= 10) { mt2060_readreg(priv, REG_FM_FREQ, &priv->fmfreq); // now find out, what is fmreq used for :) dprintk("calibration was successful: %d", (int)priv->fmfreq); } else -- cgit v1.2.3 From e07511c36db32bec6bd0fde4e996001b6e5709e0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 12 Feb 2009 18:19:24 +0000 Subject: zoran: fix printk format From: Randy Dunlap Fix printk format warning: drivers/media/video/zoran/zoran_driver.c:345: warning: format '%lx' expects type 'long unsigned int', but argument 5 has type 'phys_addr_t' Signed-off-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/video/zoran/zoran_driver.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/linux/drivers/media/video/zoran/zoran_driver.c b/linux/drivers/media/video/zoran/zoran_driver.c index 2609f54d7..798745c0a 100644 --- a/linux/drivers/media/video/zoran/zoran_driver.c +++ b/linux/drivers/media/video/zoran/zoran_driver.c @@ -356,9 +356,9 @@ v4l_fbuffer_alloc (struct file *file) SetPageReserved(MAP_NR(mem + off)); dprintk(4, KERN_INFO - "%s: v4l_fbuffer_alloc() - V4L frame %d mem 0x%lx (bus: 0x%lx)\n", + "%s: v4l_fbuffer_alloc() - V4L frame %d mem 0x%lx (bus: 0x%llx)\n", ZR_DEVNAME(zr), i, (unsigned long) mem, - virt_to_bus(mem)); + (unsigned long long)virt_to_bus(mem)); } else { #if defined(CONFIG_BIGPHYS_AREA) /* Use bigphysarea_alloc_pages */ -- cgit v1.2.3 From d5e10736ed6dd53b02e973042f407a3316c28533 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 12 Feb 2009 06:43:11 +0000 Subject: Added support for AVerMedia Cardbus Hybrid remote control MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From: Oldřich Jedlička Added support for I2C device at address 0x40 and subaddress 0x0d/0x0b that provides remote control key reading support for AVerMedia Cardbus Hybrid card, possibly for other AVerMedia Cardbus cards. The I2C address 0x40 doesn't like the SAA7134's 0xfd quirk, so it was disabled. Signed-off-by: Oldřich Jedlička [mchehab@redhat.com: CodingStyle fixes] Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/common/ir-keymaps.c | 59 +++++++++++++++++++++ linux/drivers/media/video/ir-kbd-i2c.c | 64 +++++++++++++++++++++++ linux/drivers/media/video/saa7134/saa7134-cards.c | 5 ++ linux/drivers/media/video/saa7134/saa7134-i2c.c | 2 +- linux/include/media/ir-common.h | 1 + 5 files changed, 130 insertions(+), 1 deletion(-) diff --git a/linux/drivers/media/common/ir-keymaps.c b/linux/drivers/media/common/ir-keymaps.c index 03fabc86c..827e65582 100644 --- a/linux/drivers/media/common/ir-keymaps.c +++ b/linux/drivers/media/common/ir-keymaps.c @@ -154,6 +154,65 @@ IR_KEYTAB_TYPE ir_codes_avermedia_m135a[IR_KEYTAB_SIZE] = { }; EXPORT_SYMBOL_GPL(ir_codes_avermedia_m135a); +/* Oldrich Jedlicka */ +IR_KEYTAB_TYPE ir_codes_avermedia_cardbus[IR_KEYTAB_SIZE] = { + [0x00] = KEY_POWER, + [0x01] = KEY_TUNER, /* TV/FM */ + [0x03] = KEY_TEXT, /* Teletext */ + [0x04] = KEY_EPG, + [0x05] = KEY_1, + [0x06] = KEY_2, + [0x07] = KEY_3, + [0x08] = KEY_AUDIO, + [0x09] = KEY_4, + [0x0a] = KEY_5, + [0x0b] = KEY_6, + [0x0c] = KEY_ZOOM, /* Full screen */ + [0x0d] = KEY_7, + [0x0e] = KEY_8, + [0x0f] = KEY_9, + [0x10] = KEY_PAGEUP, /* 16-CH PREV */ + [0x11] = KEY_0, + [0x12] = KEY_INFO, + [0x13] = KEY_AGAIN, /* CH RTN - channel return */ + [0x14] = KEY_MUTE, + [0x15] = KEY_EDIT, /* Autoscan */ + [0x17] = KEY_SAVE, /* Screenshot */ + [0x18] = KEY_PLAYPAUSE, + [0x19] = KEY_RECORD, + [0x1a] = KEY_PLAY, + [0x1b] = KEY_STOP, + [0x1c] = KEY_FASTFORWARD, + [0x1d] = KEY_REWIND, + [0x1e] = KEY_VOLUMEDOWN, + [0x1f] = KEY_VOLUMEUP, + [0x22] = KEY_SLEEP, /* Sleep */ + [0x23] = KEY_ZOOM, /* Aspect */ + [0x26] = KEY_SCREEN, /* Pos */ + [0x27] = KEY_ANGLE, /* Size */ + [0x28] = KEY_SELECT, /* Select */ + [0x29] = KEY_BLUE, /* Blue/Picture */ + [0x2a] = KEY_BACKSPACE, /* Back */ + [0x2b] = KEY_MEDIA, /* PIP (Picture-in-picture) */ + [0x2c] = KEY_DOWN, + [0x2e] = KEY_DOT, + [0x2f] = KEY_TV, /* Live TV */ + [0x32] = KEY_LEFT, + [0x33] = KEY_CLEAR, /* Clear */ + [0x35] = KEY_RED, /* Red/TV */ + [0x36] = KEY_UP, + [0x37] = KEY_HOME, /* Home */ + [0x39] = KEY_GREEN, /* Green/Video */ + [0x3d] = KEY_YELLOW, /* Yellow/Music */ + [0x3e] = KEY_OK, /* Ok */ + [0x3f] = KEY_RIGHT, + [0x40] = KEY_NEXT, /* Next */ + [0x41] = KEY_PREVIOUS, /* Previous */ + [0x42] = KEY_CHANNELDOWN, /* Channel down */ + [0x43] = KEY_CHANNELUP /* Channel up */ +}; +EXPORT_SYMBOL_GPL(ir_codes_avermedia_cardbus); + /* Attila Kondoros */ IR_KEYTAB_TYPE ir_codes_apac_viewcomp[IR_KEYTAB_SIZE] = { diff --git a/linux/drivers/media/video/ir-kbd-i2c.c b/linux/drivers/media/video/ir-kbd-i2c.c index a67bed7d7..a99aea49a 100644 --- a/linux/drivers/media/video/ir-kbd-i2c.c +++ b/linux/drivers/media/video/ir-kbd-i2c.c @@ -16,6 +16,8 @@ * Henry Wong * Mark Schultz * Brian Rogers + * modified for AVerMedia Cardbus by + * Oldrich Jedlicka * * 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 @@ -217,6 +219,46 @@ static int get_key_knc1(struct IR_i2c *ir, u32 *ir_key, u32 *ir_raw) return 1; } +static int get_key_avermedia_cardbus(struct IR_i2c *ir, + u32 *ir_key, u32 *ir_raw) +{ + unsigned char subaddr, key, keygroup; + struct i2c_msg msg[] = { { .addr = ir->c.addr, .flags = 0, + .buf = &subaddr, .len = 1}, + { .addr = ir->c.addr, .flags = I2C_M_RD, + .buf = &key, .len = 1} }; + subaddr = 0x0d; + if (2 != i2c_transfer(ir->c.adapter, msg, 2)) { + dprintk(1, "read error\n"); + return -EIO; + } + + if (key == 0xff) + return 0; + + subaddr = 0x0b; + msg[1].buf = &keygroup; + if (2 != i2c_transfer(ir->c.adapter, msg, 2)) { + dprintk(1, "read error\n"); + return -EIO; + } + + if (keygroup == 0xff) + return 0; + + dprintk(1, "read key 0x%02x/0x%02x\n", key, keygroup); + if (keygroup < 2 || keygroup > 3) { + /* Only a warning */ + dprintk(1, "warning: invalid key group 0x%02x for key 0x%02x\n", + keygroup, key); + } + key |= (keygroup & 1) << 6; + + *ir_key = key; + *ir_raw = key; + return 1; +} + /* ----------------------------------------------------------------------- */ static void ir_key_poll(struct IR_i2c *ir) @@ -369,6 +411,12 @@ static int ir_attach(struct i2c_adapter *adap, int addr, ir_type = IR_TYPE_OTHER; } break; + case 0x40: + name = "AVerMedia Cardbus remote"; + ir->get_key = get_key_avermedia_cardbus; + ir_type = IR_TYPE_OTHER; + ir_codes = ir_codes_avermedia_cardbus; + break; default: /* shouldn't happen */ printk(DEVNAME ": Huh? unknown i2c address (0x%02x)?\n", addr); @@ -537,6 +585,22 @@ static int ir_probe(struct i2c_adapter *adap) ir_attach(adap, msg.addr, 0, 0); } + /* Special case for AVerMedia Cardbus remote */ + if (adap->id == I2C_HW_SAA7134) { + unsigned char subaddr, data; + struct i2c_msg msg[] = { { .addr = 0x40, .flags = 0, + .buf = &subaddr, .len = 1}, + { .addr = 0x40, .flags = I2C_M_RD, + .buf = &data, .len = 1} }; + subaddr = 0x0d; + rc = i2c_transfer(adap, msg, 2); + dprintk(1, "probe 0x%02x/0x%02x @ %s: %s\n", + msg[0].addr, subaddr, adap->name, + (2 == rc) ? "yes" : "no"); + if (2 == rc) + ir_attach(adap, msg[0].addr, 0, 0); + } + return 0; } diff --git a/linux/drivers/media/video/saa7134/saa7134-cards.c b/linux/drivers/media/video/saa7134/saa7134-cards.c index e565d437b..9db045cf5 100644 --- a/linux/drivers/media/video/saa7134/saa7134-cards.c +++ b/linux/drivers/media/video/saa7134/saa7134-cards.c @@ -6120,6 +6120,11 @@ int saa7134_board_init1(struct saa7134_dev *dev) msleep(10); break; case SAA7134_BOARD_AVERMEDIA_CARDBUS_506: + saa7134_set_gpio(dev, 23, 0); + msleep(10); + saa7134_set_gpio(dev, 23, 1); + dev->has_remote = SAA7134_REMOTE_I2C; + break; case SAA7134_BOARD_AVERMEDIA_M103: saa7134_set_gpio(dev, 23, 0); msleep(10); diff --git a/linux/drivers/media/video/saa7134/saa7134-i2c.c b/linux/drivers/media/video/saa7134/saa7134-i2c.c index 4b4d5ef76..b77ccb5a0 100644 --- a/linux/drivers/media/video/saa7134/saa7134-i2c.c +++ b/linux/drivers/media/video/saa7134/saa7134-i2c.c @@ -260,7 +260,7 @@ static int saa7134_i2c_xfer(struct i2c_adapter *i2c_adap, addr = msgs[i].addr << 1; if (msgs[i].flags & I2C_M_RD) addr |= 1; - if (i > 0 && msgs[i].flags & I2C_M_RD) { + if (i > 0 && msgs[i].flags & I2C_M_RD && msgs[i].addr != 0x40) { /* workaround for a saa7134 i2c bug * needed to talk to the mt352 demux * thanks to pinnacle for the hint */ diff --git a/linux/include/media/ir-common.h b/linux/include/media/ir-common.h index 31e62abb5..135e02270 100644 --- a/linux/include/media/ir-common.h +++ b/linux/include/media/ir-common.h @@ -111,6 +111,7 @@ extern IR_KEYTAB_TYPE ir_codes_empty[IR_KEYTAB_SIZE]; extern IR_KEYTAB_TYPE ir_codes_avermedia[IR_KEYTAB_SIZE]; extern IR_KEYTAB_TYPE ir_codes_avermedia_dvbt[IR_KEYTAB_SIZE]; extern IR_KEYTAB_TYPE ir_codes_avermedia_m135a[IR_KEYTAB_SIZE]; +extern IR_KEYTAB_TYPE ir_codes_avermedia_cardbus[IR_KEYTAB_SIZE]; extern IR_KEYTAB_TYPE ir_codes_apac_viewcomp[IR_KEYTAB_SIZE]; extern IR_KEYTAB_TYPE ir_codes_pixelview[IR_KEYTAB_SIZE]; extern IR_KEYTAB_TYPE ir_codes_pixelview_new[IR_KEYTAB_SIZE]; -- cgit v1.2.3 From e63d9cf5d9e5f269f241490e6e190e8f4d92a5d0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 1 Feb 2009 22:31:54 +0000 Subject: DAB: fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From: Márton Németh Fix typo in "DAB adapters" section in Kconfig. Signed-off-by: Márton Németh Signed-off-by: Mauro Carvalho Chehab --- linux/drivers/media/Kconfig | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linux/drivers/media/Kconfig b/linux/drivers/media/Kconfig index 93ea201f4..223c36ede 100644 --- a/linux/drivers/media/Kconfig +++ b/linux/drivers/media/Kconfig @@ -117,7 +117,7 @@ source "drivers/media/dvb/Kconfig" config DAB boolean "DAB adapters" ---help--- - Allow selecting support for for Digital Audio Broadcasting (DAB) + Allow selecting support for Digital Audio Broadcasting (DAB) Receiver adapters. if DAB -- cgit v1.2.3 From 4b7ea770410dae8b9ca79623e4e36e94dfa86fd4 Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Mon, 2 Feb 2009 11:43:50 +0100 Subject: gspca - vc032x: Remove the vc0321 reset. From: Jean-Francois Moine Priority: normal Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/vc032x.c | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/linux/drivers/media/video/gspca/vc032x.c b/linux/drivers/media/video/gspca/vc032x.c index 1832d241f..72cbf56c9 100644 --- a/linux/drivers/media/video/gspca/vc032x.c +++ b/linux/drivers/media/video/gspca/vc032x.c @@ -2098,6 +2098,7 @@ static void usb_exchange(struct gspca_dev *gspca_dev, /*not reached*/ } +#if 0 static void vc0321_reset(struct gspca_dev *gspca_dev) { reg_w(gspca_dev->dev, 0xa0, 0x00, 0xb04d); @@ -2106,6 +2107,7 @@ static void vc0321_reset(struct gspca_dev *gspca_dev) reg_w(gspca_dev->dev, 0xa0, 0x01, 0xb003); msleep(100); } +#endif /* this function is called at probe time */ static int sd_config(struct gspca_dev *gspca_dev, @@ -2118,8 +2120,9 @@ static int sd_config(struct gspca_dev *gspca_dev, cam = &gspca_dev->cam; sd->bridge = id->driver_info; - +#if 0 vc0321_reset(gspca_dev); +#endif sensor = vc032x_probe_sensor(gspca_dev); switch (sensor) { case -1: -- cgit v1.2.3 From c1d676109e87244212120f7ba938d67c3d0571a0 Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Mon, 2 Feb 2009 20:25:38 +0100 Subject: gspca - some drivers: Fix compilation warnings. From: Jean-Francois Moine Priority: normal Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/mr97310a.c | 2 +- linux/drivers/media/video/gspca/sonixj.c | 2 +- linux/drivers/media/video/gspca/spca505.c | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/linux/drivers/media/video/gspca/mr97310a.c b/linux/drivers/media/video/gspca/mr97310a.c index 3a5ddff8f..5ec5ce6e3 100644 --- a/linux/drivers/media/video/gspca/mr97310a.c +++ b/linux/drivers/media/video/gspca/mr97310a.c @@ -73,7 +73,7 @@ static int reg_w(struct gspca_dev *gspca_dev, int len) rc = usb_bulk_msg(gspca_dev->dev, usb_sndbulkpipe(gspca_dev->dev, 4), - gspca_dev->usb_buf, len, 0, 500); + gspca_dev->usb_buf, len, NULL, 500); if (rc < 0) PDEBUG(D_ERR, "reg write [%02x] error %d", gspca_dev->usb_buf[0], rc); diff --git a/linux/drivers/media/video/gspca/sonixj.c b/linux/drivers/media/video/gspca/sonixj.c index 0aa4649bd..3be96d9f4 100644 --- a/linux/drivers/media/video/gspca/sonixj.c +++ b/linux/drivers/media/video/gspca/sonixj.c @@ -1031,7 +1031,7 @@ static void mi0360_probe(struct gspca_dev *gspca_dev) { struct sd *sd = (struct sd *) gspca_dev; int i, j; - u16 val; + u16 val = 0; static const u8 probe_tb[][4][8] = { { /* mi0360 */ {0xb0, 0x5d, 0x07, 0x00, 0x02, 0x00, 0x00, 0x10}, diff --git a/linux/drivers/media/video/gspca/spca505.c b/linux/drivers/media/video/gspca/spca505.c index 4fc54d8b8..2acec58b1 100644 --- a/linux/drivers/media/video/gspca/spca505.c +++ b/linux/drivers/media/video/gspca/spca505.c @@ -426,8 +426,8 @@ static const u8 spca505b_open_data_ccd[][3] = { {0x05, 0x00, 0x11}, {0x05, 0x00, 0x12}, {0x05, 0x6f, 0x00}, - {0x05, (u8) (initial_brightness >> 6), 0x00}, - {0x05, (u8) (initial_brightness << 2), 0x01}, + {0x05, initial_brightness >> 6, 0x00}, + {0x05, (initial_brightness << 2) & 0xff, 0x01}, {0x05, 0x00, 0x02}, {0x05, 0x01, 0x03}, {0x05, 0x00, 0x04}, @@ -560,8 +560,8 @@ static const u8 spca505b_open_data_ccd[][3] = { {0x06, 0x5f, 0x1f}, {0x06, 0x32, 0x20}, - {0x05, (u8) (initial_brightness >> 6), 0x00}, - {0x05, (u8) (initial_brightness << 2), 0x01}, + {0x05, initial_brightness >> 6, 0x00}, + {0x05, (initial_brightness << 2) & 0xff, 0x01}, {0x05, 0x06, 0xc1}, {0x05, 0x58, 0xc2}, {0x05, 0x00, 0xca}, -- cgit v1.2.3 From e086109f0cad2b76f5a32cf18db838e2026712bb Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Wed, 4 Feb 2009 19:33:21 +0100 Subject: gspca - main: Destroy the URBs at disconnection time. From: Adam Baker If a device using the gspca framework is unplugged while it is still streaming then the call that is used to free the URBs that have been allocated occurs after the pointer it uses becomes invalid at the end of gspca_disconnect. Make another cleanup call in gspca_disconnect while the pointer is still valid (multiple calls are OK as destroy_urbs checks for pointers already being NULL. Priority: high Signed-off-by: Adam Baker Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/gspca.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/linux/drivers/media/video/gspca/gspca.c b/linux/drivers/media/video/gspca/gspca.c index cac937040..64842682e 100644 --- a/linux/drivers/media/video/gspca/gspca.c +++ b/linux/drivers/media/video/gspca/gspca.c @@ -434,6 +434,7 @@ static void destroy_urbs(struct gspca_dev *gspca_dev) if (urb == NULL) break; + BUG_ON(!gspca_dev->dev); gspca_dev->urb[i] = NULL; if (!gspca_dev->present) usb_kill_urb(urb); @@ -1953,8 +1954,12 @@ void gspca_disconnect(struct usb_interface *intf) { struct gspca_dev *gspca_dev = usb_get_intfdata(intf); + mutex_lock(&gspca_dev->usb_lock); gspca_dev->present = 0; + mutex_unlock(&gspca_dev->usb_lock); + destroy_urbs(gspca_dev); + gspca_dev->dev = NULL; usb_set_intfdata(intf, NULL); /* release the device */ -- cgit v1.2.3 From 9ddff42d7f7354e47e024a3b71bb84cf04158ad9 Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Thu, 12 Feb 2009 12:05:45 +0100 Subject: gspca - main: More checks of the device disconnection. From: Jean-Francois Moine - prevent application oops when the device is disconnected - wake up the application at disconnection time - check the disconnection in ioctl dqbuf and poll Priority: high Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/gspca.c | 105 ++++++++++++++++++++++---------- 1 file changed, 74 insertions(+), 31 deletions(-) diff --git a/linux/drivers/media/video/gspca/gspca.c b/linux/drivers/media/video/gspca/gspca.c index 64842682e..8d78b9287 100644 --- a/linux/drivers/media/video/gspca/gspca.c +++ b/linux/drivers/media/video/gspca/gspca.c @@ -136,11 +136,13 @@ static void fill_frame(struct gspca_dev *gspca_dev, cam_pkt_op pkt_scan; if (urb->status != 0) { + if (urb->status == -ESHUTDOWN) + return; /* disconnection */ #ifdef CONFIG_PM if (!gspca_dev->frozen) #endif PDEBUG(D_ERR|D_PACK, "urb status: %d", urb->status); - return; /* disconnection ? */ + return; } pkt_scan = gspca_dev->sd_desc->pkt_scan; for (i = 0; i < urb->number_of_packets; i++) { @@ -220,6 +222,8 @@ static void bulk_irq(struct urb *urb) switch (urb->status) { case 0: break; + case -ESHUTDOWN: + return; /* disconnection */ case -ECONNRESET: urb->status = 0; break; @@ -228,7 +232,7 @@ static void bulk_irq(struct urb *urb) if (!gspca_dev->frozen) #endif PDEBUG(D_ERR|D_PACK, "urb status: %d", urb->status); - return; /* disconnection ? */ + return; } /* check the availability of the frame buffer */ @@ -434,10 +438,8 @@ static void destroy_urbs(struct gspca_dev *gspca_dev) if (urb == NULL) break; - BUG_ON(!gspca_dev->dev); gspca_dev->urb[i] = NULL; - if (!gspca_dev->present) - usb_kill_urb(urb); + usb_kill_urb(urb); if (urb->transfer_buffer != NULL) usb_buffer_free(gspca_dev->dev, urb->transfer_buffer_length, @@ -605,6 +607,11 @@ static int gspca_init_transfer(struct gspca_dev *gspca_dev) if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; + if (!gspca_dev->present) { + ret = -ENODEV; + goto out; + } + /* set the higher alternate setting and * loop until urb submit succeeds */ gspca_dev->alt = gspca_dev->nbalt; @@ -674,12 +681,14 @@ static int gspca_set_alt0(struct gspca_dev *gspca_dev) static void gspca_stream_off(struct gspca_dev *gspca_dev) { gspca_dev->streaming = 0; - if (gspca_dev->present - && gspca_dev->sd_desc->stopN) - gspca_dev->sd_desc->stopN(gspca_dev); - destroy_urbs(gspca_dev); - if (gspca_dev->present) + if (gspca_dev->present) { + if (gspca_dev->sd_desc->stopN) + gspca_dev->sd_desc->stopN(gspca_dev); + destroy_urbs(gspca_dev); gspca_set_alt0(gspca_dev); + } + + /* always call stop0 to free the subdriver's resources */ if (gspca_dev->sd_desc->stop0) gspca_dev->sd_desc->stop0(gspca_dev); PDEBUG(D_STREAM, "stream off OK"); @@ -961,8 +970,17 @@ static int vidioc_querycap(struct file *file, void *priv, struct v4l2_capability *cap) { struct gspca_dev *gspca_dev = priv; + int ret; memset(cap, 0, sizeof *cap); + + /* protect the access to the usb device */ + if (mutex_lock_interruptible(&gspca_dev->usb_lock)) + return -ERESTARTSYS; + if (!gspca_dev->present) { + ret = -ENODEV; + goto out; + } strncpy(cap->driver, gspca_dev->sd_desc->name, sizeof cap->driver); if (gspca_dev->dev->product != NULL) { strncpy(cap->card, gspca_dev->dev->product, @@ -978,7 +996,10 @@ static int vidioc_querycap(struct file *file, void *priv, cap->capabilities = V4L2_CAP_VIDEO_CAPTURE | V4L2_CAP_STREAMING | V4L2_CAP_READWRITE; - return 0; + ret = 0; +out: + mutex_unlock(&gspca_dev->usb_lock); + return ret; } static int vidioc_queryctrl(struct file *file, void *priv, @@ -1041,7 +1062,10 @@ static int vidioc_s_ctrl(struct file *file, void *priv, PDEBUG(D_CONF, "set ctrl [%08x] = %d", ctrl->id, ctrl->value); if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; - ret = ctrls->set(gspca_dev, ctrl->value); + if (gspca_dev->present) + ret = ctrls->set(gspca_dev, ctrl->value); + else + ret = -ENODEV; mutex_unlock(&gspca_dev->usb_lock); return ret; } @@ -1065,7 +1089,10 @@ static int vidioc_g_ctrl(struct file *file, void *priv, return -EINVAL; if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; - ret = ctrls->get(gspca_dev, &ctrl->value); + if (gspca_dev->present) + ret = ctrls->get(gspca_dev, &ctrl->value); + else + ret = -ENODEV; mutex_unlock(&gspca_dev->usb_lock); return ret; } @@ -1227,10 +1254,7 @@ static int vidioc_streamon(struct file *file, void *priv, return -EINVAL; if (mutex_lock_interruptible(&gspca_dev->queue_lock)) return -ERESTARTSYS; - if (!gspca_dev->present) { - ret = -ENODEV; - goto out; - } + if (gspca_dev->nframes == 0 || !(gspca_dev->frame[0].v4l2_buf.flags & V4L2_BUF_FLAG_QUEUED)) { ret = -EINVAL; @@ -1298,7 +1322,10 @@ static int vidioc_g_jpegcomp(struct file *file, void *priv, return -EINVAL; if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; - ret = gspca_dev->sd_desc->get_jcomp(gspca_dev, jpegcomp); + if (gspca_dev->present) + ret = gspca_dev->sd_desc->get_jcomp(gspca_dev, jpegcomp); + else + ret = -ENODEV; mutex_unlock(&gspca_dev->usb_lock); return ret; } @@ -1313,7 +1340,10 @@ static int vidioc_s_jpegcomp(struct file *file, void *priv, return -EINVAL; if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; - ret = gspca_dev->sd_desc->set_jcomp(gspca_dev, jpegcomp); + if (gspca_dev->present) + ret = gspca_dev->sd_desc->set_jcomp(gspca_dev, jpegcomp); + else + ret = -ENODEV; mutex_unlock(&gspca_dev->usb_lock); return ret; } @@ -1332,7 +1362,11 @@ static int vidioc_g_parm(struct file *filp, void *priv, if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; - ret = gspca_dev->sd_desc->get_streamparm(gspca_dev, parm); + if (gspca_dev->present) + ret = gspca_dev->sd_desc->get_streamparm(gspca_dev, + parm); + else + ret = -ENODEV; mutex_unlock(&gspca_dev->usb_lock); return ret; } @@ -1357,7 +1391,11 @@ static int vidioc_s_parm(struct file *filp, void *priv, if (mutex_lock_interruptible(&gspca_dev->usb_lock)) return -ERESTARTSYS; - ret = gspca_dev->sd_desc->set_streamparm(gspca_dev, parm); + if (gspca_dev->present) + ret = gspca_dev->sd_desc->set_streamparm(gspca_dev, + parm); + else + ret = -ENODEV; mutex_unlock(&gspca_dev->usb_lock); return ret; } @@ -1531,7 +1569,8 @@ static int frame_wait(struct gspca_dev *gspca_dev, if (gspca_dev->sd_desc->dq_callback) { mutex_lock(&gspca_dev->usb_lock); - gspca_dev->sd_desc->dq_callback(gspca_dev); + if (gspca_dev->present) + gspca_dev->sd_desc->dq_callback(gspca_dev); mutex_unlock(&gspca_dev->usb_lock); } return j; @@ -1553,6 +1592,9 @@ static int vidioc_dqbuf(struct file *file, void *priv, if (v4l2_buf->memory != gspca_dev->memory) return -EINVAL; + if (!gspca_dev->present) + return -ENODEV; + /* if not streaming, be sure the application will not loop forever */ if (!(file->f_flags & O_NONBLOCK) && !gspca_dev->streaming && gspca_dev->users == 1) @@ -1703,8 +1745,6 @@ static unsigned int dev_poll(struct file *file, poll_table *wait) PDEBUG(D_FRAM, "poll"); poll_wait(file, &gspca_dev->wq, wait); - if (!gspca_dev->present) - return POLLERR; /* if reqbufs is not done, the user would use read() */ if (gspca_dev->nframes == 0) { @@ -1717,10 +1757,6 @@ static unsigned int dev_poll(struct file *file, poll_table *wait) if (mutex_lock_interruptible(&gspca_dev->queue_lock) != 0) return POLLERR; - if (!gspca_dev->present) { - ret = POLLERR; - goto out; - } /* check the next incoming buffer */ i = gspca_dev->fr_o; @@ -1729,8 +1765,9 @@ static unsigned int dev_poll(struct file *file, poll_table *wait) ret = POLLIN | POLLRDNORM; /* something to read */ else ret = 0; -out: mutex_unlock(&gspca_dev->queue_lock); + if (!gspca_dev->present) + return POLLHUP; return ret; } @@ -1956,10 +1993,16 @@ void gspca_disconnect(struct usb_interface *intf) mutex_lock(&gspca_dev->usb_lock); gspca_dev->present = 0; - mutex_unlock(&gspca_dev->usb_lock); - destroy_urbs(gspca_dev); + if (gspca_dev->streaming) { + destroy_urbs(gspca_dev); + wake_up_interruptible(&gspca_dev->wq); + } + + /* the device is freed at exit of this function */ gspca_dev->dev = NULL; + mutex_unlock(&gspca_dev->usb_lock); + usb_set_intfdata(intf, NULL); /* release the device */ -- cgit v1.2.3 From 8d372d7b7fad4952e30da202fa0be5905382a8fd Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Thu, 5 Feb 2009 19:04:33 +0100 Subject: gspca - sonixj: No vertical flip control for mt9v111. From: Jean-Francois Moine Priority: normal Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/sonixj.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/linux/drivers/media/video/gspca/sonixj.c b/linux/drivers/media/video/gspca/sonixj.c index 3be96d9f4..6c5ec09a5 100644 --- a/linux/drivers/media/video/gspca/sonixj.c +++ b/linux/drivers/media/video/gspca/sonixj.c @@ -235,9 +235,9 @@ static __u32 ctrl_dis[] = { (1 << INFRARED_IDX) | (1 << VFLIP_IDX), /* SENSOR_MO4000 2 */ #if 1 - 0, + (1 << VFLIP_IDX), #else - (1 << AUTOGAIN_IDX), + (1 << AUTOGAIN_IDX) | (1 << VFLIP_IDX), #endif /* SENSOR_MT9V111 3 */ (1 << INFRARED_IDX) | (1 << VFLIP_IDX), -- cgit v1.2.3 From 1aa4c1b8e3ab0204e2985d4a13d81379b5fb7b02 Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Thu, 5 Feb 2009 19:12:24 +0100 Subject: gspca - sonixj: Add autogain for ov7630/48 and vflip for ov7648. From: Jean-Francois Moine Priority: normal Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/sonixj.c | 43 ++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/linux/drivers/media/video/gspca/sonixj.c b/linux/drivers/media/video/gspca/sonixj.c index 6c5ec09a5..5cdb643b8 100644 --- a/linux/drivers/media/video/gspca/sonixj.c +++ b/linux/drivers/media/video/gspca/sonixj.c @@ -45,7 +45,7 @@ struct sd { u8 blue; u8 red; u8 gamma; - u8 vflip; /* ov7630 only */ + u8 vflip; /* ov7630/ov7648 only */ u8 infrared; /* mt9v111 only */ s8 ag_cnt; @@ -192,7 +192,7 @@ static struct ctrl sd_ctrls[] = { .set = sd_setautogain, .get = sd_getautogain, }, -/* ov7630 only */ +/* ov7630/ov7648 only */ #define VFLIP_IDX 6 { { @@ -202,7 +202,7 @@ static struct ctrl sd_ctrls[] = { .minimum = 0, .maximum = 1, .step = 1, -#define VFLIP_DEF 1 +#define VFLIP_DEF 0 /* vflip def = 1 for ov7630 */ .default_value = VFLIP_DEF, }, .set = sd_setvflip, @@ -244,7 +244,7 @@ static __u32 ctrl_dis[] = { /* SENSOR_OM6802 4 */ (1 << AUTOGAIN_IDX) | (1 << INFRARED_IDX), /* SENSOR_OV7630 5 */ - (1 << AUTOGAIN_IDX) | (1 << INFRARED_IDX) | (1 << VFLIP_IDX), + (1 << INFRARED_IDX), /* SENSOR_OV7648 6 */ (1 << AUTOGAIN_IDX) | (1 << INFRARED_IDX) | (1 << VFLIP_IDX), /* SENSOR_OV7660 7 */ @@ -677,7 +677,8 @@ static const u8 ov7648_sensor_init[][8] = { {0xb1, 0x21, 0x2d, 0x85, 0x00, 0x00, 0x00, 0x10}, /*...*/ /* {0xa1, 0x21, 0x12, 0x08, 0x00, 0x00, 0x00, 0x10}, jfm done */ -/* {0xa1, 0x21, 0x75, 0x06, 0x00, 0x00, 0x00, 0x10}, jfm done */ +/* {0xa1, 0x21, 0x75, 0x06, 0x00, 0x00, 0x00, 0x10}, * COMN + * set by setvflip */ {0xa1, 0x21, 0x19, 0x02, 0x00, 0x00, 0x00, 0x10}, {0xa1, 0x21, 0x10, 0x32, 0x00, 0x00, 0x00, 0x10}, /* {0xa1, 0x21, 0x16, 0x00, 0x00, 0x00, 0x00, 0x10}, jfm done */ @@ -1319,7 +1320,10 @@ static int sd_config(struct gspca_dev *gspca_dev, sd->gamma = GAMMA_DEF; sd->autogain = AUTOGAIN_DEF; sd->ag_cnt = -1; - sd->vflip = VFLIP_DEF; + if (sd->sensor != SENSOR_OV7630) + sd->vflip = 0; + else + sd->vflip = 1; sd->infrared = INFRARED_DEF; gspca_dev->ctrl_dis = ctrl_dis[sd->sensor]; @@ -1589,16 +1593,39 @@ static void setautogain(struct gspca_dev *gspca_dev) if (gspca_dev->ctrl_dis & (1 << AUTOGAIN_IDX)) return; + switch (sd->sensor) { + case SENSOR_OV7630: + case SENSOR_OV7648: { + u8 comb; + + if (sd->sensor == SENSOR_OV7630) + comb = 0xc0; + else + comb = 0xa0; + if (sd->autogain) + comb |= 0x02; + i2c_w1(&sd->gspca_dev, 0x13, comb); + return; + } + } if (sd->autogain) sd->ag_cnt = AG_CNT_START; else sd->ag_cnt = -1; } +/* ov7630/ov7648 only */ static void setvflip(struct sd *sd) { - i2c_w1(&sd->gspca_dev, 0x75, /* COMN */ - sd->vflip ? 0x82 : 0x02); + u8 comn; + + if (sd->sensor == SENSOR_OV7630) + comn = 0x02; + else + comn = 0x06; + if (sd->vflip) + comn |= 0x80; + i2c_w1(&sd->gspca_dev, 0x75, comn); } static void setinfrared(struct sd *sd) -- cgit v1.2.3 From 891ac17d7e12b75ddf21bea407b502569f94bb3e Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Fri, 6 Feb 2009 17:45:23 +0100 Subject: gspca - t613: Bad sensor name in kernel trace when 'other' sensor. From: Jean-Francois Moine Priority: normal Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/t613.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/linux/drivers/media/video/gspca/t613.c b/linux/drivers/media/video/gspca/t613.c index adec0767c..1b0fc86c4 100644 --- a/linux/drivers/media/video/gspca/t613.c +++ b/linux/drivers/media/video/gspca/t613.c @@ -685,7 +685,7 @@ static int sd_init(struct gspca_dev *gspca_dev) sd->sensor = SENSOR_TAS5130A; break; case 0x0803: - PDEBUG(D_CONF, "sensor om6802"); + PDEBUG(D_CONF, "sensor 'other'"); sd->sensor = SENSOR_OTHER; break; case 0x0807: -- cgit v1.2.3 From a50f33bc015e6def039a24ead62b4e32d76d44e6 Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Fri, 6 Feb 2009 18:11:58 +0100 Subject: gspca - t613: Bad debug level when displaying the sensor type. From: Jean-Francois Moine Priority: normal Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/t613.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/linux/drivers/media/video/gspca/t613.c b/linux/drivers/media/video/gspca/t613.c index 1b0fc86c4..4891592ea 100644 --- a/linux/drivers/media/video/gspca/t613.c +++ b/linux/drivers/media/video/gspca/t613.c @@ -681,19 +681,19 @@ static int sd_init(struct gspca_dev *gspca_dev) | reg_r(gspca_dev, 0x07); switch (sensor_id) { case 0x0801: - PDEBUG(D_CONF, "sensor tas5130a"); + PDEBUG(D_PROBE, "sensor tas5130a"); sd->sensor = SENSOR_TAS5130A; break; case 0x0803: - PDEBUG(D_CONF, "sensor 'other'"); + PDEBUG(D_PROBE, "sensor 'other'"); sd->sensor = SENSOR_OTHER; break; case 0x0807: - PDEBUG(D_CONF, "sensor om6802"); + PDEBUG(D_PROBE, "sensor om6802"); sd->sensor = SENSOR_OM6802; break; default: - PDEBUG(D_CONF, "unknown sensor %04x", sensor_id); + PDEBUG(D_ERR|D_PROBE, "unknown sensor %04x", sensor_id); return -EINVAL; } -- cgit v1.2.3 From 9e943ca0c659d66896f55dcfa1280f1d22556e78 Mon Sep 17 00:00:00 2001 From: Jean-Francois Moine Date: Fri, 6 Feb 2009 19:12:46 +0100 Subject: gspca - sq905: New subdriver. From: Adam Baker Add initial support for cameras based on the SQ Technologies SQ-905 chipset (USB ID 2770:9120) to V4L2 using the gspca infrastructure. Currently only supports one resolution and doesn't attempt to inform libv4l what image flipping options are needed. Priority: normal Signed-off-by: Adam Baker Signed-off-by: Theodore Kilgore Signed-off-by: Jean-Francois Moine --- linux/drivers/media/video/gspca/Kconfig | 9 + linux/drivers/media/video/gspca/Makefile | 2 + linux/drivers/media/video/gspca/sq905.c | 438 +++++++++++++++++++++++++++++++ 3 files changed, 449 insertions(+) create mode 100644 linux/drivers/media/video/gspca/sq905.c diff --git a/linux/drivers/media/video/gspca/Kconfig b/linux/drivers/media/video/gspca/Kconfig index 11c5d2fc2..a0f05ef5c 100644 --- a/linux/drivers/media/video/gspca/Kconfig +++ b/linux/drivers/media/video/gspca/Kconfig @@ -176,6 +176,15 @@ config USB_GSPCA_SPCA561 To compile this driver as a module, choose M here: the module will be called gspca_spca561. +config USB_GSPCA_SQ905 + tristate "SQ Technologies SQ905 based USB Camera Driver" + depends on VIDEO_V4L2 && USB_GSPCA + help + Say Y here if you want support for cameras based on the SQ905 chip. + + To compile this driver as a module, choose M here: the + module will be called gspca_sq905. + config USB_GSPCA_STK014 tristate "Syntek DV4000 (STK014) USB Camera Driver" depends on VIDEO_V4L2 && USB_GSPCA diff --git a/linux/drivers/media/video/gspca/Makefile b/linux/drivers/media/video/gspca/Makefile index b3cbcc176..b6ec61185 100644 --- a/linux/drivers/media/video/gspca/Makefile +++ b/linux/drivers/media/video/gspca/Makefile @@ -16,6 +16,7 @@ obj-$(CONFIG_USB_GSPCA_SPCA505) += gspca_spca505.o obj-$(CONFIG_USB_GSPCA_SPCA506) += gspca_spca506.o obj-$(CONFIG_USB_GSPCA_SPCA508) += gspca_spca508.o obj-$(CONFIG_USB_GSPCA_SPCA561) += gspca_spca561.o +obj-$(CONFIG_USB_GSPCA_SQ905) += gspca_sq905.o obj-$(CONFIG_USB_GSPCA_SUNPLUS) += gspca_sunplus.o obj-$(CONFIG_USB_GSPCA_STK014) += gspca_stk014.o obj-$(CONFIG_USB_GSPCA_T613) += gspca_t613.o @@ -41,6 +42,7 @@ gspca_spca505-objs := spca505.o gspca_spca506-objs := spca506.o gspca_spca508-objs := spca508.o gspca_spca561-objs := spca561.o +gspca_sq905-objs := sq905.o gspca_stk014-objs := stk014.o gspca_sunplus-objs := sunplus.o gspca_t613-objs := t613.o diff --git a/linux/drivers/media/video/gspca/sq905.c b/linux/drivers/media/video/gspca/sq905.c new file mode 100644 index 000000000..dafaed69e --- /dev/null +++ b/linux/drivers/media/video/gspca/sq905.c @@ -0,0 +1,438 @@ +/* + * SQ905 subdriver + * + * Copyright (C) 2008, 2009 Adam Baker and Theodore Kilgore + * + * 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 + * 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 + */ + +/* + * History and Acknowledgments + * + * The original Linux driver for SQ905 based cameras was written by + * Marcell Lengyel and furter developed by many other contributers + * and is available from http://sourceforge.net/projects/sqcam/ + * + * This driver takes advantage of the reverse engineering work done for + * that driver and for libgphoto2 but shares no code with them. + * + * This driver has used as a base the finepix driver and other gspca + * based drivers and may still contain code fragments taken from those + * drivers. + */ + +#define MODULE_NAME "sq905" + +#include +#include "gspca.h" + +MODULE_AUTHOR("Adam Baker , " + "Theodore Kilgore "); +MODULE_DESCRIPTION("GSPCA/SQ905 USB Camera Driver"); +MODULE_LICENSE("GPL"); + +/* Default timeouts, in ms */ +#define SQ905_CMD_TIMEOUT 500 +#define SQ905_DATA_TIMEOUT 1000 + +/* Maximum transfer size to use. */ +#define SQ905_MAX_TRANSFER 0x8000 +#define FRAME_HEADER_LEN 64 + +/* The known modes, or registers. These go in the "value" slot. */ + +/* 00 is "none" obviously */ + +#define SQ905_BULK_READ 0x03 /* precedes any bulk read */ +#define SQ905_COMMAND 0x06 /* precedes the command codes below */ +#define SQ905_PING 0x07 /* when reading an "idling" command */ +#define SQ905_READ_DONE 0xc0 /* ack bulk read completed */ + +/* Some command codes. These go in the "index" slot. */ + +#define SQ905_ID 0xf0 /* asks for model string */ +#define SQ905_CONFIG 0x20 /* gets photo alloc. table, not used here */ +#define SQ905_DATA 0x30 /* accesses photo data, not used here */ +#define SQ905_CLEAR 0xa0 /* clear everything */ +#define SQ905_CAPTURE_LOW 0x60 /* Starts capture at 160x120 */ +#define SQ905_CAPTURE_MED 0x61 /* Starts capture at 320x240 */ +/* note that the capture command also controls the output dimensions */ +/* 0x60 -> 160x120, 0x61 -> 320x240 0x62 -> 640x480 depends on camera */ +/* 0x62 is not correct, at least for some cams. Should be 0x63 ? */ + +/* Structure to hold all of our device specific stuff */ +struct sd { + struct gspca_dev gspca_dev; /* !! must be the first item */ + + u8 cam_type; + + /* + * Driver stuff + */ + struct work_struct work_struct; + struct workqueue_struct *work_thread; +}; + +/* The driver only supports 320x240 so far. */ +static struct v4l2_pix_format sq905_mode[1] = { + { 320, 240, V4L2_PIX_FMT_SBGGR8, V4L2_FIELD_NONE, + .bytesperline = 320, + .sizeimage = 320 * 240, + .colorspace = V4L2_COLORSPACE_SRGB, + .priv = 0} +}; + +struct cam_type { + u32 ident_word; + char *name; + struct v4l2_pix_format *min_mode; + u8 num_modes; + u8 sensor_flags; +}; + +#define SQ905_FLIP_HORIZ (1 << 0) +#define SQ905_FLIP_VERT (1 << 1) + +/* Last entry is default if nothing else matches */ +static struct cam_type cam_types[] = { + { 0x19010509, "PocketCam", &sq905_mode[0], 1, SQ905_FLIP_HORIZ }, + { 0x32010509, "Magpix", &sq905_mode[0], 1, SQ905_FLIP_HORIZ }, + { 0, "Default", &sq905_mode[0], 1, SQ905_FLIP_HORIZ | SQ905_FLIP_VERT } +}; + +/* + * Send a command to the camera. + */ +static int sq905_command(struct gspca_dev *gspca_dev, u16 index) +{ + int ret; + + gspca_dev->usb_buf[0] = '\0'; + ret = usb_control_msg(gspca_dev->dev, + usb_sndctrlpipe(gspca_dev->dev, 0), + USB_REQ_SYNCH_FRAME, /* request */ + USB_DIR_OUT | USB_TYPE_VENDOR | USB_RECIP_DEVICE, + SQ905_COMMAND, index, gspca_dev->usb_buf, 1, + SQ905_CMD_TIMEOUT); + if (ret < 0) { + PDEBUG(D_ERR, "%s: usb_control_msg failed (%d)", + __func__, ret); + return ret; + } + + ret = usb_control_msg(gspca_dev->dev, + usb_sndctrlpipe(gspca_dev->dev, 0), + USB_REQ_SYNCH_FRAME, /* request */ + USB_DIR_IN | USB_TYPE_VENDOR | USB_RECIP_DEVICE, + SQ905_PING, 0, gspca_dev->usb_buf, 1, + SQ905_CMD_TIMEOUT); + if (ret < 0) { + PDEBUG(D_ERR, "%s: usb_control_msg failed 2 (%d)", + __func__, ret); + return ret; + } + + return 0; +} + +/* + * Acknowledge the end of a frame - see warning on sq905_command. + */ +static int sq905_ack_frame(struct gspca_dev *gspca_dev) +{ + int ret; + + gspca_dev->usb_buf[0] = '\0'; + ret = usb_control_msg(gspca_dev->dev, + usb_sndctrlpipe(gspca_dev->dev, 0), + USB_REQ_SYNCH_FRAME, /* request */ + USB_DIR_OUT | USB_TYPE_VENDOR | USB_RECIP_DEVICE, + SQ905_READ_DONE, 0, gspca_dev->usb_buf, 1, + SQ905_CMD_TIMEOUT); + if (ret < 0) { + PDEBUG(D_ERR, "%s: usb_control_msg failed (%d)", __func__, ret); + return ret; + } + + return 0; +} + +/* + * request and read a block of data - see warning on sq905_command. + */ +static int +sq905_read_data(struct gspca_dev *gspca_dev, u8 *data, int size) +{ + int ret; + int act_len; + + gspca_dev->usb_buf[0] = '\0'; + ret = usb_control_msg(gspca_dev->dev, + usb_sndctrlpipe(gspca_dev->dev, 0), + USB_REQ_SYNCH_FRAME, /* request */ + USB_DIR_OUT | USB_TYPE_VENDOR | USB_RECIP_DEVICE, + SQ905_BULK_READ, size, gspca_dev->usb_buf, + 1, SQ905_CMD_TIMEOUT); + if (ret < 0) { + PDEBUG(D_ERR, "%s: usb_control_msg failed (%d)", __func__, ret); + return ret; + } + ret = usb_bulk_msg(gspca_dev->dev, + usb_rcvbulkpipe(gspca_dev->dev, 0x81), + data, size, &act_len, SQ905_DATA_TIMEOUT); + + /* successful, it returns 0, otherwise negative */ + if (ret < 0 || act_len != size) { + PDEBUG(D_ERR, "bulk read fail (%d) len %d/%d", + ret, act_len, size); + return -EIO; + } + return 0; +} + +/* This function is called as a workqueue function and runs whenever the camera + * is streaming data. Because it is a workqueue function it is allowed to sleep + * so we can use synchronous USB calls. To avoid possible collisions with other + * threads attempting to use the camera's USB interface we take the gspca + * usb_lock when performing USB operations. In practice the only thing we need + * to protect against is the usb_set_interface call that gspca makes during + * stream_off as the camera doesn't provide any controls that the user could try + * to change. + */ +static void sq905_dostream(struct work_struct *work) +{ + struct sd *dev = container_of(work, struct sd, work_struct); + struct gspca_dev *gspca_dev = &dev->gspca_dev; + struct gspca_frame *frame; + int bytes_left; /* bytes remaining in current frame. */ + int data_len; /* size to use for the next read. */ + int header_read; /* true if we have already read the frame header. */ + int discarding; /* true if we failed to get space for frame. */ + int packet_type; + int ret; + u8 *data; + u8 *buffer; + + buffer = kmalloc(SQ905_MAX_TRANSFER, GFP_KERNEL | GFP_DMA); + mutex_lock(&gspca_dev->usb_lock); + if (!buffer) { + PDEBUG(D_ERR, "Couldn't allocate USB buffer"); + goto quit_stream; + } + + while (gspca_dev->present && gspca_dev->streaming) { + /* Need a short delay to ensure streaming flag was set by + * gspca and to make sure gspca can grab the mutex. */ + mutex_unlock(&gspca_dev->usb_lock); + msleep(1); + + /* request some data and then read it until we have + * a complete frame. */ + bytes_left = sq905_mode[0].sizeimage + FRAME_HEADER_LEN; + header_read = 0; + discarding = 0; + + while (bytes_left > 0) { + data_len = bytes_left > SQ905_MAX_TRANSFER ? + SQ905_MAX_TRANSFER : bytes_left; + mutex_lock(&gspca_dev->usb_lock); + if (!gspca_dev->present) + goto quit_stream; + ret = sq905_read_data(gspca_dev, buffer, data_len); + if (ret < 0) + goto quit_stream; + mutex_unlock(&gspca_dev->usb_lock); + PDEBUG(D_STREAM, + "Got %d bytes out of %d for frame", + data_len, bytes_left); + bytes_left -= data_len; + data = buffer; + if (!header_read) { + packet_type = FIRST_PACKET; + /* The first 64 bytes of each frame are + * a header full of FF 00 bytes */ + data += FRAME_HEADER_LEN; + data_len -= FRAME_HEADER_LEN; + header_read = 1; + } else if (bytes_left == 0) { + packet_type = LAST_PACKET; + } else { + packet_type = INTER_PACKET; + } + frame = gspca_get_i_frame(gspca_dev); + if (frame && !discarding) + gspca_frame_add(gspca_dev, packet_type, + frame, data, data_len); + else + discarding = 1; + } + /* acknowledge the frame */ + mutex_lock(&gspca_dev->usb_lock); + if (!gspca_dev->present) + goto quit_stream; + ret = sq905_ack_frame(gspca_dev); + if (ret < 0) + goto quit_stream; + } +quit_stream: + /* the usb_lock is already acquired */ + if (gspca_dev->present) + sq905_command(gspca_dev, SQ905_CLEAR); + mutex_unlock(&gspca_dev->usb_lock); + kfree(buffer); +} + +/* This function is called at probe time just before sd_init */ +static int sd_config(struct gspca_dev *gspca_dev, + const struct usb_device_id *id) +{ + struct cam *cam = &gspca_dev->cam; + struct sd *dev = (struct sd *) gspca_dev; + + cam->cam_mode = sq905_mode; + cam->nmodes = 1; + /* We don't use the buffer gspca allocates so make it small. */ + cam->bulk_size = 64; + + INIT_WORK(&dev->work_struct, sq905_dostream); + + return 0; +} + +/* called on streamoff with alt==0 and on disconnect */ +/* the usb_lock is held at entry - restore on exit */ +static void sd_stop0(struct gspca_dev *gspca_dev) +{ + struct sd *dev = (struct sd *) gspca_dev; + + /* wait for the work queue to terminate */ + mutex_unlock(&gspca_dev->usb_lock); + /* This waits for sq905_dostream to finish */ + destroy_workqueue(dev->work_thread); + dev->work_thread = NULL; + mutex_lock(&gspca_dev->usb_lock); +} + +/* this function is called at probe and resume time */ +static int sd_init(struct gspca_dev *gspca_dev) +{ + struct sd *dev = (struct sd *) gspca_dev; + u32 ident; + int ret; + + /* connect to the camera and read + * the model ID and process that and put it away. + */ + ret = sq905_command(gspca_dev, SQ905_CLEAR); + if (ret < 0) + return ret; + ret = sq905_command(gspca_dev, SQ905_ID); + if (ret < 0) + return ret; + ret = sq905_read_data(gspca_dev, gspca_dev->usb_buf, 4); + if (ret < 0) + return ret; + /* usb_buf is allocated with kmalloc so is aligned. */ + ident = le32_to_cpup((u32 *)gspca_dev->usb_buf); + ret = sq905_command(gspca_dev, SQ905_CLEAR); + if (ret < 0) + return ret; + dev->cam_type = 0; + while (dev->cam_type < ARRAY_SIZE(cam_types) - 1 && + ident != cam_types[dev->cam_type].ident_word) + dev->cam_type++; + PDEBUG(D_CONF, "SQ905 camera %s, ID %08x detected", + cam_types[dev->cam_type].name, ident); + return 0; +} + +/* Set up for getting frames. */ +static int sd_start(struct gspca_dev *gspca_dev) +{ + struct sd *dev = (struct sd *) gspca_dev; + int ret; + + /* "Open the shutter" and set size, to start capture */ + ret = sq905_command(&dev->gspca_dev, SQ905_CAPTURE_MED); + if (ret < 0) { + PDEBUG(D_ERR, "Start streaming command failed"); + return ret; + } + + /* Start the workqueue function to do the streaming */ + dev->work_thread = create_singlethread_workqueue(MODULE_NAME); + queue_work(dev->work_thread, &dev->work_struct); + + return 0; +} + +/* Table of supported USB devices */ +static const __devinitdata struct usb_device_id device_table[] = { + {USB_DEVICE(0x2770, 0x9120)}, + {} +}; + +MODULE_DEVICE_TABLE(usb, device_table); + +/* sub-driver description */ +static const struct sd_desc sd_desc = { + .name = MODULE_NAME, + .config = sd_config, + .init = sd_init, + .start = sd_start, + .stop0 = sd_stop0, +}; + +/* -- device connect -- */ +static int sd_probe(struct usb_interface *intf, + const struct usb_device_id *id) +{ + return gspca_dev_probe(intf, id, + &sd_desc, + sizeof(struct sd), + THIS_MODULE); +} + +static struct usb_driver sd_driver = { + .name = MODULE_NAME, + .id_table = device_table, + .probe = sd_probe, + .disconnect = gspca_disconnect, +#ifdef CONFIG_PM + .suspend = gspca_suspend, + .resume = gspca_resume, +#endif +}; + +/* -- module insert / remove -- */ +static int __init sd_mod_init(void) +{ + int ret; + + ret = usb_register(&sd_driver); + if (ret < 0) + return ret; + PDEBUG(D_PROBE, "registered"); + return 0; +} + +static void __exit sd_mod_exit(void) +{ + usb_deregister(&sd_driver); + PDEBUG(D_PROBE, "deregistered"); +} + +module_init(sd_mod_init); +module_exit(sd_mod_exit); -- cgit v1.2.3 From b598952580418f91c7bd0dc9d42802a052e84a6e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 17 Feb 2009 10:11:12 -0300 Subject: backport include changes on some .h files From: Mauro Carvalho Chehab kernel-sync: Signed-off-by: Mauro Carvalho Chehab --- linux/include/linux/dvb/audio.h | 5 ----- linux/include/linux/dvb/dmx.h | 2 +- linux/include/linux/dvb/frontend.h | 3 +-- linux/include/linux/dvb/net.h | 3 +-- linux/include/linux/dvb/video.h | 7 ++----- linux/include/linux/video_decoder.h | 2 ++ linux/include/linux/videodev.h | 1 + linux/include/media/videobuf-dma-sg.h | 2 +- 8 files changed, 9 insertions(+), 16 deletions(-) diff --git a/linux/include/linux/dvb/audio.h b/linux/include/linux/dvb/audio.h index 89412e18f..bb0df2aae 100644 --- a/linux/include/linux/dvb/audio.h +++ b/linux/include/linux/dvb/audio.h @@ -24,12 +24,7 @@ #ifndef _DVBAUDIO_H_ #define _DVBAUDIO_H_ -#ifdef __KERNEL__ #include -#else -#include -#endif - typedef enum { AUDIO_SOURCE_DEMUX, /* Select the demux as the main source */ diff --git a/linux/include/linux/dvb/dmx.h b/linux/include/linux/dvb/dmx.h index 402fb7a8d..fef943738 100644 --- a/linux/include/linux/dvb/dmx.h +++ b/linux/include/linux/dvb/dmx.h @@ -24,7 +24,7 @@ #ifndef _DVBDMX_H_ #define _DVBDMX_H_ -#include +#include #ifdef __KERNEL__ #include #else diff --git a/linux/include/linux/dvb/frontend.h b/linux/include/linux/dvb/frontend.h index 61a86e720..6a0405f65 100644 --- a/linux/include/linux/dvb/frontend.h +++ b/linux/include/linux/dvb/frontend.h @@ -26,8 +26,7 @@ #ifndef _DVBFRONTEND_H_ #define _DVBFRONTEND_H_ -#include - +#include typedef enum fe_type { FE_QPSK, diff --git a/linux/include/linux/dvb/net.h b/linux/include/linux/dvb/net.h index 5be474bf0..f451e7eb0 100644 --- a/linux/include/linux/dvb/net.h +++ b/linux/include/linux/dvb/net.h @@ -24,8 +24,7 @@ #ifndef _DVBNET_H_ #define _DVBNET_H_ -#include - +#include struct dvb_net_if { __u16 pid; diff --git a/linux/include/linux/dvb/video.h b/linux/include/linux/dvb/video.h index 50839fe9e..bd49c3ebf 100644 --- a/linux/include/linux/dvb/video.h +++ b/linux/include/linux/dvb/video.h @@ -24,17 +24,14 @@ #ifndef _DVBVIDEO_H_ #define _DVBVIDEO_H_ -#include - -#ifdef __KERNEL__ #include +#ifdef __KERNEL__ +#include #else -#include #include #include #endif - typedef enum { VIDEO_FORMAT_4_3, /* Select 4:3 format */ VIDEO_FORMAT_16_9, /* Select 16:9 format. */ diff --git a/linux/include/linux/video_decoder.h b/linux/include/linux/video_decoder.h index 121e26da2..e26c0c86a 100644 --- a/linux/include/linux/video_decoder.h +++ b/linux/include/linux/video_decoder.h @@ -1,6 +1,8 @@ #ifndef _LINUX_VIDEO_DECODER_H #define _LINUX_VIDEO_DECODER_H +#include + #define HAVE_VIDEO_DECODER 1 struct video_decoder_capability { /* this name is too long */ diff --git a/linux/include/linux/videodev.h b/linux/include/linux/videodev.h index 15a653d41..837f392fb 100644 --- a/linux/include/linux/videodev.h +++ b/linux/include/linux/videodev.h @@ -12,6 +12,7 @@ #ifndef __LINUX_VIDEODEV_H #define __LINUX_VIDEODEV_H +#include #include #include diff --git a/linux/include/media/videobuf-dma-sg.h b/linux/include/media/videobuf-dma-sg.h index 90edd22d3..dda47f008 100644 --- a/linux/include/media/videobuf-dma-sg.h +++ b/linux/include/media/videobuf-dma-sg.h @@ -49,7 +49,7 @@ struct scatterlist* videobuf_pages_to_sg(struct page **pages, int nr_pages, * does memory allocation too using vmalloc_32(). * * videobuf_dma_*() - * see Documentation/DMA-mapping.txt, these functions to + * see Documentation/PCI/PCI-DMA-mapping.txt, these functions to * basically the same. The map function does also build a * scatterlist for the buffer (and unmap frees it ...) * -- cgit v1.2.3