source: svn/newcon3bcm2_21bu/nexus/app/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 "bapp_types.h"

/***************************************************************************
Summary:
message stream handle.
SeeAlso:
None
***************************************************************************/
typedef struct smessage_stream * smessage_stream_t;
/***************************************************************************
Summary:
        Section filter structure, See register reference for typical use with
        Broadcom chips.
***************************************************************************/
typedef struct smessage_filter {
        uint8_t mask[16];       /* Bits to be ignored. See Description. */
        uint8_t coef[16];       /* Bits to be included. See Description. */
        uint8_t excl[16];       /* Bits to be excluded. Doesn't apply to Venom2 platforms. See Description. */
} smessage_filter;

/***************************************************************************
Summary:
Message capture format enumeration. Following formats are supported:

smessage_format_ts - capture raw ts data in to circular buffer
smessage_format_tsc - capture ts data in to provided buffer with callback
smessage_format_psi - capture psi sections in to provided buffer with callback

Circular buffer for raw ts capture is allocated internaly by the module, in 
case of smessage_format_tsc and smessage_format_psi buffer must be allocated by
caller and pointer provided as part of smessage_stream_params_t structure.
SeeAlso:
smessage_open
***************************************************************************/
typedef enum smessage_format_t {
    smessage_format_ts,
    smessage_format_tsc,
    smessage_format_psi
} smessage_format;

/***************************************************************************
Summary:
Message callback type.
Description:
Application must provide function of this type to be called when message is
captured by message filters. This is the only way for application to obtain
the message.
After this call is called messages no longer will be captured by this filter
unless callback returns non NULL pointer. User must stop and restart
filter to resume message capture.
User can not call any smessage_* api from this callback or deadlock will 
result. This callback is called directly from the filter task and it must 
return fast. Delaying return from callback will adversly impact message filter
performance and may result in overflow for all other filters. If user 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 callback message filtering 
will stop for this filter. If non NULL pointer is returned filtering will 
continue in to the buffer pointed by this pointed.
Input:
context - user context provided when message capture is started.
data_size - size of message captured in the provided buffer.
Returns:
New buffer pointer to use for next message capture or NULL if no more messages
should be captured and operation of filter should be suspended. If filter
should continue to capture messages in to old buffer, callback should return 
same pointer that was originally passed to the start function. Size of the new
buffer must be same or larger than the size of the buffer passed in to the 
smessage_start function.
SeeAlso:
smessage_stream_params_t
***************************************************************************/
typedef void * (*smessage_callback)(void * context, size_t data_size);

/***************************************************************************
Summary: 
Invalid pid channel definition.
Description:
Constant signifying that this pid channel is invalid and defaul algorithm
for choosing pid channel should be used by mesage filter.
***************************************************************************/
#define SMESSAGE_INVALID_CHANNEL (0xffff)

/***************************************************************************
Summary: 
Parameters for smessage_start function
Description:
Structure providing parameters for the smessage_start function.

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

SeeAlso:
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;

/***************************************************************************
Summary:
Initialize message subsystem.
Description:
Initialize message subsystem. No other funtions can be called before this 
function is called or results of other function calls are undefined.
Input:
decode_cfgs - decoder configuration.
Returns:
b_ok if success, error code otherwise.
SeeAlso:
None
***************************************************************************/
bresult smessage_init(void *ctx);

/***************************************************************************
Summary:
Initialise parameters with default values.
Description:
Initialise parameters with default values.
Input:
params - parameter structure to fill with default values.
stream - stream for which to fill the structure.
Returns:
None
SeeAlso:
None
***************************************************************************/
void smessage_stream_params_init( smessage_stream_params_t *params, smessage_stream_t stream);

/***************************************************************************
Summary:
Open message with desired format.
Description:
This call returns message handle which obtained from internal list. Be sure to
call smessage_close after handle is no longer needed. Failing to do so will 
result in memory leak and running out of handles.
Input:
format - desired format for the message capture.
Returns:
smessage_stream_t handle or NULL if the call fails.
SeeAlso:
smessage_close
***************************************************************************/
smessage_stream_t smessage_open(smessage_format format);

/***************************************************************************
Summary:
Start message capture.
Description:
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.
Input:
params - parameters for message capture
stream - stream handle for which to start capture.
Returns:
b_ok if capture was started, error code otherwise.
SeeAlso:
smessage_stop, smessage_stream_params_init
***************************************************************************/
bresult smessage_start(const smessage_stream_params_t * params, smessage_stream_t stream);

/***************************************************************************
Summary:
Stop message capture.
Description:
Stop message capture and if possible free internal hardware and software
resources.
Input:
stream - stream for which to stop message capture.
Returns:
b_ok if capture was stopped, error code otherwise.
SeeAlso:
smessage_stop
***************************************************************************/
bresult smessage_stop(smessage_stream_t stream);

/***************************************************************************
Summary:
Close message capture for given stream.
Description:
Close message capture for given stream and return stream to the list of free
streams. Usaer 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.
Input:
stream - stream handle to free.
Returns:
None
SeeAlso:
smessage_open
***************************************************************************/
void smessage_close(smessage_stream_t stream);

/***************************************************************************
Summary:
Get circular buffer pointer for the stream capture buffer.
Description:
Get circular buffer pointer for the stream capture buffer. This call is valid
only for some types of message capture and using it for any other type will
result in error.
Input:
stream - desired stream handle
pbuffer - pointer to the pointer to buffer. After function returns this 
          variable will contain pointer to the start of avaiable data.
plength - pointer to the length of the data. After function returns this
variable will contain lenth of the valid data in the buffer.
Returns:
b_ok if call was successful error otherwise. If error is retured values of 
*pbuffer and *plength are not defined and should be discarded.
SeeAlso:
smessage_read_complete, smessage_start
***************************************************************************/
bresult smessage_get_buffer(smessage_stream_t stream, const void ** pbuffer, size_t * plength);

/***************************************************************************
Summary:
Notify circular buffer about amount of comsumed data.
Description:
Notify circular buffer about amount of consumed data and advance read pointer.
This call is valid only for some types of message capture and using it for any
other type will result in error. Attempt to consume more data that is avalable
in the circular buffer will result in error.
Input:
stream - desired stream handle
consumed - amount of data that was consumed. Read pointer will be advanced by
that amount.
Returns:
b_ok if call was successful error otherwise. 
SeeAlso:
smessage_get_buffer, smessage_start
***************************************************************************/
bresult smessage_read_complete(smessage_stream_t stream, size_t consumed);

#endif /*__BSETTOP_SMESSAGE_H__*/