dbglib.c

VXWORKS源代码

/* dbgLib.c - debugging facilities */

/* Copyright 1984-2001 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01y,26mar02,pai  Added code to display Streaming SIMD Registers (SPR 74103).
01x,09nov01,jhw  Revert WDB_INFO to be inside of WIND_TCB.
01w,05nov01,jn   use symFindSymbol for symbol lookup (SPR #7453)
01v,17oct01,jhw  Access WDB_INFO from WIND_TCB pointer pWdbInfo.
01u,03apr01,kab  Added _WRS_ALTIVEC_SUPPORT
01t,14mar01,pcs  Added code to display ALTIVEC Registers.
01s,08nov00,zl   added dsp show routine call.
01r,03mar00,zl   merged SH support from T1
01q,15mar99,elg  change documentation of tt() (SPR 20892).
01p,14mar99,jdi  doc: removed refs to config.h and/or configAll.h (SPR 25663).
01o,18jan99,elg  Authorize breakpoints in branch delay slot (SPR 24356).
01n,31aug98,ms   dbgTlSnglStep only conditionally prints fpp regs (SPR 9198).
01m,23apr98,dbt  code cleanup
01l,16mar98,dbt  documentation and code cleanup.
01k,19nov97,dbt  modified to merge with WDB debugger
10a,14jul97,dgp  doc: add windsh x-ref to cret() & so(), change ^C to CTRL-C
09z,21feb97,tam  moved _dbgDsmInstRtn declaration to funcBind.c
09z,28nov96,cdp  added ARM support (make things line up in dbgPrintCall).
09y,23jan96,tpr  turned off the Trace capability for the PPC403ga.
09x,06oct95,jdi  changed Debugging .pG's to .tG "Shell".
09w,31aug95,jdi  doc tweak to b(); changed <passcount> to <count> -- SPR 4603.
09v,20mar95,jdi  doc tweak to l().
09u,01feb95,jdi  added special synopsis to bh() for i386/i486.
09u,01feb95,rhp  doc: simplify integration with standard VxWorks docn by
                 limiting impact of eventpoints to EVENTPOINTS para and 
                 e() routine; also propagate recent doc changes to 
                 standard bh() man page.
...deleted pre 95 history
*/

/*
DESCRIPTION
This library contains VxWorks's primary interactive debugging routines, which 
provide the following facilities:

    - task breakpoints
    - task single-stepping
    - symbolic disassembly
    - symbolic task stack tracing

In addition, dbgLib provides the facilities necessary for enhanced use
of other VxWorks functions, including:

    - enhanced shell abort and exception handling (via tyLib and excLib)

The facilities of excLib are used by dbgLib to support breakpoints,
single-stepping, and additional exception handling functions.

INITIALIZATION
The debugging facilities provided by this module are optional.  In the
standard VxWorks development configuration as distributed, the debugging
package is included.  The configuration macro is INCLUDE_DEBUG.
When defined, it enables the call to dbgInit() in the task usrRoot()
in usrConfig.c.  The dbgInit() routine initializes dbgLib and must be made
before any other routines in the module are called.

BREAKPOINTS
Use the routine b() or bh() to set breakpoints.  Breakpoints can be set to 
be hit by a specific task or all tasks.  Multiple breakpoints for different 
tasks can be set at the same address.  Clear breakpoints with bd() and bdall().

When a task hits a breakpoint, the task is suspended and a message is
displayed on the console.  At this point, the task can be examined,
traced, deleted, its variables changed, etc.  If you examine the task at
this point (using the i() routine), you will see that it is in a suspended
state.  The instruction at the breakpoint address has not yet been executed.

To continue executing the task, use the c() routine.  The breakpoint
remains until it is explicitly removed.

EVENTPOINTS (WINDVIEW)
When WindView is installed, dbgLib supports eventpoints.  Use the routine
e() to set eventpoints.  Eventpoints can be set to be hit by a specific
task or all tasks.  Multiple eventpoints for different tasks can be set at
the same address.

When a task hits an eventpoint, an event is logged and is displayed by
VxWorks kernel instrumentation.

You can manage eventpoints with the same facilities that manage
breakpoints:  for example, unbreakable tasks (discussed below) ignore
eventpoints, and the b() command (without arguments) displays
eventpoints as well as breakpoints.  As with breakpoints, you can clear
eventpoints with bd() and bdall().

UNBREAKABLE TASKS
An \f2unbreakable\fP task ignores all breakpoints.  Tasks can be spawned
unbreakable by specifying the task option VX_UNBREAKABLE.  Tasks can
subsequently be set unbreakable or breakable by resetting VX_UNBREAKABLE
with taskOptionsSet().  Several VxWorks tasks are spawned unbreakable,
such as the shell, the exception support task excTask(), and several
network-related tasks.

DISASSEMBLER AND STACK TRACER
The l() routine provides a symbolic disassembler.  The tt() routine
provides a symbolic stack tracer.

SHELL ABORT AND EXCEPTION HANDLING
This package includes enhanced support for the shell in a debugging
environment.  The terminal abort function, which restarts the shell, is
invoked with the abort key if the OPT_ABORT option has been set.  By
default, the abort key is CTRL-C.  For more information, see the manual
entries for tyAbortSet() and tyAbortFuncSet().

THE DEFAULT TASK AND TASK REFERENCING
Many routines in this module take an optional task name or ID as an
argument.  If this argument is omitted or zero, the "current" task is
used.  The current task (or "default" task) is the last task referenced.
The dbgLib library uses taskIdDefault() to set and get the last-referenced
task ID, as do many other VxWorks routines.

All VxWorks shell expressions can reference a task by either ID or name.
The shell attempts to resolve a task argument to a task ID; if no match is
found in the system symbol table, it searches for the argument in the list
of active tasks.  When it finds a match, it substitutes the task name with
its matching task ID.  In symbol lookup, symbol names take precedence over
task names.

INTERNAL
Architecture:
The VxWorks native debugger is structured to be portable across different
architectures. Six files make up the debugger:  dbgLib.c, dbgTaskLib.c,
wdbDbgLib.c, dbgArchLib.c, wdbDbgALib.s and wdbDbgArchLib.c. The three
first files contain the architecture-independent functions, the others
contains the architecture-dependent support functions.

CAVEAT
When a task is continued, c() and s() routines do not yet distinguish
between a suspended task or a task suspended by the debugger.  Therefore, 
use of these routines should be restricted to only those tasks being
debugged.

INCLUDE FILES: dbgLib.h

SEE ALSO
excLib, tyLib, taskIdDefault(), taskOptionsSet(), tyAbortSet(),
tyAbortFuncSet(),
.pG "Target Shell,"
windsh,
.tG "Shell"
*/

