rdi150.h

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

 *                      processors is not supported on the target
 *                  or
 *                      if stop_others = TRUE and the particular configuration
 *                      of running the specified processor and stopping others
 *                      is not permitted, even though other 'stop_others'
 *                      configurations are supported.
 */
typedef int RDI150_ExecuteProc(
    RDI_AgentHandle agent, RDI_ModuleHandle *mh, bool stop_others, 
    RDI_PointHandle *handle);


/*
 * Function:    RDI_StepProc
 *  Purpose:    Steps the debuggee from the current state.
 *              The debuggee continues until a natural exit occurs
 *              or the specified processor completes its next instruction.
 *              If a processor if not specified (RDINoHandle) then the exit
 *              shall be when any processor reaches its next instruction
 *              completion. The reason for exit is returned.
 *
 *  Params:
 *      Input:  agent   Identifies the debug agent.
 *      Input:  stop_others
 *                      TRUE => Only run the specified processor (*mh).  All
 *                              other processors remain halted
 *                      FALSE =>Start the whole target running
 *
 *      InOut:  *mh
 *          In:         identifies a specific processor to step.  In the absence
 *                      of other exit conditions, the execution will halt when
 *                      the specified processor completes a step.
 *
 *                      if (*mh == RDINoHandle), then in the absence of other
 *                      exit conditions, the execution will halt when any
 *                      processor completes a step.
 *
 *          Out:        Handle of the processor that caused the exit.
 *                      If no specific processor caused the exit, this is the
 *                      handle of any valid processor.
 *
 *      Output: *point  if (return == RDIError_BreakpointReached)
 *                          handle of breakpoint
 *                      if (return == RDIError_WatchpointAccessed)
 *                          handle of watchpoint
 *                      else RDINoHandle
 *                      In the current Demon debuggee the handles are not set.
 *                      Here the debugger is required to fetch the pc to
 *                      determine the point.
 *                      (Demon condition is (pointReached && RDINoHandle))
 *
 *  Returns:
 *      OK:         RDIError_NoError
 *      OK:         RDIError_BreakpointReached    Breakpoint reached
 *      OK:         RDIError_WatchpointAccessed   Watch point accessed
 *      OK:         RDIError_UserInterrupt        User stop via RDISignal_Stop
 *
 *      Vector Catches (see RDIVector_Catch Info call)
 *      OK:         RDIError_BranchThrough0       Branch through zero
 *      OK:         RDIError_UndefinedInstruction Undefined instruction
 *      OK:         RDIError_SoftwareInterrupt    Software interrupt
 *      OK:         RDIError_PrefetchAbort        Prefetch abort
 *      OK:         RDIError_DataAbort            Data abort
 *      OK:         RDIError_AddressException     Address exception
 *      OK:         RDIError_IRQ                  Interrupt (IRQ)
 *      OK:         RDIError_FIQ                  Fast Interrupt (FRQ)
 *      OK:         RDIError_Error                Error (see RDIErrorP)
 *
 *      Error:      RDIError_UnimplementedMessage under the following conditions
 *                      if stop_others = TRUE and *mh = RDINoHandle
 *                  or
 *                      if stop_others = TRUE and stopping of individual
 *                      processors is not supported on the target
 *                  or
 *                      if stop_others = TRUE and the particular configuration
 *                      of running the specified processor and stopping others
 *                      is not permitted, even though other 'stop_others'
 *                      configurations are supported.
 */
typedef int RDI150_StepProc(
    RDI_AgentHandle agent, RDI_ModuleHandle *mh, bool stop_others,
    unsigned ninstr, RDI_PointHandle *handle);


/* The argument to rdi_info_proc is either an RDI_ModuleHandle (for the
 * majority of calls) or an RDI_AgentHandle (for a small number of
 * "Agent" calls). Which it is depends on the info code. Unless otherwise
 * stated (above) all calls take a ModuleHandle.
 */

