Document revision date: 16 July 2002

To start SDD on the build system, enter the following command.

$ DEBUG/KEEP

SDD displays the DBG> prompt. With the DBGHK$IMAGE_PATH logical name defined, you can invoke the ANALYZE/CRASH_DUMP command and optional qualifier /IMAGE_PATH.

To use the ANALYZE/CRASH_DUMP command and optional qualifier (/IMAGE_PATH) to analyze the dump in file <file-name> enter the following command:

DBG> ANALYZE/CRASH_DUMP file-name

The /IMAGE_PATH qualifier is optional. If you do not use this qualifier, SDD uses the DBGHK$IMAGE_PATH logical name as the default. The /IMAGE_PATH qualifier is a quick way to change the logical name. However, when you use it, you cannot specify a search list. You can use only a logical name or a device and directory, although the logical name can be a search list.

Usually, SDD obtains the source file name from the object file. This is put there by the compiler when the source is compiled with the /DEBUG qualifier. The SET SOURCE command can take a list of paths as a parameter. It treats them as a search list.

10.6 Summary of System Dump Debugger Commands

Only a subset of OpenVMS debugger commands can be used in SDD. The following are a few examples of commands that you can use in SDD:

• Commands to manipulate the source display, such as TYPE and SCROLL
• Commands used in OpenVMS debugger command programs, such as DO and IF
• Commands that affect output formats, such as SET RADIX
• Commands that manipulate symbols and scope, such as EVALUATE, SET LANGUAGE, and CANCEL SCOPE
• Commands that read the contents of memory and registers, such as EXAMINE

Examples of commands that cannot be used in SDD are as follows:

• Commands that cause code to be executed, such as STEP and GO
• Commands that manipulate breakpoints, such as SET BREAK and CANCEL BREAK
• Commands that modify memory or registers, such as DEPOSIT

You can also use the OpenVMS debugger command SDA to examine the system dump with System Dump Analyzer semantics. This command, which is not available when debugging user programs, is described in the next section.

10.7 Using System Dump Analyzer Commands

Once a dump file has been opened, you can use the commands listed in the previous section to examine the system dump. You can also use some System Dump Analyzer (SDA) commands, such as SHOW SUMMARY and SHOW DEVICE. This feature allows the system programmer to take advantage of the strengths of both the OpenVMS Debugger and SDA to examine the system dump and to debug system programs such as device drivers, without having to invoke both the OpenVMS debugger and SDA separately.

To obtain access to SDA commands, you simply type "SDA" at the OpenVMS Debugger prompt ("DBG>") at any time after the dump file has been opened. SDA initializes itself and then outputs the "SDA>" prompt. Enter SDA commands as required. (See Chapter 4 for more information.) To return to the OpenVMS Debugger, you enter "EXIT" at the "SDA>" prompt. Optionally, you may invoke SDA to perform a single command and then return immediately to the OpenVMS Debugger, as in the following example:

DBG> SDA SHOW SUMMARY

SDA may be reentered at any time, with or without the optional SDA command. Once SDA has been initialized, the SDA> prompt is output more quickly on subsequent occasions.

Note that there are some limitations on the use of SDA from within SDD:

• You cannot switch between processes, whether requested explicitly (SET PROCESS <name>) or implicitly (SHOW PROCESS <name>). The exception to this is that access to the system process is possible.
• You cannot switch between CPUs.
• SDA has no knowledge of the OpenVMS debugger's Motif or Windows interfaces. Therefore, all SDA input and output occurs at the terminal or window where the OpenVMS debugger was originally invoked. Also, while using SDA, the OpenVMS debugger window is not refreshed; you must exit SDA to allow the OpenVMS debugger window to be refreshed.
• When you invoke SDA from SDD with an immediate command, and that command produces a full screen of output, SDA displays the message "Press RETURN for more." followed by the "SDA>" prompt before continuing. At this prompt, if you enter another SDA command, SDA does not automatically return to SDD upon completion. To do this, you must enter an EXIT command.

If the need arises to switch between processes or CPUs in the system dump, then you must invoke SDA separately using the DCL command ANALYZE/CRASH_DUMP.

10.8 Limitations of the System Dump Debugger

SDD provides a narrow window into the context of the system that was current at the time that the system crashed (stack, process, CPU, and so on). It does not provide full access to every part of the system as is provided by SDA. However, it does provide a view of the failed system using the semantics of the OpenVMS debugger---source correlation and display, call frame traversal, examination of variables by name, language constructs, and so on.