/* LINTLIBRARY */

#include "vxWorks.h"

#include "iv.h"
#include "esf.h"
#include "intLib.h"
#include "ioLib.h"
#include "memLib.h"
#include "dbgLib.h"
#include "dsmLib.h"
#include "regs.h"
#include "shellLib.h"
#include "stdio.h"
#include "stdlib.h"
#include "string.h"
#include "trcLib.h"
#include "tyLib.h"
#include "usrLib.h"
#include "vxLib.h"
#include "private/cplusLibP.h"
#include "private/windLibP.h"
#include "private/taskLibP.h"
#include "private/funcBindP.h"
#include "private/dbgLibP.h"
#include "wdb/wdbDbgLib.h"

/* defines */

#define DBG_INFO(p)      (&(((WIND_TCB *)(p))->wdbInfo))

#define DBG_DEMANGLE_PRINT_LEN 256  /* Num chars of demangled names to print */

/* error messages */

#define DBG_TASK_NOT_FOUND	"Task not found\n"
#define DBG_ILL_BKPT_ADDR	"Illegal Breakpoint Address: 0x%08x\n"
#define DBG_BKPT_TBL_FULL	"Breakpoint table is full\n"
#define DBG_ILL_EVTPT_ADDR	"Illegal Eventpoint Address: 0x%08x\n"
#define DBG_EVTPT_TBL_FULL	"Eventpoint table is full\n"
#define DBG_HW_BKPT_REGS_FULL	"Cannot set hardware breakpoint. All hardware breakpoint registers are in use\n"
#define DBG_INV_HW_BKPT_TYPE	"Invalid hardware breakpoint type\n"
#define DBG_NO_BKPT_AT_ADDR	"No breakpoint at 0x%08x"
#define DBG_TASK_IX_NOT_FOUND	"Task %#x not found\n"
#define DBG_CRET_NOT_SUPP	"cret not supported\n"
#define DBG_NO_BKPTS		"No breakpoints\n"

/* typedefs */

typedef struct                  /* EVT_CALL_ARGS */
    {
    FUNCPTR	evtRtn;		/* event routine */
    int 	evtRtnArg;	/* event routine argument */
    event_t	eventId;	/* event ID */
    } EVT_CALL_ARGS;

/* globals */

BOOL		dbgPrintFpp;
BOOL		dbgPrintDsp;
#ifdef _WRS_ALTIVEC_SUPPORT
BOOL            dbgPrintAltivec;
#endif /* _WRS_ALTIVEC_SUPPORT */
BOOL            dbgPrintSimd;

/* extern */

IMPORT FUNCPTR	_func_breakpoint;
IMPORT FUNCPTR	_func_trace;
IMPORT FUNCPTR	_func_trap;
IMPORT FUNCPTR	_func_dbgTargetNotify;
IMPORT BOOL	dbgUnbreakableOld;

/* locals */