/*
 * Function:    RDI_InfoProc
 *  Purpose:    Used to transfer miscellaneous information between the
 *              Debuger and the Debuggee. The parameters meanings change for
 *              each information type.
 *              Each type is defined in RDI_Info subcodes.
 *
 *  Params:
 *      Input:  mh          handle identifies processor
 *                          if RDINoHandle this is general target information
 *                          (e.g. hadware configuration) ?? This looks wrong ??
 *      Input:  type        Information type code
 *
 *      Use of arg parameters varies dependent on type code.
 *      See each individual definition below.
 *      InOut:  arg1        parameter 1
 *      InOut:  arg2        parameter 2
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      OK:     codes dependent on type
 *      Error:  codes dependent on type
 *      Error:  RDIError_UnimplementedMessage (unimplemented functions)
 */
typedef int RDI150_InfoProc(
    void *, unsigned type, ARMword *arg1, ARMword *arg2);


/*
 * Function:    RDI_PointinqProc
 *  Purpose:    Breakpoint or watchpoint inquiry.
 *              Used to check before setbreak or setwatch is used.
 *              Returns what will happen if a corresponding call is made
 *              to setbreak or setwatch.
 *
 *  Params:
 *      Input:  mh          handle identifies processor
 *      Input:  type        see setbreak or setwatch for definition
 *      Input:  datatype    0       breakpoint
 *                          != 0    see setwatch for definition
 *      InOut:  *address
 *          In:             address of point
 *          Out:            set to actual value that will be used
 *      InOut:  *bound
 *          In:             upper address range
 *          Out:            set to actual value that will be used
 *      @@@ MJW notes: it's not passed a ThreadHandle
 *      Output: none
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      Error:  RDIError_NoMorePoints (if cannot set)
 */
typedef int RDI150_PointInquiryProc(
    RDI_ModuleHandle, ARMword *address, unsigned type, unsigned datatype,
    ARMword *bound);

/*
 * Function:    RDI_AddConfigProc
 *  Purpose:    Declares the size of a config block about to be loaded.
 *              Only use if RDIInfo_DownLoad returns no error.
 *
 *  Params:
 *      Input:  agent   handle identifies degug agent
 *
 *              nbytes  size of configuration block to follow
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      Error:  RDIError_UnimplementedMessage (unimplemented functions)
 */
typedef int RDI150_AddConfigProc(RDI_AgentHandle agent, unsigned32 nbytes);


/*
 * Function:    RDI_LoadConfigDataProc
 *  Purpose:    Loads the config block.
 *              The block specifies target-dependent information to the
 *              debuggee. (e.g. ICEman)
 *              Only use if RDIInfo_DownLoad returns no error.
 *
 *  Params:
 *      Input:  agent   handle identifies debug agent
 *
 *              nBytes  size of block (as declared in addconfig)
 *
 *              data    source of block
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      Error:  RDIError_UnimplementedMessage (unimplemented functions)
 */
typedef int RDI150_LoadConfigDataProc(
    RDI_AgentHandle agent, unsigned32 nbytes, char const *data);


/*
 * Function:    RDI_SelectConfigProc
 *  Purpose:    Selects which of the loaded config blocks should be used
 *              and then reinitialises the Debuggee to use the selected
 *              config data.
 *              Only use if RDIInfo_DownLoad returns no error.
 *
 *  Params:
 *      Input:  mh          handle identifies processor
 *                          > ISSUE < Specification says 'processor', but
 *                          implmentation says 'agent'.  Surely processor
 *                          is required, in case the aspect = ConfigCPU.
 *
 *              aspect      RDI_ConfigCPU or RDI_ConfigSystem
 *
 *              name        name of the configuration to be selected
 *
 *              matchtype   specifies exactly how the version number
 *                          must be matched
 *                              RDI_MatchAny
 *                              RDI_MatchExactly
 *                              RDI_MatchNoEarlier
 *
 *              versionreq  the version number requested
 *
 *      Output: *versionp   the version actually selected
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      Error:  RDIError_UnimplementedMessage (unimplemented functions)
 */
typedef int RDI150_SelectConfigProc(
    RDI_AgentHandle, RDI_ConfigAspect aspect, char const *name,
    RDI_ConfigMatchType matchtype, unsigned versionreq, unsigned *versionp);

