/*
 * scemi.h
 *
 * This file is the header file for the SCEMI C API.  
 */
#ifndef INCLUDED_SCEMI
#define INCLUDED_SCEMI

typedef void SceMi;
typedef void SceMiParameters;
typedef void SceMiMessageData;
typedef void SceMiMessageInPortProxy;
typedef void SceMiMessageOutPortProxy;

#include "scemicommontypes.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Register an error handler which is called in the event
 * that an error occurs.  If no handler is registered, the
 * default error handler is called.  The errorHandler will
 * pass back the 'context' object registered by the user
 * when making this function call.  The system makes no
 * assumptions about the 'context' pointer and will not
 * modify it.
 */
void
SceMiRegisterErrorHandler(
    SceMiErrorHandler errorHandler,
    void* context);

/*
 * Register an info handler which is called in the event
 * that an informational text message needs to be printed.
 * If no handler is registered, the message is printed to stdout.
 */
void SceMiRegisterInfoHandler(
    SceMiInfoHandler infoHandler,
    void* context );

/*
 * Check version string against supported versions.
 * Return -1 if passed string not supported.
 * Return interface version # if it is supported. This interface
 * version # can be passed to the SceMiInit() function.
 */
int
SceMiVersion(
    const char* versionString);

/*
 * This function wraps constructor of class SceMi.  If an instance
 * of class SceMi has been established on a prior call to the
 * the SceMiInit() function, that pointer is returned since a single
 * instance of class SceMi is reusable among all C models.
 *
 * The caller must provide the interface version # it is expecting
 * to work with.  If the caller requests an unsupported version,
 * an error is returned.
 *
 * The caller must also provide a pointer to a filled-in SceMiParameters
 * struct that contains global interface specification parameters.
 *
 * Returns NULL if error occurred, check ec for status or register
 * an error callback.
 */
SceMi* 
SceMiInit(
    int version,
    const SceMiParameters* parameters,
    SceMiEC* ec);

/*
 * Shut down the specified SCEMI interface.
 */
void
SceMiShutdown(
    SceMi* mctHandle,
    SceMiEC* ec);

/*
 * Create proxy for message input port.
 *
 * The caller must provide the handle to the initialized SceMi system,
 * as well as the name of the transactor and port to which binding
 * is requested.
 *
 * The 'binding' input is a callback function and context pointer tray.
 * See the comments in scemitypes.h for struct SceMiMessageInPortBinding.
 */
SceMiMessageInPortProxy*
SceMiBindMessageInPort(
    SceMi* mctHandle,
    const char* transactorName,
    const char* portName,
    const SceMiMessageInPortBinding* binding,
    SceMiEC* ec);

/*
 * Create proxy for message output port.
 *
 * The caller must provide the handle to the initialized SceMi system,
 * as well as the name of the transactor and port to which binding
 * is requested.
 *
 * The 'binding' input is a callback function and context pointer tray.
 * See the comments in scemitypes.h for struct SceMiMessageOutPortBinding.
 */
SceMiMessageOutPortProxy*
SceMiBindMessageOutPort(
    SceMi* mctHandle,
    const char* transactorName,
    const char* portName,
    const SceMiMessageOutPortBinding* binding,
    SceMiEC* ec);

/*
 * Service arriving transactions from the portal.
 * Messages enqueued by SceMiMessageOutPortProxy methods, or which are
 * are from output transactions that pending dispatch to the
 * SceMiMessageOutPortProxy callbacks, may not be handled until
 * ServiceLoop() is called.  This function returns the # of output
 * messages that were dispatched.
 *
 * The 'g' input is a pointer to a user-defined service function.
 * If g is NULL, check for transfers to be performed and
 * dispatch them returning immediately afterwards.  If g is
 * non-NULL, enter into a loop of performing transfers and
 * calling 'g'.  When 'g' returns 0 return from the loop.
 * When 'g' is called, an indication of whether there is at
 * least 1 message pending will be made with the 'pending' flag.
 *
 * The 'context' input is a user context object pointer.
 * This pointer is uninterpreted by the SceMiServiceLoop() 
 * method and is passed on to the 'g' callback function.
 */
int
SceMiServiceLoop(
    SceMi* mctHandle,
    SceMiServiceLoopHandler g,
    void* context,
    SceMiEC* ec);
 

SceMiParameters*
SceMiParametersNew(
    const char* paramsFile,
    SceMiEC* ec);