static INSTR *	nextToDsm	= NULL;	/* instruction to disassemble from */
static int	dfltCount	= 10;	/* # of instructions to disassemble */

/* forward declarations */

LOCAL void 	dbgTargetNotify (UINT32 flag, UINT32 addr, 
				    REG_SET * pRegisters);
LOCAL BRKPT *	dbgBrkAdd (INSTR * addr, int task, unsigned flags, 
				    unsigned action, unsigned count, 
				    FUNCPTR callRtn, int callArg);
LOCAL STATUS	dbgCheckBreakable (int task);
LOCAL void	dbgTlSnglStep (int task);
LOCAL STATUS	dbgInstall (void);
LOCAL void	dbgTyAbort (void);
LOCAL void	dbgTlTyAbort (void);
LOCAL void 	dbgBrkDisplay (void);
LOCAL void	dbgPrintAdrs (int address);
LOCAL INSTR * 	dbgList (INSTR * addr, int count);
LOCAL void 	dbgBrkPrint (INSTR * addr);
LOCAL void	dbgE (EVT_CALL_ARGS * pEvtCall, REG_SET * pRegisters);

/*******************************************************************************
*
* dbgHelp - display debugging help menu
*
* This routine displays a summary of dbgLib utilities with a
* short description of each, similar to the following:
*
* .CS
*     dbgHelp                         Print this list
*     dbgInit                         Install debug facilities
*     b                               Display breakpoints
*     b         addr[,task[,count]]   Set breakpoint
*     e         addr[,eventNo[,task[,func[,arg]]]]] Set eventpoint (WindView)
*     bd        addr[,task]           Delete breakpoint
*     bdall     [task]                Delete all breakpoints
*     c         [task[,addr[,addr1]]] Continue from breakpoint
*     cret      [task]                Continue to subroutine return
*     s         [task[,addr[,addr1]]] Single step
*     so        [task]                Single step/step over subroutine
*     l         [adr[,nInst]]         List disassembled memory
*     tt        [task]                Do stack trace on task
*     bh        addr[,access[,task[,count[,quiet]]]] set hardware breakpoint
*                                     (if supported by the architecture)
* .CE
*
* RETURNS: N/A
*
* SEE ALSO:
* .pG "Target Shell"
*/

void dbgHelp (void)
    {
    static char * help_msg  = "\n\
dbgHelp                         Print this list\n\
dbgInit                         Install debug facilities\n\
b                               Display breakpoints and eventpoints\n\
b         addr[,task[,count]]   Set breakpoint\n\
e         addr[,eventNo[,task[,func[,arg]]]]] Set eventpoint\n\
bd        addr[,task]           Delete breakpoint\n\
bdall     [task]                Delete all breakpoints and eventpoints\n\
c         [task[,addr[,addr1]]] Continue from breakpoint\n\
cret      [task]                Continue to subroutine return\n\
s         [task[,addr[,addr1]]] Single step\n\
so        [task]                Single step/step over subroutine\n\
l         [adr[,nInst]]         List disassembled memory\n\
tt        [task]                Do stack trace on task\n";

    printf ("%s", help_msg);

    printf ("%s", _archHelp_msg);
    }

/*******************************************************************************
*
* dbgInit - initialize the local debugging package
*
* This routine initializes the local debugging package and enables the basic
* breakpoint and single-step functions.
*
* This routine also enables the shell abort function, CTRL-C.
*
* NOTE
* The debugging package should be initialized before any debugging routines
* are used.  If the configuration macro INCLUDE_DEBUG is defined, dbgInit()
* is called by the root task, usrRoot(), in usrConfig.c.
*
* RETURNS: OK, always.
*
* SEE ALSO:
* .pG "Target Shell"
*/

STATUS dbgInit (void)
    {
    _dbgArchInit ();	/* initialise disassembler ... */

    tyAbortFuncSet ((FUNCPTR) dbgTyAbort);	/* set abort routine */

    _func_bdall = bdall;

    return (OK);
    }

/*******************************************************************************
*
* dbgInstall - install the debugging facility
*
* This routine installs the debug package.
* It performs the following actions:
*
*   - Initialize breakpoint entry lists
*
*   - Sets the interrupt vectors of the breakpoint
*     and trace hardware interrupts to the appropriate
*     debug interrupt handlers.
*
*   - Adds the debug task switch routine to the kernel
*     context switch call out.
*
* This routine is called automatically by all breakpoint related routines
* in this library.  Note that dbgInstall should not be called until
* the following items have been initialized:
*
*   - the pipe driver
*   - the ty driver used for logging
*   - the exception handler library (excLib)
*   - the message logging library (logLib)
*
* RETURNS: OK, or ERROR if unable to install task switch routine.
*
* NOMANUAL
*/

