acecpu32backend.h

vxworks源码源码解读是学习vxworks的最佳途径

/* acecpu32Backend.h - header file for ACE SuperBDM BDM emulator back end */

/* Copyright 1993-1996 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01p,10dec96,bss  removed dead code.
01o,23oct96,bss  added Ace_T::cacheTxtUpdate_m().
01n,17oct96,bss  clean-up.
01m,02oct96,bss  fixed clash between WRS's ERROR and MSVC's ERROR macros.
01l,26jul96,bss  removed WPWR_SHUTDOWN().
01k,11jul96,bss  WIN32 port.  Added EXT_FUNC support.
01j,15may96,bss  added exception state management.
01i,01may96,bss  tweaked comments.
01h,30apr96,bss  moved the back end connect/disconnect functionality into Ace_T.
01g,26apr96,bss  coding convention cleanup.
01f,16apr96,bss  removed intLock_m ()/intUnlock_m ().
01e,16apr96,bss  removed stateMon_m () and stateRet_m ().
01d,26mar96,bss  Added intLock_m ()/intUnlock_m () to fix single step bug.
                 Added reg1Set_m ().
01c,25mar96,bss  Added bpEventGen_m ().
01b,17mar96,bss  Added stateMon_m() and stateRet_m ().
01a,06mar96,bss  written.
*/


#ifndef __INCacecpu32Backendh
#define __INCacecpu32Backendh

////////////////////////////////////////////////////////////////////////////////
// acecpu32Backend Architecture
//
// This module implements the vendor-specific back end class, 
// Ace_T, for the ACE SuperBDM BDM emulator for the Motorola CPU32
// microprocessor.  The vendor-specific back end class, Ace_T,
// is derived from the abstract base class Backend_T, which
// provides a back end framework, and generic back end functionality,
// like gopher and checksum.
//
// Ace_T member functions perform basic back end services, like 
// accessing memory and registers, setting breakpoints, etc.
// Typically, Ace_T member functions just manage target state, 
// marshall data in to and out of data structures, and invoke the 
// appropriate ACE API function to operate the emulator.

////////////////////////////////////////////////////////////////////////////////
// acecpu32Backend Event Handling.
//
// A crucial part of any debugging tool is the handling target events.
// The target server learns about the occurrance of a target event
// in two ways:  it can be asynchronously notified of an event
// via activity on an user-specified, event file descriptor, which it
// monitors; or, it can call Backend_T::evtPending_m() to check
// if an event has occurred.  If an event has occurred, the target
// server will call Backend_T::eventGet_m() to get WDB information about
// the event.  The event is then cleared by Backend_T::evtPendingClear_m().
//
// To support asynchronous event notification, the vendor-specific
// back end must provide the target server with an event file descriptor.
// The event file descriptor can provide asynchronous event notification
// because the target server spins in a loop, calling select() to
// wait for activity on a set of file descriptors.  If the event
// file descriptor is active, the target server will process the
// event by calling Backend_T::eventGet_m(), as described above.
// If another file descriptor is active, the target server will
// provide the appropriate service.  The event file descriptor must be 
// stored in the TGT_OPS data structure's eventFd field so that the
// target server can wait for activity on it.  A vendor-specific back 
// end must support the fdGet_m() method, which returns the file 
// descriptor used as the event file descriptor.
//
// When the ACE API detects an event, it calls the call back 
// Ace_T::eventCallBack(), which captures the necessary information
// about the event by constructing an Event_T object.  The Event_T
// object is then stored on an event queue until the target server
// requests information about the event.  The event is then dequeued,
// and passed to the target server.  Event_T and the event queue
// use Rogue Wave's Tools.h++ library.  Event_T is implemented in
// event.h and event.cpp.
//

