//
// scemi.h - SCE-MI C++ Interface
//

#ifndef INCLUDED_SCEMI
#define INCLUDED_SCEMI

class SceMiParameters;
class SceMiMessageData;
class SceMiMessageInPortProxy;
class SceMiMessageOutPortProxy;

#include "scemicommontypes.hxx"

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* configBasePath = "scemi",
        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 SceMiMessagePortProxy
//
// Description
// -----------
// The class SceMiMessagePortProxy is the base class for SceMiMessageInPortProxy
// and SceMiMessageOutPortProxy.  It contains information and methods
// common to both types of port.
//
class SceMiMessagePortProxy {
  public:
    // ACCESSORS
    const char* TransactorName() const;
    const char* PortName() const;
    const unsigned PortWidth() const;
};

//
// 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 SceMiMessagePortProxy {
  public:
    //
    // 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,
        SceMiEC* ec = NULL);
};

//
// class SceMiMessageOutPortProxy
//
// Description
// -----------
// The class SceMiMessageOutPortProxy presents a C++ proxy for a transactor
// message output port.
//
class SceMiMessageOutPortProxy : public SceMiMessagePortProxy {
  public:
    //
    // 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,
        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);

    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,
        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,
        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