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

8.4.1. dmx_ts_cb()

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.

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.

SYNOPSIS

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

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.

RETURNS

0

Continue filtering.

-1

Stop filtering - has the same effect as a call to stop_filtering() on the TS Feed API.

8.4.2. dmx_section_cb()

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

SYNOPSIS

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);

PARAMETERS

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

RETURNS

0

Continue filtering.

-1

Stop filtering - has the same effect as a call to stop_filtering() on the Section Feed API.