Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Alpha System Analysis Tools Manual


Previous Contents Index

Part 3
OpenVMS Watchpoint Utility

Part 3 describes the Watchpoint utility. It presents how to use the Watchpoint utility by doing the following:


Chapter 9
The Watchpoint Utility

This chapter describes the Watchpoint utility, which enables monitoring of write access to user-specified locations. The chapter contains the following sections:

Section 9.1 presents an introduction of the Watchpoint facility.

Section 9.2 describes how to load the watchpoint driver.

Section 9.3 describes the creation and deletion of watchpoints and the constraints upon watchpoint locations.

Section 9.4 contains detailed descriptions of the watchpoint driver data structures, knowledge of which may be required to analyze collected watchpoint data.

Section 9.5 discusses acquiring collected watchpoint data.

Section 9.6 describes the watchpoint protection facility.

Section 9.7 describes its restrictions.

9.1 Introduction

A watchpoint is a data field to which write access is monitored. The field is from 1 to 8 bytes long and must be contained within a single page. Typically, watchpoints are in a nonpaged pool. However, subject to certain constraints (see Section 9.3.1), they can be defined in other areas of system space. The Watchpoint facility can simultaneously monitor a large number (50 or more) watchpoints.

The facility is implemented in the WPDRIVER device driver and the utility program WP. This document concentrates on the device driver, which can be invoked directly or through the WP utility.

For information on the WP utility, see its help files, which can be displayed with the following DCL command:


           $ HELP/LIBRARY=SYS$HELP:WP 

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:

A user defines 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 information recorded about writes to a watchpoint is stored in WPDRIVER data structures. It can be obtained 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.

Note

1 For simplicity, this chapter only mentions XDELTA. Any reference to XDELTA breakpoints also implies system code debugger breakpoints.

9.2 Initializing the Watchpoint Facility

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 pseudodevice 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 facility.

9.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 follow.

9.3.1 Using the $QIO Interface

An image first assigns a channel to pseudodevice 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 9-1 shows the functions that the driver supports.

Table 9-1 Driver Supported Functions
Function Activity
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:

There are a number of 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 9.7 for further details.

To specify that an XDELTA breakpoint or a fatal bugcheck occur if the watchpoint is written, use the following I/O function code modifiers:

For an XDELTA breakpoint to be taken, OpenVMS must have been booted specifying that XDELTA and/or the system code debugger 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 9-2 shows the status codes that can be returned in the I/O status block.

Table 9-2 Returned Status Codes
Status Code Meaning
SS$_NORMAL Success.
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 
                   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 9-3 shows the status values that are returned in the I/O status block.

Table 9-3 Returned Status Values
Status Value Meaning
SS$_NORMAL Success.
SS$_IVADDR The specified watchpoint does not exist.

Section 9.5 describes the use of the IO$_RDSTATS QIO request.

9.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 

and


                 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: R2 - Starting address of the watchpoint area

Status is returned in R0. The status values and their interpretations are identical to those for the QIO interface.

9.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.

9.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 SYSGEN 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:

9.4.2 Watchpoint Control Block (WPCB)

The WPCBs associated with a given system page are singly-linked to a list header in the associated WPRE. A WPCB is allocated from a nonpaged pool when a watchpoint is created. A WPCB contains static information about the watchpoint such as:

In addition, the WPCB contains dynamic data associated with the most recent write reference to the watchpoint. This data includes:

9.4.3 Trace Table Entry (WPTTE)

Whenever a watchpoint is written, all the relevant data is recorded in the WPCB associated with the watchpoint. In addition, to maintain a history, the WPDRIVER copies a subset of the data to the oldest WPTTE in the circular trace buffer. Thus, the circular trace buffer contains a history of the last N references to watchpoints. The driver allocates nonpaged pool to accommodate the number of trace table entries specified by the SYSGEN parameter WPTTE_SIZE. The WPTTEs for all watchpoints are together in the table, but the ones for a particular watchpoint are chained together.

The subset of data in a WPTTE includes:

9.5 Analyzing Watchpoint Results

Analyzing watchpoint results is a function of the mode in which the WPDRIVER is used. For example, if you have only one watchpoint and have specified that an XDELTA breakpoint and/or a bugcheck occur on a write to the watchpoint, then when the reference occurs, simply find the program counter (PC) that caused the reference.

This PC (actually the PC of the next instruction) and its processor status longword (PSL) are on the stack at the time of the breakpoint and/or bugcheck. The layout that follows is the stack as it appears within an XDELTA breakpoint. Examined from a crash dump, the stack is similar but does not contain the return address from the JSB to INI$BRK.


                       +--------------------------------------+ 
                       |address in WPDRIVER from JSB G^INI$BRK| :SP 
                       |PC of next instruction                | 
                       |PSL at watchpoint access              | 
                       +--------------------------------------+ 

Furthermore, R0 contains the address of the WPCB associated with that watchpoint. You can examine the WPCB to determine the original contents of the watchpoint area and the registers at the time of the write.

Definitions for the watchpoint data structures are in SYS$LIBRARY:LIB.MLB. Build an object module with their symbol definitions by entering the following DCL commands:


$MACRO/OBJ=SYS$LOGIN:WPDEFS SYS$INPUT: + SYS$LIBRARY:LIB/LIB
$WPCBDEF   GLOBAL   !n.b. GLOBAL must be capitalized
$WPREDEF    GLOBAL
$WPTTEDEF   GLOBAL 
                     .end 
                CTRL/Z

Then, within SDA, you can format watchpoint data structures. For example, enter the following SDA commands:


SDA>READ SYS$LOGIN:WPDEFS.OBJ
SDA>FORMAT @R0 /TYPE=WPCB   !type definition is required
SDA>DEF WPTTE = @R0 + WPCB$L_TTE
SDA>FORMAT WPTTE /TYPE=WPTTE

An alternative to crashing the system or using XDELTA to get watchpoint information is the QIO function IO$_RDSTAT. This function returns watchpoint control block contents and trace table entries for a particular watchpoint.

It requires the following device/function dependent arguments:

The data returned in the buffer has the format shown in Figure 9-1.

Figure 9-1 Format of Data Returned in Buffer



                   +---------------------------------------------+ 
                   |     Number of bytes copied to buffer        | 
                   +---------------------------------------------+ 
                   |     Total number of WPTTEs for watchpoint   | 
                   +---------------------------------------------+ 
                   |     Number of WPTTEs copied to buffer       | 
                   +---------------------------------------------+ 
                   |     WPCB                                    | 
                   +---------------------------------------------+ 
                   |     Most recent WPTTE                       | 
                   +---------------------------------------------+ 
                   |     Next recent WPTTE                       | 
                   +---------------------------------------------+ 
                   |     Next WPTTE                              | 
                   +---------------------------------------------+ 
                   ~     Next WPTTE                              ~ 
                   +---------------------------------------------+ 


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6549PRO_030.HTML