rdi150.h

做ARM仿真器和调试器的厂商需要RDI协议

/* RDI 1.5.0 definitions
   Copyright (C) 2001 Free Software Foundation, Inc.


This file is part of GDB.


GDB is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version.


GDB is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.


You should have received a copy of the GNU General Public License
along with GDB; see the file COPYING.  If not, write to the Free
Software Foundation, 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.  */


/*
 * RCS $Revision: 1.25 $
 * Checkin $Date: 2000/10/05 13:47:15 $
 * Revising $Author: hbullman $
 */

#ifndef rdi150_h
#define rdi150_h

#include "toolconf.h"

#if RDI_VERSION == 150


#  define RDI150_OpenAgentProc RDI_OpenAgentProc
#  define RDI150_CloseAgentProc RDI_CloseAgentProc
#  define RDI150_OpenProc RDI_OpenProc
#  define RDI150_CloseProc RDI_CloseProc
#  define RDI150_ReadProc RDI_ReadProc
#  define RDI150_WriteProc RDI_WriteProc
#  define RDI150_CPUReadProc RDI_CPUReadProc
#  define RDI150_CPUWriteProc RDI_CPUWriteProc
#  define RDI150_CPReadProc RDI_CPReadProc
#  define RDI150_CPWriteProc RDI_CPWriteProc
#  define RDI150_SetBreakProc RDI_SetBreakProc
#  define RDI150_ClearBreakProc RDI_ClearBreakProc
#  define RDI150_SetWatchProc RDI_SetWatchProc
#  define RDI150_ClearWatchProc RDI_ClearWatchProc
#  define RDI150_ExecuteProc RDI_ExecuteProc
#  define RDI150_StepProc RDI_StepProc
#  define RDI150_InfoProc RDI_InfoProc
#  define RDI150_PointInquiryProc RDI_PointInquiryProc
#  define RDI150_AddConfigProc RDI_AddConfigProc
#  define RDI150_LoadConfigDataProc RDI_LoadConfigDataProc
#  define RDI150_SelectConfigProc RDI_SelectConfigProc
#  define RDI150_NameListProc RDI_NameListProc
#  define RDI150_ErrMessProc RDI_ErrMessProc
#  define RDI150_LoadAgentProc RDI_LoadAgentProc
#  define RDI150_TargetIsDeadProc RDI_TargetIsDeadProc
#  define RDI150_ProcVec RDI_ProcVec
#  define RDI150_ConfigPointer RDI_ConfigPointer

#endif


/*
 * RDI 1.50:  An introduction
 * --------------------------
 *
 * This file, which originally contained the definition for RDI 1, has been
 * extended (through conditional compilation via the RDI_VERSION macro) to
 * additionally include the definition of RDI 1.50.
 *
 * To use RDI 1, then RDI_VERSION should either be undefined, or be defined thus
 *     #define RDI_VERSION 100
 *
 * To use RDI 1.50, then RDI_VERSION should be defined this
 *     #define RDI_VERSION 150
 *
 * CHANGES
 * -------
 * Most RDI functions have had one additional parameter added
 *  RDI_ModuleHandle mh
 * This qualifies the functions for use in a debuggee with:
 *  multi ARM processors
 *  coprocssors that can run their own instructions
 *
 * BACKWARD COMPATIBILITY
 * ----------------------
 * The new framework can use existing debuggees.
 * To this effect error codes, structures, typedefs and flag bit positions
 * must remain as they are. The new RDI provides additional functionality
 * with minimal change.
 *
 * THREADS
 * -------
 * Threads will be dealt with in a later OS dependent interface.
 * ThreadHandles are included, for future use, in break and watch points.
 * Note: There is no method for obtaining ThreadHandles in the RDI.
 *
 */

/* opaque handle types */
typedef struct RDI_OpaqueAgentStateStr RDI_AgentState;
typedef RDI_AgentState *RDI_AgentHandle;

typedef struct RDI_OpaqueModuleStateStr RDI_ModuleState;
typedef RDI_ModuleState *RDI_ModuleHandle;