SDD therefore provides an additional approach to analyzing system dumps that is difficult to realize with SDA, often allowing quicker resolution of system crashes than is possible with SDA alone. When SDD cannot provide the needed data from the system dump, you should use SDA instead.

10.9 Access to Symbols in OpenVMS Executive Images

For a discussion and explanation of how the OpenVMS debugger accesses symbols in OpenVMS executive images, see Section 9.11.

10.10 Sample System Dump Debugging Session

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:

1. Follow the steps in Section 9.12, up to and including Example 8-9 (Breakpoint Display).
2. When the breakpoint at line 146 is reached, enter the OpenVMS debugger command to clear R27 and then continue:

   DBG> DEPOSIT R27=0 DBG> GO

3. The system then crashes and a dump is written.
4. When the system reboots, copy the contents of SYS$SYSTEM:SYSDUMP.DMP to the build system with SDA:

   $ analyze/crash sys$system:sysdump.dmp

   OpenVMS (TM) Alpha system dump analyzer ...analyzing a selective memory dump... %SDA-W-NOTSAVED, global pages not saved in the dump file Dump taken on 1-JAN-1998 00:00:00.00 INVEXCEPTN, Exception while above ASTDEL SDA> copy hstsys::sysdump.dmp SDA>

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.

The example begins by invoking the system dump debugger's character cell interface on the build system.

Example 10-1 Invoking the System Dump Debugger

$ define dbg$decw$display " " $ debug/keep OpenVMS Alpha Debug64 Version V7.2-019 DBG>

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 DBG> prompt is displayed. You should now do the following:

1. Set the language to be C, the language of the module that was active at the time of the system crash.
2. Set the source directory to the location of the source of the module. Use the debugger's SET SOURCE command, which takes a search list as a parameter so you can make it point to many places.

Example 10-2 Accessing the System Dump

DBG> analyze/crash_dump sysdump.dmp %SDA-W-NOTSAVED, global pages not saved in the dump file %DEBUG-I-INIBRK, target system interrupted %DEBUG-I-DYNIMGSET, setting image SYSTEM_DEBUG %DEBUG-I-DYNMODSET, setting module C_TEST_ROUTINES DBG> set language c DBG> set source/latest sys$examples,sys$library DBG>

Now that the debugger has access to the source, you can put the debugger into screen mode to see exactly where you are and the code surrounding it.

Example 10-3 Displaying the Source Code

