/*H***************************************************************************
*
* $Archive:: /TI/product/sdtsrv/USER/Sdti.h                                  $
* $Revision:: 7                                                              $
* $Date:: 7/30/02 10:33a                                                     $
* $Author:: Tonyc                                                            $
*
* DESCRIPTION:
*
* USAGE/LIMITATIONS:
*
* NOTES:
*   
* (C) Copyright 2000 by Spectrum Digital Incorporated
* All rights reserved
*
*H***************************************************************************/

#ifndef sdti_h
#define sdti_h

/*---- compilation control switches ----------------------------------------*/

/*****************************************************************************
* INCLUDE FILES (minimize nesting of header files)
*****************************************************************************/
#if defined( _WIN32 )
    #if (_MSC_VER >= 900 )
       #define	WIN32_LEAN_AND_MEAN
       #define 	INC_OLE2
       #define	NOSERVICE
    #endif 

    #include <windows.h>
#else  
    #include <stdlib.h>
    #include <string.h>
    #include <file.h>
	// Define BOOL if not in a WIN32 environment
	#define BOOL int   
#endif
/*---- system and platform files -------------------------------------------*/

/*---- program files -------------------------------------------------------*/

/*****************************************************************************
* FILE CONTENT
*****************************************************************************/
#ifdef __cplusplus
extern "C" {
#endif

/*****************************************************************************
* FUNCTIONAL AREA DETAIL
*****************************************************************************/
//----------------------------------------------------------------------------
// Interface Version/Revision 
//
#define SDTI_VERSION        2
#define SDTI_REVISION       1

//----------------------------------------------------------------------------
// Sub-Interface Version/Revision 
//
#define SDTI_CFG_VERSION        1
#define SDTI_CFG_REVISION       1

#define SDTI_REG_VERSION        1
#define SDTI_REG_REVISION       1

#define SDTI_MEM_VERSION        2
#define SDTI_MEM_REVISION       1

// REVISION 2 - changes
// 1) Set unused bits of TREG to 0 on read
#define SDTI_EVT_VERSION        1
#define SDTI_EVT_REVISION       2

// 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.
#define SDTI_EXE_VERSION        1
#define SDTI_EXE_REVISION       2

//----------------------------------------------------------------------------
// Interface handle
//
typedef void * SDTI_HNDL;

//----------------------------------------------------------------------------
// Target register types
//
typedef unsigned char  TREG_8;			// 8-bit register
typedef unsigned short TREG_16;			// 16-bit register
typedef unsigned long  TREG_32;			// 32-bit register

typedef struct treg_64					// 33-64 bit register
{
    unsigned long   RegL;
    unsigned long   RegH;
}TREG_64, *PTREG_64;

typedef union treg
{
    TREG_8   Reg8;
    TREG_16  Reg16;
    TREG_32  Reg32;
    TREG_64  Reg64;
}TREG, * PTREG;

// TREG_DESC is used by sdti_regXXX.c to describe each target register
// 
typedef struct treg_desc
{
    char    *pRegName;		// Register name, hopefully match the data book
    int     RegSize;		// Read/Write size of the register
    int     RegId;			// An Id for the register, not really used
} TREG_DESC, * PTREG_DESC;

//----------------------------------------------------------------------------
// Target memory types
//
// For Harvard devices the memory space can be Program or Data.  For 
// compatibility with TI DSP there is also an I/O space.
// If the processor is not Harvard then use the default of M_NATURAL.
//
// MEM_ACCESS_SIZE provides a way to force target processor accesses
// to a certain access boundary.  This is generally required by byte
// addressable processors with I/O device access size restrictions.
// Some common rules to apply:
// 
// 1) If your processor is a 16 bit fixed point DSP that can only
//    perform 16 bit read/writes then use M_SIZE16 or M_SIZE_NATURAL.
//
// 2) If your processor is a 32 bit fixed point DSP that can only
//    perform 32 bit read/writes then use M_SIZE32 or M_SIZE_NATURAL.
//
// 3) If you processor is a byte addressable machine and you are
//    fetching program or data memory then M_SIZE_NATURAL is recommended.
//    Else, use the size that matches your processor bus width.
//
// 4) For other cases use the size that matches the access restrictions
//    of your I/O or memory devices.
//
// The arguments in TMEM_DESC are pretty obvious with exception
// of Asize and Bsize.  Asize is the access size of the processor
// memory read/write operation, see rules above.  Bsize is the
// size of an element in the read/write buffer.  By having the
// Bsize option the user can pass in a pointer to a 32 bit buffer
// that only has 16 bits of valid data in each 32 bit element.
// Example:
//    unsigned long  *pD32;
//    unsigned short *pD16;
// 
//    *pD32++ = (unsigned long)(*pD16++) & 0x0000FFFFL;
//
// Another example is when the buffer size is smaller then the
// target processor access size.  This is generally the case
// on a fixed point DSP where you want "char" data that is
// 8 bit instead of the 16 bit DSP "char".
// Example:
//     unsigned char *pD8;   // Host 8 bit char data
//     unsigned char *pD16;  // DSP 16 bit data
//  
//     *pD8++ = (unsigned char)(*pD16++);
//
// When the Asize and Bsize do not match the unused data bits
// are set to zero.
//
typedef enum mem_space
{
    M_NATURAL = 0,          // Natural space for processor, !Harvard
    M_PROGRAM,              // Program space
    M_DATA,                 // Data space
    M_IO                    // I/O space
}MEM_SPACE, * PMEM_SPACE;

typedef enum mem_access_size
{
    M_SIZE_NATURAL = 0,     // Natural size of processor memory bus
    M_SIZE8,                // 8-Bit
    M_SIZE16,               // 16-Bit
    M_SIZE32,               // 32-Bit
    M_SIZE64,               // 64-Bit
    M_COFF                  // Preserve TI-COFF accesses
}MEM_ACCESS_SIZE, * PMEM_ACCESS_SIZE;

typedef unsigned long   MEM_TADDR;  // 32 Bit memory address

typedef struct tmem
{
    MEM_TADDR           Taddr;      // Target address
    MEM_SPACE           Space;      // Target memory space
    MEM_ACCESS_SIZE     Asize;      // Target memory access size
    MEM_ACCESS_SIZE     Bsize;      // Host memory buffer access size
    unsigned long       Length;     // Number of elements in ACCESS_SIZE
    void            *   pData;      // Src/Dst data
} TMEM_DESC, *PTMEM_DESC;

//----------------------------------------------------------------------------
// Target event types
//
typedef enum evt_type
{
    EVT_NONE     = 0,               // No event
    EVT_HALT,                       // Target halted, by user or non-brkpoint
    EVT_SWBP,                       // Software
    EVT_HWIAQ,                      // Hardware break, Instruction
    EVT_HWDATA                      // Hardware break, Data access
}EVT_TYPE, * PEVT_TYPE;

typedef enum evt_system
{
    EVT_SYS_NONE     = 0,           // No event
	EVT_SYS_WARN,                   // Generic warning, not an error
    EVT_SYS_ERROR,                  // Generic non-target error
    EVT_SYS_TARGET,                 // Generic target error
    EVT_SYS_TARGET_DISCONNECT,      // Target is disconnected
    EVT_SYS_TARGET_LOSSPOWER,       // Target lost power
    EVT_SYS_TARGET_TIMED_OUT,       // Target operation timed out
    EVT_SYS_TARGET_IN_RESET,        // Target is being held in reset
    EVT_SYS_TARGET_NOT_READY,       // Target is being held not ready
    EVT_SYS_TARGET_BUS_FAULT,       // Target performed a bus fault     
}EVT_SYSTEM, * PEVT_SYSTEM;

typedef struct tevt
{
    unsigned            EvtId;      // The event Id
    MEM_TADDR           Taddr;      // Target address
    MEM_SPACE           Space;      // Target memory space
    EVT_TYPE            Type;       // Type of breakpoint
} TEVT_DESC, *PTEVT_DESC;

typedef struct tevt_stat
{
    // Event information that pertains to breakpoint type events
    unsigned            EvtId;      // The event Id
    MEM_TADDR           Taddr;      // Target address
    MEM_SPACE           Space;      // Target memory space
    EVT_TYPE            Type;       // Type of breakpoint
    
    // Event information that pertains to error type events
    EVT_SYSTEM          System;     // System events 
    int                 Error;
}TEVT_STAT_DESC, *PTEVT__STAT_DESC;

/*A***************************************************************************
* NAME:  Spectrum Digital Target Interface
*
* USAGE: Interface that can sit on top of GTI, OTI or others.  The 
*        interface is processor independent and you can specify your
*        "cpu" family during initialization.  Further, argument options that
*        do not cleanly fit into generic data types are passed in as 
*        strings.  This allows any number of options to be supported without
*        continually changing the interface.
*
* CONNECTION:
*        The interface has only 1 external function "SDTI_GetInterface. The
*        user calls this functions to get a pointer to the "Interface" which
*        contains configuration information plus all the functions (methods)
*        for the interface. You then access functions as follows:
*
*        pIntf->pCfg->Init(...);
*        pIntf->pCfg->Open(...);
*
*        The function SDTI_GetInterface includes a parameter pTargetFamily.
*        This parameter specifies which target processor you are targeting.
*        If the requested target family is not supported then NULL is 
*        returned for the interface.
*
*        This style of interface is most significant when  built as
*        a DLL and explicitly loaded by the caller.  In this case you only
*        have to get a reference to one function "SDTI_GetInterface" then
*        call it to get everything you need to know about the interface.
*
* VERSION/REVISION:
*         The interface provides a version/revision.  The caller should 
*         always check for interface version/revision compatibility.  
*         "Version" changes when a significant change to the interface 
*         occurs that would effect backward compatibility.  "Revision"
*         changes when a minor change occurs that would not affect backward
*         compatibility.  You can also use sizeof( SD_TARGET_INTERFACE )
*         and compare to "StructSz" for another level of checking.
* 
* RETURN : 
*         Return types follow the Microsoft convention 
*         1 - True/Success.  The function completed without error.