/* type used for RDIInfo_Modules */
typedef struct RDI_ModuleDesc {
  char type[8];                 /* fill in with name - e.g. "ARM", "ETM" */
  char name[8];                 /* unique name of this instance e.g. "ARM_1" */
  struct RDI_ProcVec const *rdi;      /* NULL for "same as agent" */
  RDI_ModuleHandle handle;
} RDI_ModuleDesc;

/*
 * 27 July 2000
 *
 * Additional definition for RDI_ModuleDesc explicitly showing the small,
 * medium and large formats.
 *
 * RDI_ModuleDesc and RDI_ModuleDesc_Extra MUST remain binary compatible.
 */
typedef struct RDI_ModuleDesc_Extra
{ 
    char type[8];
    union { 
        char shortname[8]; 
        struct { 
            char quote; 
            char string[7]; 
        } mediumname;   /* Use of mediumname to be deprecated where possible */
        struct { 
            char s[4]; 
            char const *string; 
        } longname; 
    } name; 
  struct RDI_ProcVec const *rdi;
  RDI_ModuleHandle handle;

} RDI_ModuleDesc_Extra;

/**********************************************************************/

/*
 * RDI Implementation Prototypes
 */


/*
 *  Function:   RDI_OpenAgent
 *   Purpose:   Initialisation routine for debug agent, which supports both
 *              hot and cold calls; the cold call is guaranteed to be the
 *              very first call made from the debugger into the debuggee.
 *
 *      Input:  type
 *                  b0          0   cold start
 *                              1   warm start
 *                  b1          1   reset the comms link
 *                  b2          0/1 little/big endian
 *                  b3          1   return endian
 *
 *              config          structure containing configuration
 *                              information
 *
 *              hostif          used for reading/writing to a console
 *
 *              dbg_state       handle to identify the current Debugger
 *                              state, or an umbrella-agent if toolconf
 *                              tag "CONTROLLER_ISAGENT" is set.
 *
 *     In/Out:  agent           cold start:     passed in as NULL, returns
 *                                              pointer to debug agent instance
 *
 *                              warm start:     pointer to debug agent instance
 *
 *  Returns:                                 b3     b2
 *      Error:  RDIError_SoftInitialiseError X      X   If things go wrong!
 *      Error:  RDIError_WrongByteSex        0      E   bad match
 *      OK:     RDIError_NoError             0      E   match
 *      OK:     RDIError_LittleEndian        1      X
 *      OK:     RDIError_BigEndian           1      X
 *
 * Post-conditions: If no error occured, then *agent will contain a pointer
 *                      to the debug agent instance (newly created if a cold
 *                      start), and all parts of the system other than the
 *                      Processor modules will have seen the open too.
 */

struct RDI_LibraryData;  /* Opaque type - see rditools.h */

/* This is passed to sub-agents by an umbrella-agent during openagent. */
typedef struct RDI_DbgStateForSubAgent
{
    size_t size; /* Must be sizeof(RDI_DbgStateForSubAgent) */
    RDI_ModuleDesc *agent_desc; /* Really an Agent */
    RDI_ModuleDesc *parent_desc; /* Really a Module */
    /* This allows a sub-agent to use its parent's set of DLLs */
    struct RDI_LibraryData *lib_handle;
} RDI_DbgStateForSubAgent;

typedef toolconf RDI150_ConfigPointer;

typedef int RDI150_OpenAgentProc(
    RDI_AgentHandle *agent, unsigned type, RDI150_ConfigPointer config,
    struct RDI_HostosInterface const *i, RDI_DbgState *dbg_state);


/*
 * Function:    RDI_CloseAgent
 *  Purpose:    Equivalent to the debuggee destructor.
 *              Ensure that all processors are also closed down
 *              Release any memory and close down the emulator.
 *              Only an RDI_open call can follow.
 *
 *  Params:     agent - handle of agent to close down
 *
 *  Returns:    RDIError_NoError
 */
typedef int RDI150_CloseAgentProc(RDI_AgentHandle agent);


