*         0 - False/Failure. The function did not complete without error.
*         The error will be queued into the event queue.
*
* POINTERS : 
*         Again following the Microsoft convention all pointer arguments
*         are checked for NULL.  If a pointer is NULL then input arguments
*         are not used and return arguments are not returned.  Example,
*         if you call GetLastError and set pErrString to NULL then no
*         error string is returned.  
*A***************************************************************************/

//----------------------------------------------------------------------------
// Interface config functions
//
// CreateHndl : Create a handle for this debug instance.  If pLibPath and 
//              pLibName are not NULL then use the specified debug library.
//              Else, pDevName must hold the name of the processor family
//              to connect to.  If all three parameters are provided then
//              pFamily will be used to validate the loaded lib..
//              A valid handle is returned except in the rare case of
//              insufficent host memory.  Thus you can call GetLastError
//              if there is an error during CreateHndl.
//
// FreeHndl :   Free the handle from CreateHndl.  Closes the open 
//              debug session if required.  You MUST always call
//              this to release resources if CreateHndl returns
//              a valid handle. FreeHndl will automaticly "Disconnect"
//              if the debug session is still "Connected".
//
// SetOptions : Set the options for this debug session. Options are
//              generally setup prior to connecting to a target. 
//              Options are in the form of "EmulatorId=378,...",
//              using a comma seperator and null terminator.  Once 
//              connected some options cannot be changed until you
//              disconnect, for example your EmulatorId.
//
// GetOptions : Return the current options.  MaxString is the maximum
//              size of the return string.             
//
// FreeOptions : Free the current options and return to the default
//               state. FreeOptions can only be called when in the
//               disconnected state.  You can change current options
//               by calling SetOptions with the restriction that not
//               all options can be changed while in the connected 
//               state.
//
// Connect :     Make a debug connection to the target.  Once connected the
//               target is ready for a debug session.
//
// Disconnect : Disconnect from the debug session. Once disconnected no
//              more target accesses are allowed.
//
// GetErrorString : Get an error string based on the error number
// 
//
//----------------------------------------------------------------------------
// Valid device families for the function CreatHndl 
#define FAMILY_TMS320C5X               "TMS320C5X"
#define FAMILY_TMS320C3X               "TMS320C3X"
#define FAMILY_TMS320VC3X              "TMS320VC3X"
#define FAMILY_TMS320C4X               "TMS320C4X"
#define FAMILY_TMS320C2XX              "TMS320C2XX"
#define FAMILY_TMS320C54X              "TMS320C54X"   
#define FAMILY_TMS320C6XX              "TMS320C6XX"
#define FAMILY_TMS320C55XX             "TMS320C55XX"
#define FAMILY_TMSR470                 "TMSR470"
#define FAMILY_TMS320C27XX             "TMS320C27XX"
#define FAMILY_INTEL_XSCALE            "INTEL_XSCALE"
#define FAMILY_ARM925                  "ARM925"
#define FAMILY_TMS320C64XX             "TMS320C64XX"

typedef struct sdf_cfg
{
    int      StructSz;           // Size of this structure
    int      Version;            // Interface major version                    
    int      Revision;           // Interface minor revision        

    // Create/Free handle for debug instance
    BOOL     (*CreateHndl)  ( SDTI_HNDL *pHndl, char *pLibPath, char *pLibName,
                                                char *pFamily );
    BOOL     (*FreeHndl)    ( SDTI_HNDL Hndl );

    // Option setup prior to connecting to the target
	BOOL     (*SetOptions)   ( SDTI_HNDL Hndl, char *pOptsString );
    BOOL     (*GetOptions)   ( SDTI_HNDL Hndl, int  MaxString, 
                               char *pOptsString );
    BOOL     (*FreeOptions)  ( SDTI_HNDL Hndl );


    // Connect/Disconnect from the target
    BOOL     (*Connect)      ( SDTI_HNDL Hndl                     );   
    BOOL     (*Disconnect)   ( SDTI_HNDL Hndl                     );

    // Get an error string based on the error code
    BOOL     (*GetErrorString) ( SDTI_HNDL Hndl, int Error, int MaxString, 
                                                 char *pErrString );
} SDF_CFG, *PSDF_CFG;