/*
 * Function:    RDI_LoadAgentProc
 *  Purpose:    Loads a replacement EmbeddedICE ROM image, and starts it
 *              (in RAM).
 *              Only if RDIInfo_Target returns a value with
 *              RDITarget_CanReloadAgent set.
 *
 *  Params:
 *      Input:  agent       handle identifies agent
 *      Input:  dest        address in the Debuggee's memory where the new
 *                          version will be put
 *      Input:  size        size of the new version
 *      Input:  getb        a function that can be called (with getbarg as
 *                          the first argument) and the number of bytes to
 *                          down load as the second argument.
 *      InOut:  none
 *      Output: none
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      Error:  RDIError_UnimplementedMessage (unimplemented functions)
 */
typedef int RDI150_LoadAgentProc(
    RDI_AgentHandle, ARMword dest, unsigned32 size, RDI_GetBufferProc *getb,
    RDI_GetBufferArg *getbarg);


/*
 * Function:    RDI_TargetIsDeadProc
 *  Purpose:    Used to inform local device drivers that a remote
 *              (typically hardware) debuggee is unresponsive.
 *
 *  Params: 
 *      Input:  agent
 *
 *  Returns:
 *      OK:     RDIError_NoError
 *      Error:  RDIError_UnimplementedMessage
 */
typedef int RDI150_TargetIsDeadProc(RDI_AgentHandle agent);


/*
 * Function:    RDI_ErrMessProc
 *  Purpose:    Gets an error message corresponding to the error number.
 *
 *  Params:
 *      Input:  agent
 *      Input:  buflen      length of the buffer
 *      Input:  errnum      the error number
 *      InOut:  none
 *      Output: buf         destination for the message
 *
 *  Returns:    errmessproc returns the number of bytes written,
 *                rather than an RDIError
 */
typedef int RDI150_ErrMessProc(
    RDI_AgentHandle agent, char *buf, int buflen, int errnum);

/*
 * Function:    RDI_CPUNamesProc and RDI_DriverNamesProc
 *  Purpose:    Get a list of names.
 *              The returned structure contains the number of names
 *              and a list of pointers to the sz names.
 *              The index to the chosen name is used in RDI 1.0 only:
 *                  RDI_ConfigBlock.procesor    (RDI 1.0)
 *                  RDI_ConfigBlock.drivertype
 *              This is used to select a harware driver for the target
 *              or a processor from a processor family.
 *              E.g. If the processor family was PROCESSOR_ARM
 *              the list would show the members of that family
 *              (ARM6, ARM7 etc.)
 *  Params:
 *      Input:  handle      handle identifies processor in cpunames
 *                          RDI_NoHandle for drivernames
 *                          (i.e. target hadware configuration)
 *      InOut:  none
 *      Output: none
 *
 *  Returns:
 *      OK:     RDI_NameList
 *      Error:  none
 */
typedef RDI_NameList const *RDI150_NameListProc(RDI_AgentHandle handle);

typedef struct RDI150_ProcVec
{
    char rditypename[12];

    RDI150_OpenAgentProc       *openagent;
    RDI150_CloseAgentProc      *closeagent;
    RDI150_OpenProc            *open;
    RDI150_CloseProc           *close;
    RDI150_ReadProc            *read;
    RDI150_WriteProc           *write;
    RDI150_CPUReadProc         *CPUread;
    RDI150_CPUWriteProc        *CPUwrite;
    RDI150_CPReadProc          *CPread;
    RDI150_CPWriteProc         *CPwrite;
    RDI150_SetBreakProc        *setbreak;
    RDI150_ClearBreakProc      *clearbreak;
    RDI150_SetWatchProc        *setwatch;
    RDI150_ClearWatchProc      *clearwatch;
    RDI150_ExecuteProc         *execute;
    RDI150_StepProc            *step;
    RDI150_InfoProc            *info;
    RDI150_PointInquiryProc    *pointinquiry;

    /* These three useable only if RDIInfo_DownLoad returns no error */
    RDI150_AddConfigProc       *addconfig;
    RDI150_LoadConfigDataProc  *loadconfigdata;
    RDI150_SelectConfigProc    *selectconfig;

    RDI150_NameListProc        *drivernames;
    RDI150_NameListProc        *cpunames;

    RDI150_ErrMessProc         *errmess;

    /* Only if RDIInfo_Target returns a value with RDITarget_LoadAgent set */
    RDI150_LoadAgentProc       *loadagent;
    RDI150_TargetIsDeadProc    *targetisdead;
} RDI150_ProcVec;


#endif

/* EOF rdi150.h */