Team,
After compiling it, I found a minor syntax error in scemi.h.C++.
Attached is the revised version along with the ANSI C version.
Please superceed previous e-mail with this.
-- johnS
John Stickley wrote:
> Team,
>
> One of my actions was to send updated headers
> with scemicommontypes.h inlined rather than separate.
>
> Attached are the both the C++ and ANSI-C headers that do thsi.
>
> I've also added the SceMiRecoverableError value to the
> SceMiErrorType enum.
>
> I'm going to follow later today with formal re-wording proposals
> for the specification regarding recoverrable errors.
>
> -- johnS
>
> This email may contain material that is confidential, privileged
> and/or attorney work product for the sole use of the intended
> recipient. Any review, reliance or distribution by others or
> forwarding without express permission /\
> is strictly prohibited. If you are /\ | \
> not the intended recipient please | \ / |
> contact the sender and delete / \ \
> all copies. /\_/ K2 \_ \_
> ______________________________/\/ \ \
> John Stickley \ \ \
> Principal Engineer \ \________________
> Mentor Graphics - MED \_
> 17 E. Cedar Place \ john_stickley@mentor.com
> Ramsey, NJ 07446 \ Phone: (201) 818-2585
> ________________________________________________________________
>
>
> ------------------------------------------------------------------------
>
> /*
> * 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<stdlib.h>
>
> /* 32 bit unsigned word type for building and reading messages */
> typedef unsigned SceMiU32;
>
> /* 64 bit unsigned word used for CycleStamps */
> typedef unsigned long long SceMiU64;
>
> #ifndef __cplusplus
> typedef int bool;
> #endif
>
> typedef int (*SceMiServiceLoopHandler)(void* context, bool pending);
>
> /*
> * struct SceMiEC - SceMi Error Context
> */
>
> typedef enum {
> SceMiOK = 0,
> SceMiError = 1,
> SceMiRecoverableError = 2
> } SceMiErrorType;
>
> typedef struct {
> const char* Culprit; /* The offending function */
> const char* Message; /* Descriptive message describing problem */
> SceMiErrorType Type; /* Error code describing the nature of the error */
> int Id; /* A code to uniquely identify each error */
> } SceMiEC;
>
> #ifdef __cplusplus
> extern "C" {
> #endif
> typedef void (*SceMiErrorHandler)(void* context, SceMiEC* ec);
> #ifdef __cplusplus
> }
> #endif
>
> /*
> * struct SceMiIC - SceMi Informational Message Context
> */
>
> typedef enum {
> SceMiInfo = 0,
> SceMiWarning = 1,
> SceMiNonFatalError = 2
> } SceMiInfoType;
>
> typedef struct {
> const char* Originator;
> const char* Message;
> SceMiInfoType Type;
> int Id;
> } SceMiIC;
>
> #ifdef __cplusplus
> extern "C" {
> #endif
> typedef void (*SceMiInfoHandler)(void* context, SceMiIC* ic);
> #ifdef __cplusplus
> }
> #endif
>
> /*
> * struct SceMiMessageInPortBinding
> *
> * Description
> * -----------
> * This structure defines a tray of callback functions that support
> * propagation of message input readiness back to the software.
> *
> * If an input ready callback is registered (optionally) on a given
> * input port, the port will dispatch the callback whenever becomes
> * ready for more input.
> *
> * Note: All callbacks must take their data and return promptly as they
> * are called possibly deep down in a non-preemptive thread. Typically,
> * the callback might to some minor manipulation to the context object
> * then return and let a suspended thread resume and do the main processing
> * of the received transaction.
> */
>
> typedef struct {
> /*
> * This is the user's context object pointer.
> * The application is free to use this pointer for any purposes it
> * wishes. Neither the class SceMi nor class MessageInputPortProxy do
> * anything with this pointer other than store it and pass it when
> * calling functions.
> */
> void* Context;
>
> /*
> * Receive a response transaction. This function is called when data
> * from the message output port arrives. This callback acts as a proxy
> * for the message output port of the transactor.
> */
> void (*IsReady)(
> void* context);
>
> /*
> * This function is called from the MessageInputPortProxy destructor
> * to notify the user code that the reference to the 'context' pointer
> * has been deleted.
> */
> int (*Close)(
> void* context);
>
> } SceMiMessageInPortBinding;
>
> /*
> * struct SceMiMessageOutPortBinding
> *
> * Description
> * -----------
> * This structure defines a tray of callback functions are passed to the class
> * SceMi when the application model binds to a message output port proxy and
> * which are called on message receipt and close notification. It is the means
> * by which the MessageOutputPort forwards received transactions to the C model.
> *
> * Note: All callbacks must take their data and return promptly as they
> * are called possibly deep down in a non-preemptive thread. Typically,
> * the callback might to some minor manipulation to the context object
> * then return and let a suspended thread resume and do the main processing
> * of the received transaction.
> *
> * Additionally, the message data passed into the receive callback is
> * not guaranteed to remain the same once the callback returns. All
> * data therein then must be processed while inside the callback.
> */
>
> typedef struct {
> /*
> * This is the user's context object pointer.
> * The application is free to use this pointer for any purposes it
> * wishes. Neither the class SceMi nor class SceMiMessageOutPortProxy do
> * anything with this pointer other than store it and pass it when
> * calling callback functions Receive and Close.
> */
> void* Context;
>
> /*
> * Receive a response transaction. This function is called when data
> * from the message output port arrives. This callback acts as a proxy
> * for the message output port of the transactor.
> */
> void (*Receive)(
> void* context,
> const SceMiMessageData* data);
>
> /*
> * This function is called from the MessageOutputPortProxy destructor
> * to notify the user code that the reference to the 'context' pointer
> * has been deleted.
> */
> int (*Close)(
> void* context);
>
> } SceMiMessageOutPortBinding;
>
> #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
>
>
> ------------------------------------------------------------------------
>
> //
> // scemi.h - SCE-MI C++ Interface
> //
>
> #ifndef INCLUDED_SCEMI
> #define INCLUDED_SCEMI
>
> class SceMiParameters;
> class SceMiMessageData;
> class SceMiMessageInPortProxy;
> class SceMiMessageOutPortProxy;
>
> #include<stdlib.h>
>
> /* 32 bit unsigned word type for building and reading messages */
> typedef unsigned SceMiU32;
>
> /* 64 bit unsigned word used for CycleStamps */
> typedef unsigned long long SceMiU64;
>
> #ifndef __cplusplus
> typedef int bool;
> #endif
>
> typedef int (*SceMiServiceLoopHandler)(void* context, bool pending);
>
> /*
> * struct SceMiEC - SceMi Error Context
> */
>
> typedef enum {
> SceMiOK = 0,
> SceMiError = 1,
> SceMiRecoverableError = 2
> } SceMiErrorType;
>
> typedef struct {
> const char* Culprit; /* The offending function */
> const char* Message; /* Descriptive message describing problem */
> SceMiErrorType Type; /* Error code describing the nature of the error */
> int Id; /* A code to uniquely identify each error */
> } SceMiEC;
>
> #ifdef __cplusplus
> extern "C" {
> #endif
> typedef void (*SceMiErrorHandler)(void* context, SceMiEC* ec);
> #ifdef __cplusplus
> }
> #endif
>
> /*
> * struct SceMiIC - SceMi Informational Message Context
> */
>
> typedef enum {
> SceMiInfo = 0,
> SceMiWarning = 1,
> SceMiNonFatalError = 2
> } SceMiInfoType;
>
> typedef struct {
> const char* Originator;
> const char* Message;
> SceMiInfoType Type;
> int Id;
> } SceMiIC;
>
> #ifdef __cplusplus
> extern "C" {
> #endif
> typedef void (*SceMiInfoHandler)(void* context, SceMiIC* ic);
> #ifdef __cplusplus
> }
> #endif
>
> /*
> * struct SceMiMessageInPortBinding
> *
> * Description
> * -----------
> * This structure defines a tray of callback functions that support
> * propagation of message input readiness back to the software.
> *
> * If an input ready callback is registered (optionally) on a given
> * input port, the port will dispatch the callback whenever becomes
> * ready for more input.
> *
> * Note: All callbacks must take their data and return promptly as they
> * are called possibly deep down in a non-preemptive thread. Typically,
> * the callback might to some minor manipulation to the context object
> * then return and let a suspended thread resume and do the main processing
> * of the received transaction.
> */
>
> typedef struct {
> /*
> * This is the user's context object pointer.
> * The application is free to use this pointer for any purposes it
> * wishes. Neither the class SceMi nor class MessageInputPortProxy do
> * anything with this pointer other than store it and pass it when
> * calling functions.
> */
> void* Context;
>
> /*
> * Receive a response transaction. This function is called when data
> * from the message output port arrives. This callback acts as a proxy
> * for the message output port of the transactor.
> */
> void (*IsReady)(
> void* context);
>
> /*
> * This function is called from the MessageInputPortProxy destructor
> * to notify the user code that the reference to the 'context' pointer
> * has been deleted.
> */
> int (*Close)(
> void* context);
>
> } SceMiMessageInPortBinding;
>
> /*
> * struct SceMiMessageOutPortBinding
> *
> * Description
> * -----------
> * This structure defines a tray of callback functions are passed to the class
> * SceMi when the application model binds to a message output port proxy and
> * which are called on message receipt and close notification. It is the means
> * by which the MessageOutputPort forwards received transactions to the C model.
> *
> * Note: All callbacks must take their data and return promptly as they
> * are called possibly deep down in a non-preemptive thread. Typically,
> * the callback might to some minor manipulation to the context object
> * then return and let a suspended thread resume and do the main processing
> * of the received transaction.
> *
> * Additionally, the message data passed into the receive callback is
> * not guaranteed to remain the same once the callback returns. All
> * data therein then must be processed while inside the callback.
> */
>
> typedef struct {
> /*
> * This is the user's context object pointer.
> * The application is free to use this pointer for any purposes it
> * wishes. Neither the class SceMi nor class SceMiMessageOutPortProxy do
> * anything with this pointer other than store it and pass it when
> * calling callback functions Receive and Close.
> */
> void* Context;
>
> /*
> * Receive a response transaction. This function is called when data
> * from the message output port arrives. This callback acts as a proxy
> * for the message output port of the transactor.
> */
> void (*Receive)(
> void* context,
> const SceMiMessageData* data);
>
> /*
> * This function is called from the MessageOutputPortProxy destructor
> * to notify the user code that the reference to the 'context' pointer
> * has been deleted.
> */
> int (*Close)(
> void* context);
>
> } SceMiMessageOutPortBinding;
>
> class SceMiParameters {
>
> public:
> // CREATORS
>
> //
> // This constructor initializes some parameters from the
> // parameters file in the config directory, and some other
> // parameters directly from the config file.
> //
> SceMiParameters(
> const char* paramfile;
> SceMiEC* ec = NULL);
>
> ~SceMiParameters();
>
> // ACCESSORS
>
> //
> // This accessor returns the number of instances of objects of
> // the specified objectKind name.
> //
> unsigned int NumberOfObjects(
> const char* objectKind, // Input: Object kind name.
> SceMiEC* ec = 0) const; // Input/Output: Error status.
>
> //
> // These accessors return an integer or string attribute values of the
> // given object kind. It is considered an error if the index > number
> // returned by ::NumberOfObjects() or the objectKind and attributeName
> // arguments are unrecognized.
> //
> int AttributeIntegerValue(
> const char* objectKind, // Input: Object kind name.
> unsigned int index, // Input: Index of object instance.
> const char* attributeName, // Input: Name of attribute being read.
> SceMiEC* ec = NULL) const; // Input/Output: Error status.
>
> const char* AttributeStringValue(
> const char* objectKind, // Input: Object kind name.
> unsigned int index, // Input: Index of object instance.
> const char* attributeName, // Input: Name of attribute being read.
> SceMiEC* ec = NULL) const; // Input/Output: Error status.
>
> // MANIPULATORS
>
> //
> // These manipulators override an integer or string attribute values of the
> // given object kind. It is considered an error if the index > number
> // returned by ::NumberOfObjects(). or the objectKind and attributeName
> // arguments are unrecognized.
> //
> void OverrideAttributeIntegerValue(
> const char* objectKind, // Input: Object kind name.
> unsigned int index, // Input: Index of object instance.
> const char* attributeName, // Input: Name of attribute being read.
> int value, // Input: New integer value of attribute.
> SceMiEC* ec = NULL); // Input/Output: Error status.
>
> void OverrideAttributeStringValue(
> const char* objectKind, // Input: Object kind name.
> unsigned int index, // Input: Index of object instance.
> const char* attributeName, // Input: Name of attribute being read.
> const char* value, // Input: New string value of attribute.
> SceMiEC* ec = NULL); // Input/Output: Error status.
> };
>
> //
> // class SceMiMessageInPortProxy
> //
> // Description
> // -----------
> // The class SceMiMessageInPortProxy presents a C++ proxy for a transactor
> // message input port. The input channel to that transactor is represented
> // by the Send() method.
> //
>
> class SceMiMessageInPortProxy {
> public:
> // ACCESSORS
> const char* TransactorName() const;
> const char* PortName() const;
> const unsigned PortWidth() const;
>
> //
> // This method sends message to the transactor input port.
> //
> void Send(
> const SceMiMessageData &data, // Message payload to be sent.
> SceMiEC* ec = NULL);
>
> //
> // Replace port binding.
> // The binding argument represents a callback function and context
> // pointer tray (see comments in scemicommontypes.h for struct
> // SceMiMessageInPortBinding).
> //
> void ReplaceBinding(
> const SceMiMessageInPortBinding* binding = NULL,
> SceMiEC* ec = NULL);
> };
>
> //
> // class SceMiMessageOutPortProxy
> //
> // Description
> // -----------
> // The class SceMiMessageOutPortProxy presents a C++ proxy for a transactor
> // message output port.
> //
> class SceMiMessageOutPortProxy {
> public:
> // ACCESSORS
> const char* TransactorName() const;
> const char* PortName() const;
> const unsigned PortWidth() const;
>
> //
> // Replace port binding.
> // The binding argument represents a callback function and context
> // pointer tray (see comments in scemicommontypes.h for struct
> // SceMiMessageOutPortBinding).
> //
> void ReplaceBinding(
> const SceMiMessageOutPortBinding* binding = NULL,
> SceMiEC* ec = NULL);
> };
>
> //
> // class SceMiMessageData
> //
> // Description
> // -----------
> // The class SceMiMessageData represents a fixed length array of data which
> // is transferred between models.
> //
> class SceMiMessageData {
> public:
> // CREATORS
>
> //
> // Constructor: The message in port proxy for which
> // this message data object must be suitably sized.
> //
> SceMiMessageData(
> const SceMiMessageInPortProxy& messageInPortProxy,
> SceMiEC* ec = NULL);
>
> ~SceMiMessageData();
>
> // Return size of vector in bits
> unsigned WidthInBits() const;
>
> // Return size of array in 32 bit words.
> unsigned WidthInWords() const;
>
> void Set( unsigned i, SceMiU32 word, SceMiEC* ec = NULL);
>
> void SetBit( unsigned i, int bit, SceMiEC* ec = NULL);
>
> void SetBitRange(
> unsigned int i, unsigned int range, SceMiU32 bits, SceMiEC* ec = NULL);
>
> SceMiU32 Get( unsigned i, SceMiEC* ec = NULL) const;
>
> int GetBit( unsigned i, SceMiEC* ec = NULL) const;
>
> SceMiU32 GetBitRange(
> unsigned int i, unsigned int range, SceMiEC* ec = NULL) const;
>
> SceMiU64 CycleStamp() const;
> };
>
> //
> // class SceMi
> //
> // Description
> // -----------
> // This file defines the public interface to class SceMi.
> //
>
> class SceMi {
> public:
> //
> // Check version string against supported versions.
> // Returns -1 if passed string not supported.
> // Returns interface version # if it is supported.
> // This interface version # can be passed to SceMi::Init().
> //
> static int Version(
> 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
> // SceMi::Init() function, that pointer is returned since a single
> // instance of class SceMi is reusable among all C models.
> // Returns NULL if error occurred, check ec for status or register
> // an error callback.
> //
> // The caller is required to pass in the version of SceMi it is
> // expecting to work with. Call SceMi::Version to convert a version
> // string to an integer suitable for this version's "version" argument.
> //
> // The caller is also expected to have instantiated a SceMiParameters
> // object, and pass a pointer to that object into this function.
> //
> static SceMi*
> Init(
> int version,
> const SceMiParameters* parameters,
> SceMiEC* ec = NULL);
>
> //
> // Shut down the SCEMI interface.
> //
> static void
> Shutdown(
> SceMi* mct,
> SceMiEC* ec = NULL);
>
> //
> // Create proxy for message input port.
> //
> // Pass in the instance name in the bridge netlist of
> // the transactor and port to which binding is requested.
> //
> // The binding argument is a callback function and context
> // pointer tray. For more details, see the comments in
> // scemicommontypes.h by struct SceMiMessageInPortBinding.
> //
> SceMiMessageInPortProxy*
> BindMessageInPort(
> const char* transactorName,
> const char* portName,
> const SceMiMessageInPortBinding* binding = NULL,
> SceMiEC* ec = NULL);
>
> //
> // Create proxy for message output port.
> //
> // Pass in the instance name in the bridge netlist of
> // the transactor and port to which binding is requested.
> //
> // The binding argument is a callback function and context
> // pointer tray. For more details, see the comments in
> // scemicommontypes.h by struct SceMiMessageOutPortBinding.
> //
> SceMiMessageOutPortProxy*
> BindMessageOutPort(
> const char* transactorName,
> const char* portName,
> const SceMiMessageOutPortBinding* binding = NULL,
> SceMiEC* ec = NULL);
>
> //
> // 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.
> //
> // Regarding the service loop handler (aka "g 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 user context object pointer is uninterpreted by
> // ServiceLoop() and is passed straight to the 'g' function.
> //
> int
> ServiceLoop(
> SceMiServiceLoopHandler g = NULL,
> void* context = NULL,
> SceMiEC* ec = NULL);
>
> //
> // 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.
> //
> static void
> RegisterErrorHandler(
> SceMiErrorHandler errorHandler,
> void* context);
>
> //
> // Register an info handler which is called in the event
> // that a text message needs to be issued. If no handler
> // is registered, the message is printed to stdout in
> // Ikos message format.
> //
> static void
> RegisterInfoHandler(
> SceMiInfoHandler infoHandler,
> void* context);
> };
>
> #endif
>
-- This email may contain material that is confidential, privileged and/or attorney work product for the sole use of the intended recipient. Any review, reliance or distribution by others or forwarding without express permission /\ is strictly prohibited. If you are /\ | \ not the intended recipient please | \ / | contact the sender and delete / \ \ all copies. /\_/ K2 \_ \_ ______________________________/\/ \ \ John Stickley \ \ \ Principal Engineer \ \________________ Mentor Graphics - MED \_ 17 E. Cedar Place \ john_stickley@mentor.com Ramsey, NJ 07446 \ Phone: (201) 818-2585 ________________________________________________________________
/*
* 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<stdlib.h>
/* 32 bit unsigned word type for building and reading messages */
typedef unsigned SceMiU32;
/* 64 bit unsigned word used for CycleStamps */
typedef unsigned long long SceMiU64;
#ifndef __cplusplus
typedef int bool;
#endif
typedef int (*SceMiServiceLoopHandler)(void* context, bool pending);
/*
* struct SceMiEC - SceMi Error Context
*/
typedef enum {
SceMiOK = 0,
SceMiError = 1,
SceMiRecoverableError = 2
} SceMiErrorType;
typedef struct {
const char* Culprit; /* The offending function */
const char* Message; /* Descriptive message describing problem */
SceMiErrorType Type; /* Error code describing the nature of the error */
int Id; /* A code to uniquely identify each error */
} SceMiEC;
#ifdef __cplusplus
extern "C" {
#endif
typedef void (*SceMiErrorHandler)(void* context, SceMiEC* ec);
#ifdef __cplusplus
}
#endif
/*
* struct SceMiIC - SceMi Informational Message Context
*/
typedef enum {
SceMiInfo = 0,
SceMiWarning = 1,
SceMiNonFatalError = 2
} SceMiInfoType;
typedef struct {
const char* Originator;
const char* Message;
SceMiInfoType Type;
int Id;
} SceMiIC;
#ifdef __cplusplus
extern "C" {
#endif
typedef void (*SceMiInfoHandler)(void* context, SceMiIC* ic);
#ifdef __cplusplus
}
#endif
/*
* struct SceMiMessageInPortBinding
*
* Description
* -----------
* This structure defines a tray of callback functions that support
* propagation of message input readiness back to the software.
*
* If an input ready callback is registered (optionally) on a given
* input port, the port will dispatch the callback whenever becomes
* ready for more input.
*
* Note: All callbacks must take their data and return promptly as they
* are called possibly deep down in a non-preemptive thread. Typically,
* the callback might to some minor manipulation to the context object
* then return and let a suspended thread resume and do the main processing
* of the received transaction.
*/
typedef struct {
/*
* This is the user's context object pointer.
* The application is free to use this pointer for any purposes it
* wishes. Neither the class SceMi nor class MessageInputPortProxy do
* anything with this pointer other than store it and pass it when
* calling functions.
*/
void* Context;
/*
* Receive a response transaction. This function is called when data
* from the message output port arrives. This callback acts as a proxy
* for the message output port of the transactor.
*/
void (*IsReady)(
void* context);
/*
* This function is called from the MessageInputPortProxy destructor
* to notify the user code that the reference to the 'context' pointer
* has been deleted.
*/
int (*Close)(
void* context);
} SceMiMessageInPortBinding;
/*
* struct SceMiMessageOutPortBinding
*
* Description
* -----------
* This structure defines a tray of callback functions are passed to the class
* SceMi when the application model binds to a message output port proxy and
* which are called on message receipt and close notification. It is the means
* by which the MessageOutputPort forwards received transactions to the C model.
*
* Note: All callbacks must take their data and return promptly as they
* are called possibly deep down in a non-preemptive thread. Typically,
* the callback might to some minor manipulation to the context object
* then return and let a suspended thread resume and do the main processing
* of the received transaction.
*
* Additionally, the message data passed into the receive callback is
* not guaranteed to remain the same once the callback returns. All
* data therein then must be processed while inside the callback.
*/
typedef struct {
/*
* This is the user's context object pointer.
* The application is free to use this pointer for any purposes it
* wishes. Neither the class SceMi nor class SceMiMessageOutPortProxy do
* anything with this pointer other than store it and pass it when
* calling callback functions Receive and Close.
*/
void* Context;
/*
* Receive a response transaction. This function is called when data
* from the message output port arrives. This callback acts as a proxy
* for the message output port of the transactor.
*/
void (*Receive)(
void* context,
const SceMiMessageData* data);
/*
* This function is called from the MessageOutputPortProxy destructor
* to notify the user code that the reference to the 'context' pointer
* has been deleted.
*/
int (*Close)(
void* context);
} SceMiMessageOutPortBinding;
#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
//
// scemi.h - SCE-MI C++ Interface
//
#ifndef INCLUDED_SCEMI
#define INCLUDED_SCEMI
class SceMiParameters;
class SceMiMessageData;
class SceMiMessageInPortProxy;
class SceMiMessageOutPortProxy;
#include<stdlib.h>
/* 32 bit unsigned word type for building and reading messages */
typedef unsigned SceMiU32;
/* 64 bit unsigned word used for CycleStamps */
typedef unsigned long long SceMiU64;
#ifndef __cplusplus
typedef int bool;
#endif
typedef int (*SceMiServiceLoopHandler)(void* context, bool pending);
/*
* struct SceMiEC - SceMi Error Context
*/
typedef enum {
SceMiOK = 0,
SceMiError = 1,
SceMiRecoverableError = 2
} SceMiErrorType;
typedef struct {
const char* Culprit; /* The offending function */
const char* Message; /* Descriptive message describing problem */
SceMiErrorType Type; /* Error code describing the nature of the error */
int Id; /* A code to uniquely identify each error */
} SceMiEC;
#ifdef __cplusplus
extern "C" {
#endif
typedef void (*SceMiErrorHandler)(void* context, SceMiEC* ec);
#ifdef __cplusplus
}
#endif
/*
* struct SceMiIC - SceMi Informational Message Context
*/
typedef enum {
SceMiInfo = 0,
SceMiWarning = 1,
SceMiNonFatalError = 2
} SceMiInfoType;
typedef struct {
const char* Originator;
const char* Message;
SceMiInfoType Type;
int Id;
} SceMiIC;
#ifdef __cplusplus
extern "C" {
#endif
typedef void (*SceMiInfoHandler)(void* context, SceMiIC* ic);
#ifdef __cplusplus
}
#endif
/*
* struct SceMiMessageInPortBinding
*
* Description
* -----------
* This structure defines a tray of callback functions that support
* propagation of message input readiness back to the software.
*
* If an input ready callback is registered (optionally) on a given
* input port, the port will dispatch the callback whenever becomes
* ready for more input.
*
* Note: All callbacks must take their data and return promptly as they
* are called possibly deep down in a non-preemptive thread. Typically,
* the callback might to some minor manipulation to the context object
* then return and let a suspended thread resume and do the main processing
* of the received transaction.
*/
typedef struct {
/*
* This is the user's context object pointer.
* The application is free to use this pointer for any purposes it
* wishes. Neither the class SceMi nor class MessageInputPortProxy do
* anything with this pointer other than store it and pass it when
* calling functions.
*/
void* Context;
/*
* Receive a response transaction. This function is called when data
* from the message output port arrives. This callback acts as a proxy
* for the message output port of the transactor.
*/
void (*IsReady)(
void* context);
/*
* This function is called from the MessageInputPortProxy destructor
* to notify the user code that the reference to the 'context' pointer
* has been deleted.
*/
int (*Close)(
void* context);
} SceMiMessageInPortBinding;
/*
* struct SceMiMessageOutPortBinding
*
* Description
* -----------
* This structure defines a tray of callback functions are passed to the class
* SceMi when the application model binds to a message output port proxy and
* which are called on message receipt and close notification. It is the means
* by which the MessageOutputPort forwards received transactions to the C model.
*
* Note: All callbacks must take their data and return promptly as they
* are called possibly deep down in a non-preemptive thread. Typically,
* the callback might to some minor manipulation to the context object
* then return and let a suspended thread resume and do the main processing
* of the received transaction.
*
* Additionally, the message data passed into the receive callback is
* not guaranteed to remain the same once the callback returns. All
* data therein then must be processed while inside the callback.
*/
typedef struct {
/*
* This is the user's context object pointer.
* The application is free to use this pointer for any purposes it
* wishes. Neither the class SceMi nor class SceMiMessageOutPortProxy do
* anything with this pointer other than store it and pass it when
* calling callback functions Receive and Close.
*/
void* Context;
/*
* Receive a response transaction. This function is called when data
* from the message output port arrives. This callback acts as a proxy
* for the message output port of the transactor.
*/
void (*Receive)(
void* context,
const SceMiMessageData* data);
/*
* This function is called from the MessageOutputPortProxy destructor
* to notify the user code that the reference to the 'context' pointer
* has been deleted.
*/
int (*Close)(
void* context);
} SceMiMessageOutPortBinding;
class SceMiParameters {
public:
// CREATORS
//
// This constructor initializes some parameters from the
// parameters file in the config directory, and some other
// parameters directly from the config file.
//
SceMiParameters(
const char* paramfile,
SceMiEC* ec = NULL);
~SceMiParameters();
// ACCESSORS
//
// This accessor returns the number of instances of objects of
// the specified objectKind name.
//
unsigned int NumberOfObjects(
const char* objectKind, // Input: Object kind name.
SceMiEC* ec = 0) const; // Input/Output: Error status.
//
// These accessors return an integer or string attribute values of the
// given object kind. It is considered an error if the index > number
// returned by ::NumberOfObjects() or the objectKind and attributeName
// arguments are unrecognized.
//
int AttributeIntegerValue(
const char* objectKind, // Input: Object kind name.
unsigned int index, // Input: Index of object instance.
const char* attributeName, // Input: Name of attribute being read.
SceMiEC* ec = NULL) const; // Input/Output: Error status.
const char* AttributeStringValue(
const char* objectKind, // Input: Object kind name.
unsigned int index, // Input: Index of object instance.
const char* attributeName, // Input: Name of attribute being read.
SceMiEC* ec = NULL) const; // Input/Output: Error status.
// MANIPULATORS
//
// These manipulators override an integer or string attribute values of the
// given object kind. It is considered an error if the index > number
// returned by ::NumberOfObjects(). or the objectKind and attributeName
// arguments are unrecognized.
//
void OverrideAttributeIntegerValue(
const char* objectKind, // Input: Object kind name.
unsigned int index, // Input: Index of object instance.
const char* attributeName, // Input: Name of attribute being read.
int value, // Input: New integer value of attribute.
SceMiEC* ec = NULL); // Input/Output: Error status.
void OverrideAttributeStringValue(
const char* objectKind, // Input: Object kind name.
unsigned int index, // Input: Index of object instance.
const char* attributeName, // Input: Name of attribute being read.
const char* value, // Input: New string value of attribute.
SceMiEC* ec = NULL); // Input/Output: Error status.
};
//
// class SceMiMessageInPortProxy
//
// Description
// -----------
// The class SceMiMessageInPortProxy presents a C++ proxy for a transactor
// message input port. The input channel to that transactor is represented
// by the Send() method.
//
class SceMiMessageInPortProxy {
public:
// ACCESSORS
const char* TransactorName() const;
const char* PortName() const;
const unsigned PortWidth() const;
//
// This method sends message to the transactor input port.
//
void Send(
const SceMiMessageData &data, // Message payload to be sent.
SceMiEC* ec = NULL);
//
// Replace port binding.
// The binding argument represents a callback function and context
// pointer tray (see comments in scemicommontypes.h for struct
// SceMiMessageInPortBinding).
//
void ReplaceBinding(
const SceMiMessageInPortBinding* binding = NULL,
SceMiEC* ec = NULL);
};
//
// class SceMiMessageOutPortProxy
//
// Description
// -----------
// The class SceMiMessageOutPortProxy presents a C++ proxy for a transactor
// message output port.
//
class SceMiMessageOutPortProxy {
public:
// ACCESSORS
const char* TransactorName() const;
const char* PortName() const;
const unsigned PortWidth() const;
//
// Replace port binding.
// The binding argument represents a callback function and context
// pointer tray (see comments in scemicommontypes.h for struct
// SceMiMessageOutPortBinding).
//
void ReplaceBinding(
const SceMiMessageOutPortBinding* binding = NULL,
SceMiEC* ec = NULL);
};
//
// class SceMiMessageData
//
// Description
// -----------
// The class SceMiMessageData represents a fixed length array of data which
// is transferred between models.
//
class SceMiMessageData {
public:
// CREATORS
//
// Constructor: The message in port proxy for which
// this message data object must be suitably sized.
//
SceMiMessageData(
const SceMiMessageInPortProxy& messageInPortProxy,
SceMiEC* ec = NULL);
~SceMiMessageData();
// Return size of vector in bits
unsigned WidthInBits() const;
// Return size of array in 32 bit words.
unsigned WidthInWords() const;
void Set( unsigned i, SceMiU32 word, SceMiEC* ec = NULL);
void SetBit( unsigned i, int bit, SceMiEC* ec = NULL);
void SetBitRange(
unsigned int i, unsigned int range, SceMiU32 bits, SceMiEC* ec = NULL);
SceMiU32 Get( unsigned i, SceMiEC* ec = NULL) const;
int GetBit( unsigned i, SceMiEC* ec = NULL) const;
SceMiU32 GetBitRange(
unsigned int i, unsigned int range, SceMiEC* ec = NULL) const;
SceMiU64 CycleStamp() const;
};
//
// class SceMi
//
// Description
// -----------
// This file defines the public interface to class SceMi.
//
class SceMi {
public:
//
// Check version string against supported versions.
// Returns -1 if passed string not supported.
// Returns interface version # if it is supported.
// This interface version # can be passed to SceMi::Init().
//
static int Version(
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
// SceMi::Init() function, that pointer is returned since a single
// instance of class SceMi is reusable among all C models.
// Returns NULL if error occurred, check ec for status or register
// an error callback.
//
// The caller is required to pass in the version of SceMi it is
// expecting to work with. Call SceMi::Version to convert a version
// string to an integer suitable for this version's "version" argument.
//
// The caller is also expected to have instantiated a SceMiParameters
// object, and pass a pointer to that object into this function.
//
static SceMi*
Init(
int version,
const SceMiParameters* parameters,
SceMiEC* ec = NULL);
//
// Shut down the SCEMI interface.
//
static void
Shutdown(
SceMi* mct,
SceMiEC* ec = NULL);
//
// Create proxy for message input port.
//
// Pass in the instance name in the bridge netlist of
// the transactor and port to which binding is requested.
//
// The binding argument is a callback function and context
// pointer tray. For more details, see the comments in
// scemicommontypes.h by struct SceMiMessageInPortBinding.
//
SceMiMessageInPortProxy*
BindMessageInPort(
const char* transactorName,
const char* portName,
const SceMiMessageInPortBinding* binding = NULL,
SceMiEC* ec = NULL);
//
// Create proxy for message output port.
//
// Pass in the instance name in the bridge netlist of
// the transactor and port to which binding is requested.
//
// The binding argument is a callback function and context
// pointer tray. For more details, see the comments in
// scemicommontypes.h by struct SceMiMessageOutPortBinding.
//
SceMiMessageOutPortProxy*
BindMessageOutPort(
const char* transactorName,
const char* portName,
const SceMiMessageOutPortBinding* binding = NULL,
SceMiEC* ec = NULL);
//
// 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.
//
// Regarding the service loop handler (aka "g 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 user context object pointer is uninterpreted by
// ServiceLoop() and is passed straight to the 'g' function.
//
int
ServiceLoop(
SceMiServiceLoopHandler g = NULL,
void* context = NULL,
SceMiEC* ec = NULL);
//
// 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.
//
static void
RegisterErrorHandler(
SceMiErrorHandler errorHandler,
void* context);
//
// Register an info handler which is called in the event
// that a text message needs to be issued. If no handler
// is registered, the message is printed to stdout in
// Ikos message format.
//
static void
RegisterInfoHandler(
SceMiInfoHandler infoHandler,
void* context);
};
#endif
Received on Wed Jun 23 21:22:34 2004
This archive was generated by hypermail 2.1.8 : Wed Jun 23 2004 - 21:22:35 PDT