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

/***************************************************************************
 *     Copyright (c) 2012, 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_amessage.h $
 * $brcm_Revision: $
 * $brcm_Date: $
 *
 * Module Description:
 *      Message filtering and raw ATM packet capture api.
 * Revision History:
 *
 * $brcm_Log: $
 * 
 *
 ***************************************************************************/

#ifndef __BSETTOP_AMESSAGE_H__
#define __BSETTOP_AMESSAGE_H__

#include "bsettop_types.h"

/** \file bsettop_amessage.h 
 This file defines interfaces for PSI section filtering. Main difference between
 this one and smessage is that is the message comes from SCTE 55-2 (ATM cell).
 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 amessage_stream * amessage_stream_t;

/** \struct amessage_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 amessage_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 amessage_filter::coef
 Coefficient bits to be compared against the PSI message data.
*/
/** \var amessage_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 amessage_filter {
        uint8_t mask[16];
        uint8_t coef[16];
        uint8_t excl[16];
} amessage_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 amessage_* 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 amessage_start function.

@see amessage_stream_params_t
*/
typedef void * (*amessage_callback)(void * context, size_t data_size);

/**
Parameters for the amessage_start function.

Structure for providing parameters to the amessage_start function.

@param band - parser band
@param vpi - vpi for ATM packet filter
@param vci - vci for ATM packet filter
@param filter - message filter
@param buffer - buffer for complete message
@param buffer_size - size of the buffer
@param hec_disabled - disable ATM HEC checking, HEC 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, vpi, vci, buffer_size, hec_disabled. All other parameters are ignored.

@see amessage_stream_params_init, amessage_start
*/
typedef struct amessage_stream_params_tag {
    bband_t band;
        uint8_t  vpi;
        uint16_t  vci;
    amessage_filter filter;
    void * buffer;
    size_t buffer_size;
    bool hec_disabled;
    amessage_callback data_ready_callback;
    amessage_callback overflow;
    void * callback_context;
    void * priv;
} amessage_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.

@return b_ok if success, error code otherwise.
*/
bresult amessage_init(void);

/**
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 amessage_open call.

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

@see amessage_open
*/
void amessage_stream_params_init( amessage_stream_params_t *params, amessage_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 amessage_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 amessage_stream_t handle or NULL if the call fails.

@see amessage_close
*/
amessage_stream_t amessage_open(void);

/**
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 amessage_stop, amessage_stream_params_init
*/
bresult amessage_start(const amessage_stream_params_t * params, amessage_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 amessage_stop
*/
bresult amessage_stop(amessage_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 amessage_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 amessage_open
*/
void amessage_close(amessage_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 amessage_read_complete, amessage_start
*/
bresult amessage_get_buffer(amessage_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 amessage_get_buffer, amessage_start
*/
bresult amessage_read_complete(amessage_stream_t stream, size_t consumed);


#endif /*__BSETTOP_AMESSAGE_H__*/