//----------------------------------------------------------------------------
// Register functions
//
// ReadByName  : Read a target register using the "common" register name as
//               the identifier.
// WriteByName : Write a target register using the "common" register name as
//               the identifier.
//
// Each processor has a register mapping file named "sdti_regCPU.c" where
// CPU is a processor identifier.  Each register is defined as:
//     { "Name", Size, Id }
//     C54x Example:
//        {"IMR",      sizeof(TREG_16),         0 },
//        {"IFR",      sizeof(TREG_16),         1 },
//
typedef struct sdf_reg
{
    int      StructSz;           // Size of this structure
    int      Version;            // Interface major version                    
    int      Revision;           // Interface minor revision        

    BOOL     (*ReadByName) ( SDTI_HNDL Hndl, char *pRegName, TREG *pReg );
    BOOL     (*WriteByName)( SDTI_HNDL Hndl, char *pRegName, TREG *pReg );
}SDF_REG, *PSDF_REG;

//----------------------------------------------------------------------------
// Memory functions
// 
// Read  : Read a block of memory.
// Write : Write a block of memory.
// Fill  : Fill a block of memory.
// isBigEndian  : Returns TRUE if processor is big endian or FALSE if little.
// 
// The user can specify a memory type, i.e. program, data, i/o for Harvard(TI),
// or natural for others.
// The user then specifies if the access size is to be 8,16,32,64 bit.
// The length of the block is in "access size" elements.
//
// Data in the memory buffer is passed in host endianess format for the
// specified access size.
//
typedef struct sdf_mem
{
    int      StructSz;           // Size of this structure
    int      Version;            // Interface major version                    
    int      Revision;           // Interface minor revision        
    
    BOOL     (*Read)       ( SDTI_HNDL Hndl, TMEM_DESC *pMem );
    BOOL     (*Write)      ( SDTI_HNDL Hndl, TMEM_DESC *pMem );
    BOOL     (*Fill)       ( SDTI_HNDL Hndl, TMEM_DESC *pMem );
	BOOL     (*isBigEndian)( SDTI_HNDL Hndl                  );
}SDF_MEM, *PSDF_MEM;

//----------------------------------------------------------------------------
// Event functions
//
// Add    : Add an event.  An event Id is returned.
// Delete : Delete an event based on EvtId.
// 
typedef struct sdf_evt
{
    int             StructSz;           // Size of this structure
    int             Version;            // Interface major version                    
    int             Revision;           // Interface minor revision            
    
    BOOL     (*Add)       ( SDTI_HNDL Hndl, TEVT_DESC *pEvt );
    BOOL     (*Delete)    ( SDTI_HNDL Hndl, unsigned EvtId );
}SDF_EVT, *PSDF_EVT;  