unsigned int
SceMiParametersNumberOfObjects(
    const SceMiParameters* parametersHandle,
    const char* objectKind,
    SceMiEC* ec);

int
SceMiParametersAttributeIntegerValue(
    const SceMiParameters* parametersHandle,
    const char* objectKind,
    unsigned int index,
    const char* attributeName,
    SceMiEC* ec);

const char* 
SceMiParametersAttributeStringValue(
    const SceMiParameters* parametersHandle,
    const char* objectKind,
    unsigned int index,
    const char* attributeName,
    SceMiEC* ec);

void
SceMiParametersOverrideAttributeIntegerValue(
    SceMiParameters* parametersHandle,
    const char* objectKind,
    unsigned int index,
    const char* attributeName,
    int value,
    SceMiEC* ec);

void
SceMiParametersOverrideAttributeStringValue(
    SceMiParameters* parametersHandle,
    const char* objectKind,
    unsigned int index,
    const char* attributeName,
    const char* value,
    SceMiEC* ec);
 
/*
 * SceMiMessageData initialization function.
 * This is called to construct a new SceMiMessageData object.
 */
SceMiMessageData* 
SceMiMessageDataNew(
    const SceMiMessageInPortProxy* messageInPortProxyHandle,
    SceMiEC* ec);

/*
 * Destroy a SceMiMessageData object previously returned from
 * SceMiMessageDataNew.
 */
void
SceMiMessageDataDelete(
    SceMiMessageData* messageDataHandle);

/*
 * Return size of message data array in 32 bit words.
 */
unsigned
SceMiMessageDataWidthInBits(
    const SceMiMessageData* messageDataHandle);

/*
 * Return size of array in 32 bit words.
 */
unsigned
SceMiMessageDataWidthInWords(
    const SceMiMessageData* messageDataHandle);

/*
 * Set value of message data word at given index.
 */
void
SceMiMessageDataSet(
    SceMiMessageData* messageDataHandle,
    unsigned i,
    SceMiU32 word,
    SceMiEC* ec);

/*
 * Set bit in message data word at given index.
 */
void
SceMiMessageDataSetBit(
    SceMiMessageData* messageDataHandle,
    unsigned i,
    int bit,
    SceMiEC* ec);

/*
 * Set bit range in message data word at given index.
 */
void SceMiMessageDataSetBitRange(
    SceMiMessageData* messageDataHandle,
    unsigned i,
    unsigned range,
    SceMiU32 bits,
    SceMiEC *ec);

/*
 * Return value of message data word at given index.
 */
SceMiU32
SceMiMessageDataGet(
    const SceMiMessageData* messageDataHandle,
    unsigned i,
    SceMiEC* ec);

/*
 * Return value of bit in message data word at given index.
 */
int
SceMiMessageDataGetBit(
    const SceMiMessageData* messageDataHandle,
    unsigned i,
    SceMiEC* ec);

/*
 * Return value of bit range in message data word at given index.
 */
SceMiU32
SceMiMessageDataGetBitRange(
    const SceMiMessageData *messageDataHandle,
    unsigned int i,
    unsigned int range,
    SceMiEC *ec);

/*
 * Get cyclestamp.
 */
SceMiU64
SceMiMessageDataCycleStamp(
    const SceMiMessageData* messageDataHandle);
 

/*
 * This method sends a message with the specified payload to the
 * transactor input port.  The data will transparently be delivered
 * to the transactor as 1 or more chunks.
 */
void
SceMiMessageInPortProxySend(
    SceMiMessageInPortProxy* messageInPortProxyHandle,
    const SceMiMessageData* messageDataHandle,
    SceMiEC* ec);

const char* 
SceMiMessageInPortProxyTransactorName(
    const SceMiMessageInPortProxy* messageInPortProxyHandle);

const char* 
SceMiMessageInPortProxyPortName(
    const SceMiMessageInPortProxy* messageInPortProxyHandle);

unsigned
SceMiMessageInPortProxyPortWidth(
    const SceMiMessageInPortProxy* messageInPortProxyHandle);

const char* 
SceMiMessageOutPortProxyTransactorName(
    const SceMiMessageOutPortProxy* messageOutPortProxyHandle);

const char* 
SceMiMessageOutPortProxyPortName(
    const SceMiMessageOutPortProxy* messageOutPortProxyHandle);

unsigned
SceMiMessageOutPortProxyPortWidth(
    const SceMiMessageOutPortProxy* messageOutPortProxyHandle);

#ifdef __cplusplus
};
#endif

#endif