VxWorks Reference Manual : Libraries
dbgLib - debugging facilities
dbgHelp( ) - display debugging help menu
dbgInit( ) - initialize the local debugging package
b( ) - set or display breakpoints
e( ) - set or display eventpoints (WindView)
bh( ) - set a hardware breakpoint
bd( ) - delete a breakpoint
bdall( ) - delete all breakpoints
c( ) - continue from a breakpoint
cret( ) - continue until the current subroutine returns
s( ) - single-step a task
so( ) - single-step, but step over a subroutine
l( ) - disassemble and display a specified number of instructions
tt( ) - display a stack trace of a task
This library contains VxWorks's primary interactive debugging routines, which provide the following facilities:
- task breakpoints
- task single-stepping
- symbolic disassembly
- symbolic task stack tracingIn 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.
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.
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.
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( ).
An unbreakable 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.
The l( ) routine provides a symbolic disassembler. The tt( ) routine provides a symbolic stack tracer.
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( ).
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.
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.
dbgLib.h
dbgLib, excLib, tyLib, taskIdDefault( ), taskOptionsSet( ), tyAbortSet( ), tyAbortFuncSet( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
dbgHelp( ) - display debugging help menu
void dbgHelp (void)
This routine displays a summary of dbgLib utilities with a short description of each, similar to the following:
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)
N/A
dbgLib, VxWorks Programmer's Guide: Target Shell
dbgInit( ) - initialize the local debugging package
STATUS dbgInit (void)
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.
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.
OK, always.
dbgLib, VxWorks Programmer's Guide: Target Shell
b( ) - set or display breakpoints
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 */ /* info */ )
This routine sets or displays breakpoints. To display the list of currently active breakpoints, call b( ) without arguments:
-> bThe 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:
-> b addr[,task[,count[,quiet]]]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( ).
OK, or ERROR if addr is illegal or the breakpoint table is full.
dbgLib, bd( ), taskOptionsSet( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
e( ) - set or display eventpoints (WindView)
STATUS e ( INSTR * addr, /* where to set eventpoint, or 0 means display all */ event_t eventId, /* event ID */ int taskNameOrId, /* task affected; 0 means all tasks */ FUNCPTR evtRtn, /* function to be invoked; NULL means no function */ /* invoked */ int arg /* argument to be passed to evtRtn */ )
This routine sets "eventpoints"--that is, breakpoint-like instrumentation markers that can be inserted in code to generate and log an event for use with WindView. Event logging must be enabled with wvEvtLogEnable( ) for the eventpoint to be logged.
eventId selects the evenpoint number that will be logged: it is in the user event ID range (0-25536).
If addr is NULL, then all eventpoints and breakpoints are displayed. If taskNameOrId is 0, then this event is logged in all tasks. The evtRtn routine is called when this eventpoint is hit. If evtRtn returns OK, then the eventpoint is logged; otherwise, it is ignored. If evtRtn is a NULL pointer, then the eventpoint is always logged.
Eventpoints are exactly like breakpoints (which are set with the b( ) command) except in how the system responds when the eventpoint is hit. An eventpoint typically records an event and continues immediately (if evtRtn is supplied, this behavior may be different). Eventpoints cannot be used at interrupt level.
To delete an eventpoint, use bd( ).
OK, or ERROR if addr is odd or nonexistent in memory, or if the breakpoint table is full.
bh( ) - set a hardware breakpoint
STATUS bh ( INSTR * addr, /* where to set breakpoint, or 0 = display all */ int access, /* access type (arch dependant) */ 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 */ /* info */ )
This routine is used to set a hardware breakpoint. If the architecture allows it, this function will add the breakpoint to the list of breakpoints and set the hardware breakpoint register(s). For more information, see the manual entry for b( ).
The types of hardware breakpoints vary with the architectures. Generally, a hardware breakpoint can be a data breakpoint or an instruction breakpoint.
OK, or ERROR if addr is illegal or the hardware breakpoint table is full.
dbgLib, b( ), VxWorks Programmer's Guide: Target Shell
bd( ) - delete a breakpoint
STATUS bd ( INSTR * addr, /* address of breakpoint to delete */ int task /* task for which to delete breakpoint, 0 = delete for all */ )
This routine deletes a specified breakpoint.
To execute, enter:
-> bd addr [,task]If task is omitted or zero, the breakpoint will be removed for all tasks. If the breakpoint applies to all tasks, removing it for only a single task will be ineffective. It must be removed for all tasks and then set for just those tasks desired. Temporary breakpoints inserted by the routines so( ) or cret( ) can also be deleted.
OK, or ERROR if there is no breakpoint at the specified address.
dbgLib, b( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
bdall( ) - delete all breakpoints
STATUS bdall ( int task /* task for which to delete breakpoints, 0 = delete for all */ )
This routine removes all breakpoints.
To execute, enter:
-> bdall [task]If task is specified, all breakpoints that apply to that task are removed. If task is omitted, all breakpoints for all tasks are removed. Temporary breakpoints inserted by so( ) or cret( ) are not deleted; use bd( ) instead.
OK, always.
dbgLib, bd( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
c( ) - continue from a breakpoint
STATUS c ( int task, /* task that should proceed from breakpoint */ INSTR * addr, /* address to continue at; 0 = next instruction */ INSTR * addr1 /* address for npc; 0 = instruction next to pc */ )
This routine continues the execution of a task that has stopped at a breakpoint.
To execute, enter:
-> c [task [,addr[,addr1]]]If task is omitted or zero, the last task referenced is assumed. If addr is non-zero, the program counter is changed to addr; if addr1 is non-zero, the next program counter is changed to addr1, and the task is continued.
When a task is continued, c( ) does not distinguish between a suspended task or a task suspended by the debugger. Therefore, its use should be restricted to only those tasks being debugged.
The next program counter, addr1, is currently supported only by SPARC.
OK, or ERROR if the specified task does not exist.
dbgLib, tr( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
cret( ) - continue until the current subroutine returns
STATUS cret ( int task /* task to continue, 0 = default */ )
This routine places a breakpoint at the return address of the current subroutine of a specified task, then continues execution of that task.
To execute, enter:
-> cret [task]If task is omitted or zero, the last task referenced is assumed.When the breakpoint is hit, information about the task will be printed in the same format as in single-stepping. The breakpoint is automatically removed when hit, or if the task hits another breakpoint first.
OK, or ERROR if there is no such task or the breakpoint table is full.
dbgLib, so( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
s( ) - single-step a task
STATUS s ( int taskNameOrId, /* task to step; 0 = use default */ INSTR * addr, /* address to step to; 0 = next instruction */ INSTR * addr1 /* address for npc, 0 = next instruction */ )
This routine single-steps a task that is stopped at a breakpoint.
To execute, enter:
-> s [task[,addr[,addr1]]]If task is omitted or zero, the last task referenced is assumed. If addr is non-zero, then the program counter is changed to addr; if addr1 is non-zero, the next program counter is changed to addr1, and the task is stepped.
When a task is continued, s( ) does not distinguish between a suspended task or a task suspended by the debugger. Therefore, its use should be restricted to only those tasks being debugged.
The next program counter, addr1, is currently supported only by SPARC.
OK, or ERROR if the debugging package is not installed, the task cannot be found, or the task is not suspended.
dbgLib, VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
so( ) - single-step, but step over a subroutine
STATUS so ( int task /* task to step; 0 = use default */ )
This routine single-steps a task that is stopped at a breakpoint. However, if the next instruction is a JSR or BSR, so( ) breaks at the instruction following the subroutine call instead.
To execute, enter:
-> so [task]If task is omitted or zero, the last task referenced is assumed.
dbgLib, VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
l( ) - disassemble and display a specified number of instructions
void l ( INSTR * addr, /* address of first instruction to disassemble if 0, */ /* from the last instruction disassembled on the */ /* call to l */ int count /* number of instruction to disassemble if 0, use the same */ /* the last call to l */ )
This routine disassembles a specified number of instructions and displays them on standard output. If the address of an instruction is entered in the system symbol table, the symbol will be displayed as a label for that instruction. Also, addresses in the opcode field of instructions will be displayed symbolically.
To execute, enter:
-> l [address [,count]]If address is omitted or zero, disassembly continues from the previous address. If count is omitted or zero, the last specified count is used (initially 10). As with all values entered via the shell, the address may be typed symbolically.
N/A
dbgLib, VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
tt( ) - display a stack trace of a task
STATUS tt ( int taskNameOrId /* task name or task ID */ )
This routine displays a list of the nested routine calls that the specified task is in. Each routine call and its parameters are shown.
If taskNameOrId is not specified or zero, the last task referenced is assumed. The tt( ) routine can only trace the stack of a task other than itself. For instance, when tt( ) is called from the shell, it cannot trace the shell's stack.
-> tt "logTask" 3ab92 _vxTaskEntry +10 : _logTask (0, 0, 0, 0, 0, 0, 0, 0, 0, 0) ee6e _logTask +12 : _read (5, 3f8a10, 20) d460 _read +10 : _iosRead (5, 3f8a10, 20) e234 _iosRead +9c : _pipeRead (3fce1c, 3f8a10, 20) 23978 _pipeRead +24 : _semTake (3f8b78) value = 0 = 0x0This indicates that logTask( ) is currently in semTake( ) (with one parameter) and was called by pipeRead( ) (with three parameters), which was called by iosRead( ) (with three parameters), and so on.
In order to do the trace, some assumptions are made. In general, the trace will work for all C language routines and for assembly language routines that start with a LINK instruction. Some C compilers require specific flags to generate the LINK first. Most VxWorks assembly language routines include LINK instructions for this reason. The trace facility may produce inaccurate results or fail completely if the routine is written in a language other than C, the routine's entry point is non-standard, or the task's stack is corrupted. Also, all parameters are assumed to be 32-bit quantities, so structures passed as parameters will be displayed as long integers.
OK, or ERROR if the task does not exist.
dbgLib, VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell