source: svn/trunk/newcon3bcm2_21bu/dta/src/settop_api/bsettop_smessage.h

/***************************************************************************
 *     Copyright (c) 2003-2006, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: bsettop_smessage.h $
 * $brcm_Revision: $
 * $brcm_Date: $
 *
 * Module Description:
 * Message filtering and raw ts capture api. Note inconsistent naming of 
 * types and members in the structures. It was done in attempt to preserve
 * similarity with bsettop_message.h api.
 * Revision History:
 *
 * $brcm_Log: $
 * 
 *
 ***************************************************************************/

#ifndef __BSETTOP_SMESSAGE_H__
#define __BSETTOP_SMESSAGE_H__

#include "bsettop_types.h"

/** \file bsettop_smessage.h 
 This file defines interfaces for PSI section filtering.
 The DTA PSI filtering works differently than the hardware PSI filtering
 in settop api and nexus. The DTA PSI filters are combination of the software
 filtering with the hardware assist. For performance and efficiency reasons
 the sections are filtered in to the application supplied buffer instead of per
 filter circular buffer as it happens with the hardware implementation. This
 allows application to immediately start processing the data and avoid an 
 extra copying operation.
 The caller allocates a buffer, capable of containing maximum expected
 section size. If the caller does not know expected section size, buffer size
 should be 1K for standard sections and 4 K for private sections.
 The caller then would initialize the section filtering api, fill the parameter
 structure and start the section filtering.
 When any of the filters match a section, the section filtering api will copy 
 this section in to the caller supplied buffer and if required would verify the
 CRC. When the section is completely received and the CRC is verified, the
 section filtering code will invoke the caller supplied callback. In the 
 callback the caller can process section data and chose to continue filtering
 or choose to stop filtering sections.
 */

/**
   Message stream handle.
   This handle is returned by the open call and used in all subsequent
   calls to control the psi interface functionality.
*/
typedef struct smessage_stream * smessage_stream_t;

/** \typedef smessage_format
Message capture format enumeration. Following formats are supported: 
smessage_format_ts, smessage_format_tsc, smessage_format_psi.
Circular buffer for raw ts capture is allocated internally by the module, in 
case of smessage_format_tsc and smessage_format_psi, a buffer must be allocated
by the caller and a pointer provided as part of the smessage_stream_params_t
structure.
@see smessage_open
*/
/** \var smessage_format::smessage_format_ts
capture raw ts data in to circular buffer.
*/
/** \var enum smessage_format_t::smessage_format_tsc
capture ts data in to provided buffer with callback
*/
/** \var enum smessage_format_t::smessage_format_psi
capture psi sections in to provided buffer with callback
*/
typedef enum smessage_format_t {
    smessage_format_ts,
    smessage_format_tsc,
    smessage_format_psi
} smessage_format;

/** \struct smessage_filter
Structure that is used to specify a PSI filter.

All filtering is done using bit by bit comparisons.
There are two types of masks that are used in conjunction with the coefficient.
inclusion mask (mask) - for all inclusion mask bits that are unmasked
                (set to 0) ALL of the corresponding bits in the
                message must match the bits specified by the coef in order to
                                be included. If one bit differs, it will be excluded.

exclusion mask (excl) - for all exclusion mask bits that are unmasked
                (set to 0) at least one of the corresponding bits
                in the message must NOT match the bits specified
                by the coef in order to be included. If all of the bits
                                match, it will be excluded.
Results from both comparisons are AND'd together to form the final pass/fail decision.
Exception: Currently for MPEG2 streams, byte 2 (i.e. the message length field)
of the filter and the MPEG2 message data is ignored.
*/
/** \var smessage_filter::mask
 Any bit of the mask that is set to 0 will allow the corresponding bit of the 
 coefficient to be compared against the PSI message data.
*/
/** \var smessage_filter::coef
 Coefficient bits to be compared against the PSI message data.
*/
/** \var smessage_filter::excl
 Any bit of the exclusion that is set to 0 will allow the corresponding bit
 of the coefficient to be compared against the PSI message data.
*/
typedef struct smessage_filter {
        uint8_t mask[16];
        uint8_t coef[16];
        uint8_t excl[16];
} smessage_filter;

/**
Section callback type.

The caller must provide a function of this type to be called when the section 
is captured by the section filters. This is the only way for a caller to obtain
the section.
After this call is called sections are longer will be captured by this filter
unless the callback returns non NULL pointer. User must stop and restart
the filter to resume the section capture.

\warning User can not call any smessage_* api from this callback such call
will result in a deadlock.

 This callback is called directly from the filter task and it
must return fast. Delaying return from the callback will adversely impact 
the message filter performance and may result in overflow for all the other
filters. If caller has to do substantial work he must convey the information
to another task and do the work in another context. If NULL is returned by
the callback message filtering will stop for this filter. If non NULL pointer
is returned filtering will continue in to the buffer pointed by this pointer.

@param context - user context provided when message capture was started.
@param data_size - size of message captured in the provided buffer.
@return 
New buffer pointer to use for the next section capture or NULL if no more
sections should be captured and operation of the filter should be suspended.
If the filter should continue to capture sections in to the old buffer, the 
callback should return the same pointer that was originally passed to the 
start function. Size of the new buffer must be the same or larger than the
size of the buffer passed in to the smessage_start function.

@see smessage_stream_params_t
*/
typedef void * (*smessage_callback)(void * context, size_t data_size);

