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, 1215 insertions, 0 deletions
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 @@ +<!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 --> |