diff options
Diffstat (limited to 'dvb-spec/API/dvb_api/demux_mod.xml')
| -rw-r--r-- | dvb-spec/API/dvb_api/demux_mod.xml | 1215 |
1 files changed, 0 insertions, 1215 deletions
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 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"> -<html><head><title> - linuxtv.org|DVB Demux Kernel API</title></head><body -bgcolor="#000000" link="#ffcc00" text="#ffffff" vlink="#ffdd00"><table -border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td><table -border="0" cellpadding="0" cellspacing="0" width="100%"><tr><td -width="610"><table border="0" cellpadding="0" cellspacing="0"><tr -valign="top"><td><table border="0" cellpadding="0" cellspacing="0" -width="180"><tr align="right" valign="top"><td><img height="30" -src="/images/top01.gif" width="180"></td></tr><tr><td align="center" -height="38" valign="bottom"><img border="0" height="38" -src="/images/cimlogo02.gif" width="45"></td></tr></table></td><td><table -border="0" cellpadding="0" cellspacing="0" width="50"><tr><td><img -height="30" src="/images/top02.gif" width="284"></td></tr><tr><td><img -height="45" src="/images/top06.gif" width="20"> - - </td></tr></table></td><td><table border="0" cellpadding="0" -cellspacing="0" width="170"><tr><td background="/images/squares05.gif" -colspan="2"><img height="68" src="/images/squares04.gif" -width="32"></td></tr></table></td></tr><tr><td></td></tr></table></td><td -height="68" valign="top" width="100%"><table border="0" cellpadding="0" -cellspacing="0" width="100%"><tr><td background="/images/squares05.gif" -height="68" -width="100%"> </td></tr></table></td></tr></table></td></tr><tr><td height="30"> - - </td></tr></table><table border="0" cellpadding="0" -cellspacing="0"><tr><td width="181"><table border="0" cellpadding="0" -cellspacing="0" width="181"><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gruen.gif" width="20"></td><td -bgcolor="#003d19" valign="top" width="19"><img height="22" -src="/images/pfeilgruen.gif" width="19"></td><td bgcolor="#000000" -valign="top" width="2"></td><td bgcolor="#003d19" width="120"><a -href="http://www.convergence.de"><font color="#ffcc00" -face="arial, helvetica" size="2"><b> - convergence.de - </b></font></a></td><td align="right" bgcolor="#003d19" -valign="bottom" width="20"><img height="22" -src="/images/eckeswgruen.gif" width="8"></td></tr><tr><td -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gruen.gif" width="20"></td><td -bgcolor="#003d19" valign="top" width="19"><img height="22" -src="/images/pfeilgruen.gif" width="19"></td><td bgcolor="#000000" -valign="top" width="2"></td><td bgcolor="#003d19" width="120"><a -href="http://www.cryptolabs.org"><font color="#ffcc00" -face="arial, helvetica" size="2"><b> - cryptolabs.org</b></font></a></td><td align="right" -bgcolor="#003d19" valign="bottom" width="20"><img height="22" -src="/images/eckeswgruen.gif" width="8"></td></tr><tr><td -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gruen.gif" width="20"></td><td -bgcolor="#003d19" valign="top" width="19"><img height="22" -src="/images/pfeilgruen.gif" width="19"></td><td bgcolor="#000000" -valign="top" width="2"></td><td bgcolor="#003d19" width="120"><a -href="http://www.directfb.org"><font color="#ffcc00" -face="arial, helvetica" size="2"><b> - directfb.org - </b></font></a></td><td align="right" bgcolor="#003d19" -valign="bottom" width="20"><img height="22" -src="/images/eckeswgruen.gif" width="8"></td></tr><tr><td -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gleb.gif" width="20"></td><td -bgcolor="#ffcc00" valign="top" width="19"><img height="22" -src="/images/pfeilgelb.gif" width="19"></td><td bgcolor="#000000" -valign="top" width="2"></td><td bgcolor="#ffcc00" width="120"><a -href="/"><font color="#003d19" face="arial, helvetica" size="2"><b> - linuxtv.org - </b></font></a></td><td align="right" bgcolor="#ffcc00" -valign="bottom" width="20"><img height="22" src="/images/eckeswgelb.gif" -width="8"></td></tr><tr><td height="2"></td></tr></table></td><td width="20"> - - </td><td valign="top" width="500"><img height="60" -src="/images/linuxtv.gif" width="245"></td></tr><tr><td align="left" -valign="top" width="181"><table bgcolor="#ffcc00" border="0" -cellpadding="0" cellspacing="0" width="185"><tr><td bgcolor="#000000" -valign="top" width="20"><img height="22" src="/images/gleb.gif" -width="20"></td><td bgcolor="#ffcc00" width="19"><img height="22" -src="/images/arrow_main.gif" width="19"></td><td bgcolor="#000000" -width="2"></td><td bgcolor="#ffcc00" width="131"> - <a href="/"><font color="#003d19" face="helvetica" -size="2"><b>linuxtv</b></font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" colspan="5" -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gleb.gif" width="20"></td><td -bgcolor="#ffcc00" width="19"><img height="22" -src="/images/arrow_main.gif" width="19"></td><td bgcolor="#000000" -width="2"></td><td bgcolor="#ffcc00" width="131"> - <a href="/projects.xml"><font color="#003d19" face="helvetica" -size="2"><b>projects</b></font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" colspan="5" -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gleb.gif" width="20"></td><td -bgcolor="#ffcc00" width="19"><img height="22" -src="/images/arrow_main_open.gif" width="19"></td><td bgcolor="#000000" -width="2"></td><td bgcolor="#ffcc00" width="131"> - <a href="/developer/"><font color="#003d19" face="helvetica" -size="2"><b>developer</b></font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" width="20"></td><td -bgcolor="#ffcc00" width="19"> </td><td bgcolor="#000000" -width="2"></td><td width="131"><img height="13" -src="/images/arrow_sub_open.gif" width="13"> - <a href="/developer/dvb.xml"><font color="#000000" -face="helvetica" size="2">DVB</font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" width="20"></td><td -width="19"> </td><td bgcolor="#000000" width="2"></td><td width="131"> - <img height="13" src="/images/space_sub.gif" width="13"><img -height="13" src="/images/kulleropen.gif" width="13"><a -href="/developer/dvb_api.xml"><font color="#000000" face="helvetica" size="2"> - API</font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" width="20"></td><td -bgcolor="#ffcc00" width="19"> </td><td bgcolor="#000000" -width="2"></td><td width="131"><img height="13" -src="/images/arrow_sub.gif" width="13"> - <a href="/developer/dvd.xml"><font color="#000000" -face="helvetica" size="2">DVD</font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" width="20"></td><td -bgcolor="#ffcc00" width="19"> </td><td bgcolor="#000000" -width="2"></td><td width="131"><img height="13" -src="/images/arrow_sub.gif" width="13"> - <a href="/developer/mbone.xml"><font color="#000000" -face="helvetica" size="2">Mbone</font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" width="20"></td><td -bgcolor="#ffcc00" width="19"> </td><td bgcolor="#000000" -width="2"></td><td width="131"><img height="13" -src="/images/arrow_sub.gif" width="13"> - <a href="/cvs/"><font color="#000000" face="helvetica" -size="2">CVS</font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" colspan="5" -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gleb.gif" width="20"></td><td -bgcolor="#ffcc00" width="19"><img height="22" -src="/images/arrow_main.gif" width="19"></td><td bgcolor="#000000" -width="2"></td><td bgcolor="#ffcc00" width="131"> - <a href="/download/"><font color="#003d19" face="helvetica" -size="2"><b>download</b></font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" colspan="5" -height="2"></td></tr><tr><td bgcolor="#000000" valign="top" -width="20"><img height="22" src="/images/gleb.gif" width="20"></td><td -bgcolor="#ffcc00" width="19"><img height="22" -src="/images/arrow_main.gif" width="19"></td><td bgcolor="#000000" -width="2"></td><td bgcolor="#ffcc00" width="131"> - <a href="/contact.xml"><font color="#003d19" face="helvetica" -size="2"><b>contact</b></font></a></td><td bgcolor="#000000" -width="9"></td></tr><tr><td bgcolor="#000000" colspan="5" -height="2"></td></tr></table></td><td width="20"> - - </td><td valign="top" width="500"><font color="#ffcc00" face="arial, helvetica"><h2>DVB Demux Kernel API</h2></font> - - <p> - The demux kernel API gives access to the demuxer of the DVB hardware - to other kernel modules which implement devices like the - <a href="demux.xml">demux device</a> or generic DVB network devices. - </p> - - <p> - The function calls defined in the include file - <a href="demux.h">demux.h</a> are described in detail below: - </p> - - <p> - <font face="arial, helvetica" size="+1">Demux Directory API</font> - - <p> - 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. - </p> - <p> - All demux drivers in the directory implement the abstract interface dmx_demux_t. - </p> - -<p> -<pre> -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. - - - -</pre> -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -</p> - - -<p> -<font face="arial, helvetica" size="+1">Demux API</font> -<p> - 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. -</p> -<p> - 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. -</p> -<p> - 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". -</p> -<p> - 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. -</p> -<p> - 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. -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -<p> -<pre> -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. - -</pre> -</p> -<p> -<pre> -allocate_pes_feed() - - TBD - - - -</pre> -</p> -<p> -<pre> -release_pes_feed() - - TBD - - - -</pre> -</p> -<p> -<pre> -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. - -</pre> -</p> -<p> -<pre> - -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. - - -</pre> -</p> -<p> -<pre> - -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. - - - - -</pre> -</p> -<p> -<pre> - -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. - - -</pre> -</p> -<p> -<pre> - -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. - -</pre> -</p> -<p> -<pre> - -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(). - - -</pre> -</p> -<p> -<pre> - -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. - -</pre> -</p> -<p> -<pre> - -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. - -</pre> -</p> -<p> -<pre> - -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. - - -</pre> -</p> -</p> - -<p> -<font face="arial, helvetica" size="+1">Demux Callback API</font> -<p> - 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. -</p> -<p> - 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. -</p> -<p> - 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. - -</p> -<p> -<pre> -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. - - - -</pre> -</p> -<p> -<pre> - -dmx_pes_cb() - - TBD - -</pre> -</p> -<p> -<pre> - -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. - -</pre> -</p> - -</p> - -<p> -<font face="arial, helvetica" size="+1">TS Feed API</font> -<p> - 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. -</p> -<p> - 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. -</p> -<p> -<pre> - -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. - -</pre> -</p> -<p> -<pre> - -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. - - -</pre> -</p> -<p> -<pre> - -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. - - - -</pre> -</p> -</p> - -<p> -<font face="arial, helvetica" size="+1">PES Feed API</font> -<p> - TBD -</p> -</p> - -<p> -<font face="arial, helvetica" size="+1">Section Feed API</font> -<p> - 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. -</p> -<p> - 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. -</p> - -<p> -<pre> - -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. - -</pre> -</p> -<p> -<pre> - -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. - -</pre> -</p> -<p> -<pre> -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. - -</pre> -</p> -<p> -<pre> -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. - -</pre> -</p> -<p> -<pre> -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. - - - -</pre> -</p> - </p> - </td></tr></table></body></html> - -<!-- This page was served in 2918 milliseconds by Cocoon 1.7.4 --> |