HP OpenVMS Systems Documentation
OpenVMS Alpha System Analysis Tools Manual
9.9 Access to Symbols in OpenVMS Executive Images
This section provides a sample session that shows the use of some OpenVMS debugger commands as they apply to the system dump debugger. The examples in this section show how to work with a dump created as follows:
To reproduce this sample session, you need access to the SYSTEM_DEBUG.DSF matching the SYSTEM_DEBUG.EXE file on your test system and to the source file C_TEST_ROUTINES.C, which is available in SYS$EXAMPLES.
Use the ANALYZE/CRASH_DUMP command to open the system dump. In this example, the logical name DBGHK$IMAGE_PATH is used for the image path, so the command qualifier /IMAGE_PATH is not being used. You may need to use it.
When you have opened the dump file, the DEBUG prompt is displayed. You should now do the following:
Now, you try a couple of other commands, EXAMINE and SHOW CALLS. The EXAMINE command allows you to look at all the C variables. Note that the C_TEST_ROUTINES module is compiled with the /NOOPTIMIZE switch which allows access to all variables. The SHOW CALLS command shows you the call sequence from the beginning of the stack. In this case, you started out in the image EXEC_INIT. (The debugger prefixes all images other than the main image with SHARE$ so it shows up as SHARE$EXEC_INIT.)
Part 3 describes the Watchpoint utility. It presents how to use the
Watchpoint utility by doing the following:
Once the driver has been loaded, a suitably privileged user can designate a watchpoint in system space. Any write to a location designated as a watchpoint is trapped. Information is recorded about the write, including its time, the register contents, and the program counter (PC) and processor status longword (PSL) of the writing instruction. Optionally, one or both of the following user-specified actions can be taken:
You define a watchpoint by issuing QIO requests to the watchpoint driver; entering commands to the WP utility, which issues requests to the driver; or, from kernel mode code, invoking a routine within the watchpoint driver.
The WPDRIVER data structures store information about writes to a watchpoint. This information can be obtained either through QIO requests to the WPDRIVER, commands to the WP utility, XDELTA commands issued during a requested breakpoint, or SDA commands issued during the analysis of a requested crashdump.
1 For simplicity, this chapter only mentions XDELTA. Any reference to XDELTA breakpoints also implies SCD breakpoints.
From a process with CMKRNL privilege, run the SYSMAN utility to load the watchpoint driver, SYS$WPDRIVER.EXE. Enter the following commands:
$ RUN SYS$SYSTEM:SYSMAN SYSMAN> IO CONNECT WPA0:/NOADAPTER/DRIVER=SYS$WPDRIVER SYSMAN> EXIT
SYSMAN creates system I/O data structures for the pseudo-device WPA0, loads WPDRIVER, and invokes its initialization routines. WPDRIVER initialization includes the following actions:
Memory requirements for WPDRIVER and its data structures are:
It is advisable to load the watchpoint driver relatively soon after
system initialization to ensure its allocation of physically contiguous
memory. If the driver cannot allocate enough physically contiguous
memory, it does not set WPA0: online. If the unit is offline, you will
not be able to use the watchpoint utility.
10.3 Creating and Deleting Watchpoints
There are three different ways to create and delete watchpoints:
The first two methods are described in detail in the sections that
10.3.1 Using the $QIO Interface
An image first assigns a channel to the pseudo-device WPA0: and then issues a $QIO request on that channel. The process must have the privilege PHY_IO; otherwise, the $QIO request is rejected with the error SS$_NOPRIV.
Table 10-1 shows the functions that the driver supports.
|IO$_ACCESS||Creates a watchpoint|
|IO$_DEACCESS||Deletes a watchpoint|
|IO$_RDSTATS||Receives trace information on a watchpoint|
The IO$_ACCESS function requires the following device/function dependent arguments:
The following are the constraints on the watchpoint area. It must be:
Because of the current behavior of the driver, there is an additional requirement that there be no "unexpected" access violations referencing a page containing a watchpoint. See Section 10.7 for further details.
For an XDELTA breakpoint to be taken, OpenVMS must have been booted specifying that XDELTA and/or the SCD be resident (bit 1 or bit 15 in the boot flags must be set). If both watchpoint options are requested, the XDELTA breakpoint is taken first. At exit from the breakpoint, the driver crashes the system.
A request to create a watchpoint can succeed completely, succeed partially, or fail. Table 10-2 shows the status codes that can be returned in the I/O status block.
|SS$_BUFFEROVF||A watchpoint was established, but its length is less than was requested because the requested watchpoint would have straddled a page boundary.|
|SS$_EXQUOTA||The watchpoint could not be created because too many watchpoints already exist.|
|SS$_INSFMEM||The watchpoint could not be created because there was insufficient nonpaged pool to create data structures specific to this watchpoint.|
|SS$_IVADDR||The requested watchpoint resides in one of the areas in which the WPDRIVER is unable to create watchpoints.|
|SS$_WASSET||An existing watchpoint either coincides or overlaps with the requested watchpoint.|
The following example MACRO program assigns a channel to the WPA0 device and creates a watchpoint of 4 bytes, at starting address 80001068. The program requests neither an XDELTA breakpoint nor a system crash for that watchpoint.
$IODEF .PSECT RWDATA,NOEXE,RD,WRT,LONG ; WP_IOSB: .BLKL 2 ; I/O status block. WP_ADDR: .LONG ^X80001068 ; Address of watchpoint to create. WP_NAM: .ASCID /WPA0:/ ; Device to which to assign channel. WP_CHAN: .BLKW 1 ; Channel number. .PSECT PROG,EXE,NOWRT ; START: .CALL_ENTRY $ASSIGN_S DEVNAM=WP_NAM,CHAN=WP_CHAN BLBC R0,RETURN $QIOW_S CHAN=WP_CHAN,- FUNC=#IO$_ACCESS,- IOSB=WP_IOSB,- P2=#4,- P3=WP_ADDR BLBC R0,RETURN MOVL WP_IOSB,R0 ; Move status to R0. RETURN: RET ; Return to caller. .END START
A watchpoint remains in effect until it is explicitly deleted. (Note, however, that watchpoint definitions do not persist across system reboots.) To delete an existing watchpoint, issue an IO$_DEACCESS QIO request.
The IO$_DEACCESS function requires the following device/function dependent argument: P3 - Starting address of the watchpoint to be deleted.
Table 10-3 shows the status values that are returned in the I/O status block.
|SS$_IVADDR||The specified watchpoint does not exist.|
Section 10.5 describes the use of the IO$_RDSTATS QIO request.
10.3.2 Invoking WPDRIVER Entry Points from System Routines
When the WPDRIVER is loaded, it initializes two locations in system space with the addresses of routines within the driver. These locations, WP$CREATE_WATCHPOINT and WP$DELETE_WATCHPOINT, enable dispatch to create and delete watchpoint routines within the loaded driver. Input arguments for both routines are passed in registers.
Code running in kernel mode can execute the following instructions:
JSB @G^WP$CREATE_WATCHPOINT ; create a watchpoint
JSB @G^WP$DELETE_WATCHPOINT ; delete a watchpoint
Both these routines save IPL at entry and set it to the fork IPL of the WPDRIVER, IPL 11. Thus, they should not be invoked by code threads running above IPL 11. At exit, the routines restore the entry IPL.
These two locations contain an RSB instruction prior to the loading of the driver. As a result, if a system routine tries to create or delete a watchpoint before the WPDRIVER is loaded, control immediately returns.
WP$CREATE_WATCHPOINT has the following register arguments:
Status is returned in R0. The status values and their interpretations are identical to those for the QIO interface to create a watchpoint. The only difference is that the SS$_NOPRIV status cannot be returned with this interface.
WPS$DELETE_WATCHPOINT has the following register argument:
Status is returned in R0. The status values and their interpretations
are identical to those for the QIO interface.
10.4 Data Structures
The WPDRIVER uses three different kinds of data structures:
These data structures are described in detail and illustrated in the
sections that follow.
10.4.1 Watchpoint Restore Entry (WPRE)
There is one WPRE for each system page that contains a watchpoint. That is, if nine watchpoints are defined which are in four different system pages, four WPREs are required to describe those pages. When WPDRIVER is loaded, its initialization routine allocates physically contiguous memory for the maximum number of WPREs. The number of pages to be allocated is specified by system parameter WPRE_SIZE.
The WPDRIVER allocates WPREs starting at the beginning of the table and maintains a tightly packed list. That is, when a WPRE in the middle of those in use is "deallocated," its current contents are replaced with the contents of the last WPRE in use. The number in use at any given time is in the driver variable WP$L_WP_COUNT. The system global EXE$GA_WP_WPRE points to the beginning of the WPRE table.
The WPRE for a page contains information useful for: