U. DCB SCB
6.2 THE EXECUTIVE DEBUGGING TOOL
An interactive debugging tool aids in debugging Executive modules, I/O drivers, and interrupt service routines. This debugging aid, called XDT, is a version of RSX-ll ODT. Including XDT in a system with Executive data space support does not reduce the size of pool space that the system can have. XDT occupies physical address space but does not take up any Executive virtual data address space. XDT also does not interfere with user-level RSX-ll ODT, which can be used with any number of tasks while you are debugging your driver with XDT.
You can include XDT in a system during the "Choosing Executive Options" section of system generation when the following question is asked:
Do You Want To Include XDT? [YIN D:N]
DEBUGGING A UfER-SUPPLIED DRIVER
If you answer Y, XDT is linked into the Executive image when you build the Executive.
6.2.1 XDT Commands
XDT commands are generally compatible with RSX-ll ODT commands, which are described in the IASjRSX-ll ODT Reference Manual. That manual, together with the discussion in Section 6.2 in this manual, can be used as a guide to XDT operation on RSX-llM-PLUS.
XDT does not contain the following commands available in ODT:
No $M
-
(Mask) registerNo $X - (En try Flag) registers No $V - (SST vector) registers No $D - (I/O LUN) registers No $E
-
(SST data) registersNo $W - (Directive status word) $DSW word No E
-
(Effective Address Search) command No F-
(Fill Memory) commandNo N
-
(Not word search) command No V-
(Resto re SST vectors) command No W-
(Memory word search) commandIn addi':ion, the X (Exit) ODT command has been changed for XDT. The X command causes a jump to the crash dump routine.
Except:or the omitted features and the change in the X command, XDT is comnand-compatible with RSX-ll ODT; consequently, the IASjRSX-ll ODT Reference Manual can be used as a guide to XDT operation.
XDT includes referencing.
referencing:
both The
Instruction space following commands
and Data control the
I sets address references to Instruction space D sets address references to Data space
space address current address
When XD'J' starts up, the default condition is that address references are to [lata space.
6.2.2 >DT Start Up
When YOL bootstrap a system that includes XDT, the normal system startup transfers control to XDT, which identifies itself at the system console terminal with the following messag~:
XDT: <system name and version>
6-2
DEBUGGING A USER-SUPPLIED DRIVER
If no errors were encountered, the identification message is followed by the prompt:
XDT>
The following are the register conditions when XDT starts:
RO CSR address of the bootstrap device Rl LBN of the system image
R2 LBN of the system image
R3 physical unit number of the load device R4 ASCII name of the load device
R5 total number of blocks read from the system image XDT runs entirely at priority level 7.
You can set breakpoints at this time, and then give a G command, passing control to the Executive initialization module INITL.
Whenever control reaches a breakpoint, a printout similar to that of RSX-ll ODT occurs.
If INITL encounters an error condition, i t prints an error message preceded by a prefix telling whether the condition is a warning or fatal. If the condition is a warning, XDT has control. You can set breakpoints to establish control or type the P command to proceed. If the condition is fatal, the processor halts. You must correct the condition before you can rebootstrap your system.
6.2.3 XDT Restrictions
On some types of systems, the following restrictions exist on the use of XDT when i t is first entered:
1. All systems
Some data structures are not yet initialized. The pool is not set up and the console terminal bootstrapped device are not on-line.
secondary and the
2. Systems with Kernel data space support
Data space mapping is not yet set up. Certain Executive locations that the Task Builder could not resolve are not initialized. (The RH common interrupt table address ($RHTBX) does not contain the RH common interrupt routine address
($RHALT) .)
To proceed when you encounter such restrictions on your system, at the initial XDT prompt you should first set a breakpoint near the end of the INITL module (after the routine that sets up the data structures).
Then, after you proceed and XDT encounters the breakpoint near the end of INITL, use XDT to examine locations in the Executive and to set more Executive breakpoints.
On a multiprocessor system, you should be aware of the following conditions:
1. When you initially place a processor on-line, XDT does prompt from that processor unless you have set processor's bit in the $XDTPR word.
not the
2. XDT does not handle multiprocessor-specific conditions. You cannot set processor-specific breakpoints nor can you easily examine other processors' low memory context.
DEBUGGING A USER-SUPPLIED DRIVER
3. Under certain circumstances (such as when Data space is not yet set up), setting a breakpoint in shared Instruction space may eventually cause a trap on a processor other than the one on which you set the breakpoint. Consequently, because the processor encountering the breakpoint does not have that breakpoint in its XDT tables, XDT generates a breakpoint error message (BE:) rather than a breakpoint message.
4. All processors are locked out of the Executive while XDT is being executed by one of the other processors.
G.2.4 XDT General Operation
A forCEd entry to XDT can be executed at any time from a privileged termincl by means of the MCR Breakpoint (BRK) command. Thus, if your system has no XDT restrictions as described in Section 6.2.3, the normal procedure is to type G when the system is bootstrapped without
settin~ any breakpoints. When it becomes necessary to use XDT, the MeR Breakpoint command is executed, causing a forced breakpoint. XDT then prints on the console terminal:
BE :xxxxxx
This mEssage is followed by the prompt:
XIT>
You car then set breakpoints and issue other XDT commands.
system operation by typing the Proceed (P) command to XDT.
Continue All XD1 command I/O goes to and from the console terminal, and the List MEmory (L) command can list on either the console terminal or the line printer.
6.2.5 XDT and Debugging a User-Supplied Driver
Using IDT to debug a loadable driver has special pitfalls. One problen that can arise is a T-bit error:
TF:xxxxxx X[T>
This error results when control reaches a breakpoint that you have set, Lsing XDT, in a loaded driver. The T-bit error, rather than the expected BE: error, occurs unless register APR5 is mapped to the driver at the time XDT sets the breakpoint.
To avoid this T-bit error, assemble the driver with an embedded BPT instruction, or use either the ZAP utility or the MCR OPEN function to set the breakpoint by replacing a word of code with the BPT instruction. You can use the OPEN command in the following way to access the driver:
>CPE nnnn/DRV=xx:
where nnnn matches the address in the driver map listing and xx is the device mnemonic. (Write down the instruction that you replace with the B P'I ins t r uc t ion. )
6-4
DEBUGGING A USER-SUPPLIED DRIVER
When control reaches a breakpoint set in the driver, XDT prints:
BE:xxxxxx XDT>
Recover as follows:
1. Using XDT, replace the BPT instruction with the desired instruction.
2. Decrement the PC by subtracting 2 from the contents of register R7.
3. Then proceed by using the P or S commands.
NOTE
You should not set breakpoints in more than one module that maps into the Executive through APR 5 or APR 6. In particular, do not set breakpoints in more than one loadable driver at a time or XDT will overwrite words of main memory when i t attempts to restore what i t considers to be the contents of breakpoints.