DBG> Set Mode Screen; Set Step Nosource - SRC: module C_TEST_ROUTINES -scroll-source------------------------------------ 135: int i,k; 136: for(k=0;k<1000;k++) 137: { 138: test_c_code5(&i); 139: } 140: return; 141: } 142: int test_c_code3(int subrtnCount) 143: { 144: subrtnCount = subrtnCount - 1; 145: if (subrtnCount != 0) -> 146: subrtnCount = test_c_code3(subrtnCount); 147: return subrtnCount; 148: } 149: int test_c_code2(int64 in64,int in32, int64 test, int64* pVar) 150: { 151: xdt$fregsav[5] = in64; 152: xdt$fregsav[6] = in32; 153: if (xdt$fregsav[9] > 0) 154: *pVar = (*pVar + xdt$fregsav[17])%xdt$fregsav[9]; 155: else 156: *pVar = (*pVar + xdt$fregsav[17]); 157: xdt$fregsav[7] = test_c_code3(10); - OUT -output------------------------------------------------------------------- - PROMPT -error-program-prompt-------------------------------------------------- DBG>

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

Example 10-4 Using the Examine and Show Calls Commands

DBG> Set Mode Screen; Set Step Nosource - SRC: module C_TEST_ROUTINES -scroll-source------------------------------------ 135: int i,k; 136: for(k=0;k<1000;k++) 137: { 138: test_c_code5(&i); 139: } 140: return; 141: } 142: int test_c_code3(int subrtnCount) 143: { 144: subrtnCount = subrtnCount - 1; 145: if (subrtnCount != 0) -> 146: subrtnCount = test_c_code3(subrtnCount); 147: return subrtnCount; 148: } 149: int test_c_code2(int64 in64,int in32, int64 test, int64* pVar) 150: { 151: xdt$fregsav[5] = in64; 152: xdt$fregsav[6] = in32; 153: if (xdt$fregsav[9] > 0) 154: *pVar = (*pVar + xdt$fregsav[17])%xdt$fregsav[9]; 155: else 156: *pVar = (*pVar + xdt$fregsav[17]); 157: xdt$fregsav[7] = test_c_code3(10); - OUT -output------------------------------------------------------------------- C_TEST_ROUTINES\test_c_code3\subrtnCount: 9 module name routine name line rel PC abs PC *C_TEST_ROUTINES test_c_code3 146 00000000000000CC FFFFFFFF83002D6C *C_TEST_ROUTINES test_c_code2 157 00000000000001A0 FFFFFFFF83002E40 *C_TEST_ROUTINES test_c_code 170 0000000000000260 FFFFFFFF83002F00 *XDELTA XDT$SYSDBG_INIT 9371 0000000000000058 FFFFFFFF83052238 *SYS$DOINIT INI$DOINIT 1488 0000000000000098 FFFFFFFF830520B8 SHARE$EXEC_INIT 0000000000018C74 FFFFFFFF83086C74 SHARE$EXEC_INIT 0000000000014BD0 FFFFFFFF83082BD0 - PROMPT -error-program-prompt-------------------------------------------------- DBG> e subrtnCount DBG> show calls DBG>

• Loading the watchpoint driver
• Creating and deleting watchpoints
• Looking at watchpoint driver data
• Acquiring collected watchpoint data
• Looking at the protection attributes and access fault mechanism
• Looking at some watchpoint restrictions

This chapter describes the Watchpoint utility (WP), which enables you to monitor write access to user-specified locations. The chapter contains the following sections:

Section 11.1 presents an introduction of the Watchpoint utility.

Section 11.2 describes how to load the watchpoint driver.

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

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

Section 11.5 discusses acquiring collected watchpoint data.

Section 11.6 describes the watchpoint protection facility.

Section 11.7 describes its restrictions.

11.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 nonpaged pool. However, subject to certain constraints (see Section 11.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 utility 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:

• An XDELTA breakpoint¹ or SCD breakpoint which occurs just after the write to the watchpoint
• A fatal watchpoint bugcheck which occurs just after the write to the watchpoint

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.

11.2 Initializing the Watchpoint Utility

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:

• Allocating nonpaged pool and physical memory for WPDRIVER data structures
• Appropriating the SCB vector specific to access violations
• Recording in system space the addresses of the WPDRIVER routines invoked by kernel mode code to create and delete watchpoints

Memory requirements for WPDRIVER and its data structures are:

• Device driver and UCB---approximately 3K bytes of nonpaged pool
• Trace table and a related array---36 bytes for each of system parameter WPTTE_SIZE trace table entries
• Watchpoint restore entries---system parameter WPRE_SIZE pages of physically contiguous memory
• Each watchpoint---176 bytes of nonpaged pool

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.

11.3 Creating and Deleting Watchpoints

There are three different ways to create and delete watchpoints:

• An image can assign a channel to device WPA0: and then request the Queue I/O Request ($QIO) system service to create or delete a watchpoint.
• Code running in kernel mode can dispatch directly to routines within the WPDRIVER to create and delete watchpoints.
• You can enter commands to the WP utility.

The first two methods are described in detail in the sections that follow.

11.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 11-1 shows the functions that the driver supports.

Table 11-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:

• P2---Length of the watchpoint. A number larger than 8 is reduced to 8.
• P3---Starting address of the watchpoint area.

The following are the constraints on the watchpoint area. It must be:

• Nonpageable system space.
• Write-accessible from kernel mode.
• Within one page. If it is not, the requested length is reduced to what will fit within the page containing the starting address.
• Within a page accessed only from kernel mode and by instructions that incur no pagefaults.
• Within a page whose protection is not altered while the watchpoint is in place.
• Outside of certain address ranges. These are the WPDRIVER code, its data structures, and the system page table.

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 11.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:

• IO$M_CTRL to request an XDELTA breakpoint
• IO$M_ABORT to request a fatal bugcheck

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 11-2 shows the status codes that can be returned in the I/O status block.

Table 11-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 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 11-3 shows the status values that are returned in the I/O status block.

Table 11-3 Returned Status Values

Status Value	Meaning
SS$_NORMAL	Success.
SS$_IVADDR	The specified watchpoint does not exist.

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

	privacy and legal statement
6549PRO_036.HTML