/*
 * Function:    RDI_OpenProc
 *  Purpose:    This is the Initialization routine and as such is the first
 *              call made to the RDI. It allows the program to set up the
 *              initial debuggee working environment. It will be called
 *              later if the emulator is to be reset. There are hot and
 *              cold calls. On the very first cold call is equivalent to a
 *              constructor when memory should be claimed.
 *              The initialization also provides a console window for
 *              reading and writing text. This can be used now and in the
 *              future for messages. The call provides information on the
 *              settings on the debugger.
 *
 *  Pre-conditions:
 *
 *  Params:
 *      Input:  handle          Processor module handle
 *
 *              type
 *                  b0          0   cold start
 *                              1   warm start
 *                  b1          1   reset the comms link
 *                  b2          0/1 little/big endian
 *                  b3          1   return endian
 *
 *              config          structure containing configuration
 *                              information
 *
 *              hostif          used for reading/writing to a console
 *
 *              dbg_state       handle to identify the current Debugger
 *                              state
 *
 *  Returns:                                 b3     b2
 *      Error:  RDIError_SoftInitialiseError X      X   If things go wrong!
 *      Error:  RDIError_WrongByteSex        0      E   bad match
 *      OK:     RDIError_NoError             0      E   match
 *      OK:     RDIError_LittleEndian        1      X
 *      OK:     RDIError_BigEndian           1      X
 */
typedef int RDI150_OpenProc(
    RDI_ModuleHandle rdi_handle, unsigned type, RDI150_ConfigPointer config,
    struct RDI_HostosInterface const *i, RDI_DbgState *dbg_state);


/*
 * Function:    RDI_CloseProc
 *  Purpose:    Close down an individual processor.
 *              > ISSUE <
 *              Behaviour is currently undefined if only a subset of
 *              processors are 'open' and execution is requested.
 *
 *  Params:     mh - Handle of processor to close down
 *
 *  Returns:    RDIError_NoError
 */
typedef int RDI150_CloseProc(RDI_ModuleHandle mh);


/*
 * Access types for RDI(Read,Write}Proc
 */
typedef enum {
  RDIAccess_Data = 0,
  RDIAccess_Data8,
  RDIAccess_Data16,
  RDIAccess_Data32,
  RDIAccess_Data64,
  RDIAccess_Code = 8,
  RDIAccess_Code8,              /* Not used at present */
  RDIAccess_Code16,
  RDIAccess_Code32,
  /* Not used yet - we don't model prefetch units that well. */
  RDIAccess_Code64
} RDI_AccessType;


#ifdef OldCode /* Nothing uses these. */
/*
 * 2000-03-16 dsinclai
 * ARMulator 3 access-function options.
 */
# define RDIAccess_Read 0x10
# define RDIAccess_Write 0x20
# define RDIAccess_ByteLanes 0x40
#endif


/*
 * 1999-12-07
 * UNDER CONSTRUCTION - RDI for NDI
 * (these may become 16 and 32 when we re-align ARMISS and ARMulator).
 */
/* This is >not< a debugger-access, so >do< cycle-count it and
 * do not use the debugger's endianness. */
#define RDI_AccessType_NotForDebugger 0x100
/* This is a debugger-access to physical memory, so don't address-translate */
#define RDI_AccessType_Physical 0x200
/* This is an access between one emulated module and another. */
#define RDI_AccessType_HostEndian 0x400

/*
 * Function:    RDI_ReadProc
 *  Purpose:    Read memory contents in byte format from the debuggee.
 *              read *nbytes of data from source address and write to dest
 *              in the caller's address space using the processor specified.
 *
 *              Assuming nothing went wrong with the transfer, the debuggee
 *              will normally return RDIError_NoError.  However, if the
 *              debuggee has changed its byte sex, it should return a
 *              notification of this change, i.e. either RDIError_BigEndian
 *              or RDI_ErrorLittleEndian; the caller must then acknowledge
 *              this notification by calling RDI_Info RDIInfo_AckByteSex.
 *              The debuggee will keep returning this notification until an
 *              acknowledgement has been received.
 *
 *  Params:
 *      Input:  mh          handle identifies processor
 *
 *              source      address