LOCAL STATUS dbgInstall (void)
    {
    static BOOL dbgInstalled = FALSE;	   /* TRUE = facility installed */

    /* if debugging facility is not already installed, then install it
     * by initializing lists and installing switch hook.
     */

    if (!dbgInstalled)
	{
	/* initialize breakpoint lists */

	wdbDbgBpListInit ();

	/* connect various handlers */

	dbgTaskBpHooksInstall ();

	/* routine to be called when a breakpoint is encountered */

	_func_dbgTargetNotify = (FUNCPTR) dbgTargetNotify;

#if DBG_NO_SINGLE_STEP
	/* 
	 * If _func_trap was not already initialized by the WDB agent, 
	 * initialize it.
	 */

	if (_func_trap == NULL)
	    _func_trap = (FUNCPTR) dbgTaskBpTrap;
#else	/* DBG_NO_SINGLE_STEP */ 
	/*
	 * If _func_trace was not already initialized by the WDB agent,
	 * initialize it.
	 */

	if (_func_trace == NULL)
	    _func_trace = (FUNCPTR) dbgTaskBpTrace;

	/* 
	 * if _func_breakpoint was not already initialized by the WDB agent, 
	 * initialize it. 
	 */

	if (_func_breakpoint == NULL)
	    _func_breakpoint = (FUNCPTR) dbgTaskBpBreakpoint;
#endif	/* DBG_NO_SINGLE_STEP */

	/* Insert the break and trace vectors, set breakpoint instruction */

	wdbDbgArchInit ();

	dbgInstalled = TRUE;
	}

    return (OK);
    }

/*******************************************************************************
*
* b - set or display breakpoints
*
* This routine sets or displays breakpoints.  To display the list of
* currently active breakpoints, call b() without arguments:
* .CS
*     -> b
* .CE
* The list shows the address, task, and pass count of each breakpoint.
* Temporary breakpoints inserted by so() and cret() are also indicated.
*
* To set a breakpoint with b(), include the address, which can be
* specified numerically or symbolically with an optional offset.
* The other arguments are optional:
* .CS
*     -> b addr[,task[,count[,quiet]]]
* .CE
* If <task> is zero or omitted, the breakpoint will apply to all breakable
* tasks.  If <count> is zero or omitted, the breakpoint will occur every
* time it is hit.  If <count> is specified, the break will not occur
* until the <count> +1th time an eligible task hits the breakpoint
* (i.e., the breakpoint is ignored the first <count> times it is hit).
*
* If <quiet> is specified, debugging information destined for the console
* will be suppressed when the breakpoint is hit.  This option is included
* for use by external source code debuggers that handle the breakpoint
* user interface themselves.
*
* Individual tasks can be unbreakable, in which case breakpoints that
* otherwise would apply to a task are ignored.  Tasks can be spawned
* unbreakable by specifying the task option VX_UNBREAKABLE.
* Tasks can also be set unbreakable or breakable by resetting
* VX_UNBREAKABLE with the routine taskOptionsSet().
*
* RETURNS
* OK, or ERROR if <addr> is illegal or the breakpoint table is full.
*
* SEE ALSO: bd(), taskOptionsSet(),
* .pG "Target Shell,"
* windsh,
* .tG "Shell"
*/

STATUS b
    (
    INSTR *	addr,		/* where to set breakpoint, or	 */
				/* 0 = display all breakpoints	 */
    int	 	task,		/* task for which to set breakboint,   */
				/* 0 = set all tasks		   */
    int		count,		/* number of passes before hit	 */
    BOOL	quiet		/* TRUE = don't print debugging info,  */
				/* FALSE = print debugging info	*/
    )
    {
    int		tid = 0;	/* task ID */
    int		val;		/* temporary buffer */
    int		action;		/* breakpoint action */
    int 	retVal = OK;	/* return value */

    if (dbgInstall () != OK)
	return (ERROR);

    if (task != 0)
	tid = taskIdFigure (task);	/* convert to task id */

    if (tid == ERROR)
	{
	printErr (DBG_TASK_NOT_FOUND);
	return (ERROR);
	}

    /* NULL address means show all breakpoints */

    if (addr == NULL) 
	{
	dbgBrkDisplay ();
	return (OK);
	}

    /* if text segment protection turned on, first write enable the page */

    TEXT_UNLOCK(addr);

    /* check validity of breakpoint address */

    if (!ALIGNED ((int) addr, DBG_INST_ALIGN) ||
	(vxMemProbe ((char *)addr, VX_READ,
				sizeof(INSTR), (char *)&val) != OK) ||
	(vxMemProbe ((char *)addr, VX_WRITE,
				sizeof(INSTR), (char *)&val) != OK))
	{
	printErr (DBG_ILL_BKPT_ADDR, (int)addr);
	retVal = ERROR;
	goto done;
	}

    if (quiet)
	action = WDB_ACTION_STOP;