////////////////////////////////////////////////////////////////////////////////
// Handling of Exceptions on Target
//
// To successfully handle exceptions, a back end must 
// notify the target server when exceptions occur, and
// the back end must report the correct information.
// ACE's emulator does not directly provide notification
// exceptions which occur on the target.  Consequently,
// notification of target exceptions is provided by an exception
// handling hook which is installed on the target, and executes
// the 'bgnd' instruction whenever an exception occurs. 
// The exception handling hook is installed using vxWorks's
// undocumented _func_excBaseHook function pointer.  Whenever
// a target exception occurs, vxWorks's exception handler
// will invoke the function stored in _func_excBaseHook.
// This exception hook runs at exception time, stores exception
// information in a global variable on the target, and notifies
// the host of the exception by executing the 'bgnd' instruction,
// which puts the target in BDM mode.  ACE's API detects that
// the 'bgnd' instruction was executed, and generates an
// ACE_SIGNAL event.  Ace_T::eventCallBack() then handles the 
// event in the normal fashion.
//
// To implement the target exception notification hook,
// first install the hook:
//
//      #include "vxWorks.h"
//      #include "private/funcBindP.h"
//      
//      ...
//      
//      STATUS bdmExcLibInit (void)
//          {
//          if (bdmIsInitialized)
//              return (ERROR);
//      
//          if (_func_excBaseHook != NULL)
//              return (ERROR);
//      
//          /* install exception notification hook */
//          _func_excBaseHook = bdmExcHook;
//          bdmIsInitialized  = TRUE;
//      
//          return (OK);
//          }
//
//  The exception notification hook, bdmExcHook()
//  should capture information about the exception and
//  notify the target server of the exception by 
//  executing the 'bgnd' instruction:
//
//      LOCAL int bdmExcHook
//          (
//          int vec,
//          char *pESF,
//          WDB_IU_REGS *pRegs
//          )
//          {
//
//          /* store exception information */
//          ...
//
//          /* put target in background mode */
//          /* by executing the 'bgnd' instruction */
//      
//          __asm__ (".word 0x4afa");
//      
//          return (FALSE);        /* FALSE means we did not handle exception */
//          }
//      
//  The exception notification hook must return FALSE so that
//  vxWorks's exception handler will continue handling the
//  exception.  Typically, the hook will store exception
//  information, like the pointer to the exception stack
//  frame (ESF) in a global data structure so that the back end
//  can read this data structure to determine the pointer to the
//  ESF.  The exception notification code must be linked into
//  vxWorks, and initialized.  Initialization is usually 
//  performed in usrInit(), after the vxWorks exception handlers are 
//  installed by calling excVecInit(). 
//
//  An important part of managing exception information is to
//  correctly report register values.  Once an exception has
//  occurred, CrossWind will requests target register values.
//  The values returned should not be the current CPU register
//  values, but instead the values when the exception occurred.
//  These "exception" register values may be obtained from the
//  exception handling hook, bdmExcHook ():  vxWorks provides
//  a pointer to the register information in the third parameter 
//  which is passed to bdmExcHook ().


////////////////////////////////////////////////////////////////////////////////
//  Mandatory Helper Functions
//
//  The vendor-specific back end class implements three mandatory
//  helper functions, fdGet_m(), halt_m(), and unhalt_m().
//  fdGet_m(), described above, returns the event file descriptor,
//  which is used for asynchronous event notification.  halt_m()
//  is used to stop the emulator, so that generic back end operations,
//  like gopher or checksum, can be performed.  unhalt_m() returns
//  the system to the state it was in before halt_m() was called.
//  For the present case of a CPU32 microprocessor, halt_m() puts 
//  the system in background debug mode, and unhalt_m() returns the
//  system to its previous state.


/* includes */

#include "rw/queuecol.h"


/* 
 * Toggle ERROR definition to accomodate MicroSoft's 
 * conflicting definition 
 */

#ifdef WIN32
#ifdef ERROR
#undef ERROR
#endif
#endif


#include "ace/api.h"  // ACE's API header file

/* re-enable WRS's definition of ERROR */

#ifdef  WIN32
#ifdef  ERROR
#undef  ERROR
#endif
#define ERROR     (-1)
#endif


#include "host.h"
#include "tgtlib.h"
#include "windll.h"
#include "wpwrutil.h"
#include "wdb.h"


#include "backend.h"
#include "event.h"

#include "bdmExcLib.h"

/* defines */