//----------------------------------------------------------------------------
// Execution functions 
//
// Reset : Do a hardware or software reset on the connected target.
// Continue : Continue target execution from the current program address.
// Suspend  : Suspend target execution.
// Step  : Step "Count" assembly instructions with interrupts off.
// UserMode : Continue target execution in user mode, i.e. connected but
//            debug disabled.
// IsRunning : Is the target processor running or suspended.  The 
//             target is considered "running" until it is SUCCESSFULLY
//             suspended.  
// IsEvent : Is an event pending. If pEvtStat is not NULL then return the
//             pending event.
//            
// IsEvent returns all events, i.e. breakpoints, errors, status, etc..
// As long as events are in the queue IsEvent will return "TRUE".
//
typedef struct sdf_exe
{
    int             StructSz;           // Size of this structure
    int             Version;            // Interface major version                    
    int             Revision;           // Interface minor revision            
    
    BOOL     (*Reset)      ( SDTI_HNDL Hndl );
    BOOL     (*Continue)   ( SDTI_HNDL Hndl );
    BOOL     (*Suspend)    ( SDTI_HNDL Hndl );
    BOOL     (*Step)       ( SDTI_HNDL Hndl, unsigned long Count );
    BOOL     (*UserMode)   ( SDTI_HNDL Hndl );
    BOOL     (*IsRunning)  ( SDTI_HNDL Hndl );
    BOOL     (*IsEvent)    ( SDTI_HNDL Hndl, TEVT_STAT_DESC *pEvtStat );

// REVISION 2 - changes
// 1) Added in realtime functions EnterRealtimeMode() and ExitRealtimeMode().
//    These functions are supported on C28x, C55xx, and C64xx via TI
//    IceMaker emulation.  These functions are basicly pass-through to lower
//    level of emulation drivers and may require additional setup external
//    to SDTI.
    BOOL     (*EnterRealtimeMode) (SDTI_HNDL Hndl, unsigned long Option );
    BOOL     (*ExitRealtimeMode)  (SDTI_HNDL Hndl );

}SDF_EXE, *PSDF_EXE;


typedef struct sd_target_interface
{
    int             StructSz;           // Size of this structure
    int             Version;            // Interface major version                    
    int             Revision;           // Interface minor revision                  
    int             Type;               // Interface type         
    int             isInitalized;       // True if intf. autoinit 
    char    *       Name;               // Interface name, will contain the
                                        // target family name
    unsigned long   Flags;              // Operation flags           

    SDF_CFG       * pCfg;               // Interface config functions
    SDF_REG       * pReg;               // Register functions
    SDF_MEM       * pMem;               // Memory functions
    SDF_EVT       * pEvt;               // Event functions
    SDF_EXE       * pExe;               // Execution functions

}SD_TARGET_INTERFACE, *PSD_TARGET_INTERFACE ;

typedef enum sdti_errors
{
    ERR_NONE            = 0,

    // Config errors
    CFG_ERR_GENERIC     = 4000,
    GFG_ERR_HOST_MALLOC,                // Fail host memory malloc
    CFG_ERR_LIB_HANDLE,                 // Could not get targ lib handle
    CFG_ERR_LIB_INTERFACE,              // Invalid lib interface
    CFG_ERR_LIB_VERSION,                // Invalid lib version
    CFG_ERR_FAMILY,                     // Invalid processor family
    CFG_ERR_UNKNOWN_OPTION,             // Unknown/unsupported option
    CFG_ERR_HANDLE,                     // Passed handle is invalid
    CFG_ERR_DISCONNECTED,               // Invalid action when targ disconnected
    
    // Register errors
    REG_ERR_GENERIC = 5000,
    REG_ERR_NAME,                       // Invalid register name

    // Memory errors
    MEM_ERR_GENERIC = 6000,
    MEM_ERR_SPACE,                      // Invalid memory space
    MEM_ERR_ACCESS_SIZE,                // Access size not supported
    MEM_ERR_ADDRESS,                    // Invalid or out of range address

    // Event errors 
    EVT_ERR_GENERIC = 7000,
    EVT_ERR_ADDRESS,                    // Invalid or out of range address
    EVT_ERR_SPACE,                      // Invalid memory space
    EVT_ERR_TYPE,                       // Unsupported event type

    // Execution errors
    EXE_ERR_GENERIC = 8000,
    EXE_ERR_TARGET_RUNNING              // Invalid action while running
}SDTI_ERRORS, * PSDTI_ERRORS;


/*---- global data declarations --------------------------------------------*/

/*---- global function prototypes ------------------------------------------*/
#ifdef GLOBAL
    #undef GLOBAL
#endif
#ifdef sdti_c
   #define GLOBAL 
#else
   #define GLOBAL extern
#endif

GLOBAL int 
SDTI_GetInterface( void ** pInterface, char *pFamily );

#ifdef __cplusplus
}
#endif

#endif /* inf_h ------- END OF FILE ----------------------------------------*/