/**
Invalid pid channel definition.

Constant signifying that this pid channel is invalid and the default algorithm
for choosing the pid channel should be used by the section filter.
*/
#define SMESSAGE_INVALID_CHANNEL (0xffff)

/**
Parameters for the smessage_start function.

Structure for providing parameters to the smessage_start function.

@param band - parser band
@param pid - pid to filter on
@param pid_channel - optional pid channel supplied by the caller. This field
is set to SMESSAGE_INVALID_CHANNEL by smessage_stream_params_init function. If 
the user does not change this field, the message filter will allocate a pid
channel internally, else it will use the value provided in this field.
@param filter - message filter
@param buffer - buffer for complete message
@param buffer_size - size of the buffer
@param crc_disabled - disable crc checking, crc checking enabled by default.
@param data_ready_callback - notification callback invoked when message is captured.
@param overflow - notification callback invoked when overflow happens.

Only following parameters are used when stream is captured in to circular 
buffer - band, pid, pid_channel, buffer_size. All other parameters are ignored.

@see smessage_stream_params_init, smessage_start
*/
typedef struct smessage_stream_params_tag {
    bband_t band;
    uint16_t pid;
    uint16_t pid_channel;
    smessage_filter filter;
    void * buffer;
    size_t buffer_size;
    bool crc_disabled;
    smessage_callback data_ready_callback;
    smessage_callback overflow;
    void * callback_context;
    void * priv;
} smessage_stream_params_t;

/**
Initialize the message subsystem.
No other functions can be called before this function is called or results
of other function calls are undefined.

@param decode_cfgs - decoder configuration.
@return b_ok if success, error code otherwise.
*/
bresult smessage_init(void *decode_cfgs);

/**
Initialize parameters with default values.

This function will fill the given structure with the default values that are
appropriate for the message stream type. This function must be called before
setting up the parameter structure for the smessage_open call.

@param params - parameter structure to fill with the default values.
@param stream - stream for which to fill the structure.

@see smessage_open
*/
void smessage_stream_params_init( smessage_stream_params_t *params, smessage_stream_t stream);

/**
Open message with the desired format.

This call returns the message handle which is obtained from the internal list.
Be sure to call smessage_close after the handle is no longer needed. Failing
to do so will result in memory leak and running out of handles.

@param format - desired format for the message capture.
@return smessage_stream_t handle or NULL if the call fails.

@see smessage_close
*/
smessage_stream_t smessage_open(smessage_format format);

/**
Start message capture.

This call will start message filtering. When message is captured it will be
copied in to the provided buffer and callback will be called. After message is
captured this filter will be disabled if NULL is returned by callback. If 
caller desires to continue message filtering, callback should return a pointer
to the buffer in which to capture next message.
If message callback returns NULL and user wants to resume filtering, message
filter should be stopped and restarted with new parameters by calling this
api again.
This call will start capture and immediately return.

@param params - parameters for message capture
@param stream - stream handle for which to start capture.

@return b_ok if capture was started, error code otherwise.

@see smessage_stop, smessage_stream_params_init
*/
bresult smessage_start(const smessage_stream_params_t * params, smessage_stream_t stream);

/**
Stop message capture.
Stop capture and if possible free internal hardware and software
resources.

@param stream - stream for which to stop message capture.

@return b_ok if capture was stopped, error code otherwise.

@see smessage_stop
*/
bresult smessage_stop(smessage_stream_t stream);

/**
Close message capture for given stream.

Close message capture for given stream and return stream to the list of free
streams. User must call smessage_stop before calling this api and user must 
call this api if he no longer needs stream handle. If this api is not called
stream handle will be leaked and eventually system will run out of stream 
handles as they are limited.

@param stream - stream handle to free.

@see smessage_open
*/
void smessage_close(smessage_stream_t stream);

/**
Get circular buffer pointer for the stream capture buffer.
Get the pointer to the start of unread data in the circular buffer. This call
is valid only for some types of message capture and using it for any other
type will result in error.

@param stream - desired stream handle
@param pbuffer - pointer to the pointer to buffer. After the function returns
this variable will contain the pointer to the start of the available data.
@param plength - pointer to the length of the data. After function returns this
variable will contain length of the valid data in the buffer.

@return b_ok if call was successful error otherwise. If error is returned 
values of *pbuffer and *plength are not defined and should be discarded.

@see smessage_read_complete, smessage_start
*/
bresult smessage_get_buffer(smessage_stream_t stream, const void ** pbuffer, size_t * plength);

/**
Notify circular buffer about amount of consumed data.

Notify the circular buffer about amount of the consumed data and advance the
read pointer. This call is valid only for some types of the message capture 
and using it for any other type will result in error. Attempt to consume more
data that is available in the circular buffer will result in error.

@param stream - desired stream handle
@param consumed - amount of data that was consumed. Read pointer will be advanced by
that amount.

@return b_ok if call was successful error otherwise. 

@see smessage_get_buffer, smessage_start
*/
bresult smessage_read_complete(smessage_stream_t stream, size_t consumed);


#endif /*__BSETTOP_SMESSAGE_H__*/