Document revision date: 30 March 2001

If you want to proceed because you are done debugging this code, first cancel all the breakpoints and then enter the GO command. Notice, however, that you do not keep running but receive a message that you have stepped to line 147. This happens because the STEP command used earlier never completed. It was interrupted by the breakpoint on line 146.

Note that the debugger remembers all step events and only removes them once they have completed.

Example 8-12 Canceling the Breakpoints

- SRC: module C_TEST_ROUTINES -scroll-source------------------------------------ 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); 158: xdt$fregsav[3] = test; - OUT -output------------------------------------------------------------------- break at C_TEST_ROUTINES\test_c_code3\%LINE 146 break at C_TEST_ROUTINES\test_c_code3\%LINE 146 C_TEST_ROUTINES\test_c_code3\subrtnCount: 8 module name routine name line rel PC abs PC *C_TEST_ROUTINES test_c_code3 146 00000000000000C4 FFFFFFFF83002D64 *C_TEST_ROUTINES test_c_code3 146 00000000000000D4 FFFFFFFF83002D74 *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 stepped to C_TEST_ROUTINES\test_c_code3\%LINE 147 - PROMPT -error-program-prompt-------------------------------------------------- DBG> go DBG> Step DBG> examine subrtnCount DBG> show calls DBG> cancel break/all DBG> go DBG>

The STEP/RETURN command, a different type of step command, single steps assembly code until it finds a return instruction. This command is useful if you want to see the return value for the routine, which is done here by examining the R0 register.

For more information about using other STEP command qualifiers, see the OpenVMS Debugger Manual.

Example 8-13 Using the Step/Return Command

- SRC: module C_TEST_ROUTINES -scroll-source------------------------------------ 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); 158: xdt$fregsav[3] = test; 159: return xdt$fregsav[23]; - OUT -output------------------------------------------------------------------- break at C_TEST_ROUTINES\test_c_code3\%LINE 146 break at C_TEST_ROUTINES\test_c_code3\%LINE 146 C_TEST_ROUTINES\test_c_code3\subrtnCount: 8 module name routine name line rel PC abs PC *C_TEST_ROUTINES test_c_code3 146 00000000000000C4 FFFFFFFF83002D64 *C_TEST_ROUTINES test_c_code3 146 00000000000000D4 FFFFFFFF83002D74 *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 stepped to C_TEST_ROUTINES\test_c_code3\%LINE 147 stepped on return from C_TEST_ROUTINES\test_c_code3\%LINE 147 to C_TEST_ROUTINES\test_c_code3\%LINE 148 C_TEST_ROUTINES\test_c_code3\%R0: 0 - PROMPT -error-program-prompt-------------------------------------------------- DBG> examine subrtnCount DBG> show calls DBG> cancel break/all DBG> go DBG> step/return DBG> examine r0 DBG>

After you finish the SCD session, enter the GO command to leave this module. You will encounter another INI$BRK breakpoint at the end of EXEC_INIT. An error message indicating there are no source lines for address 80002010 is displayed, because debug information on this image or module is not available.

Also notice that there is no message in the OUT display for this event. That is because INI$BRKs are special breakpoints that are handled as SS$_DEBUG signals. They are a method for the system code to break into the debugger and there is no real breakpoint in the code.

Example 8-14 Source Lines Error Message

- SRC: module SYSTEM_ROUTINES -scroll-source------------------------------------ 15896: Source line not available 15897: Source line not available . . . 15906: Source line not available ->5907: Source line not available 15908: Source line not available . . . 15917: Source line not available 15918: Source line not available - OUT -output------------------------------------------------------------------- break at C_TEST_ROUTINES\test_c_code3\%LINE 146 break at C_TEST_ROUTINES\test_c_code3\%LINE 146 C_TEST_ROUTINES\test_c_code3\subrtnCount: 8 module name routine name line rel PC abs PC *C_TEST_ROUTINES test_c_code3 146 00000000000000C4 FFFFFFFF83002D64 *C_TEST_ROUTINES test_c_code3 146 00000000000000D4 FFFFFFFF83002D74 *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 stepped to C_TEST_ROUTINES\test_c_code3\%LINE 147 stepped on return from C_TEST_ROUTINES\test_c_code3\%LINE 147 to C_TEST_ROUTINES\test_c_code3\%LINE 148 C_TEST_ROUTINES\test_c_code3\%R0: 0 - PROMPT -error-program-prompt-------------------------------------------------- DBG> examine r0 DBG> go %DEBUG-I-INIBRK, target system interrupted %DEBUG-I-DYNIMGSET, setting image SYS$BASE_IMAGE %DEBUG-W-SCRUNAOPNSRC, unable to open source file SYS$COMMON:[SYSLIB]SYSTEM_ROUTINES.M64; -RMS-E-FNF, file not found DBG>

Enter the SHOW IMAGE command. You will see more images displayed as the boot path has progressed further.

Finally, enter GO, allowing the target system to boot completely, because there are no more breakpoints in the boot path. The debugger will wait for another event to occur.

Example 8-15 Using the Show Image Command

- SRC: module SYSTEM_ROUTINES -scroll-source------------------------------------ 15896: Source line not available 15897: Source line not available . . . 15906: Source line not available ->5907: Source line not available 15908: Source line not available . . . 15917: Source line not available 15918: Source line not available - OUT -output------------------------------------------------------------------- PRO2 FFFFFFFF8329C000 FFFFFFFF832A2DFF SYSLICENSE no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80188000 FFFFFFFF801883FF NPRW1 FFFFFFFF80CCC000 FFFFFFFF80CCC5FF PRO2 FFFFFFFF8321E000 FFFFFFFF832247FF PRW3 FFFFFFFF83226000 FFFFFFFF832265FF SYSTEM_DEBUG yes FFFFFFFF82FFE000 FFFFFFFF83056000 SYSTEM_PRIMITIVES_MIN no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80034000 FFFFFFFF800775FF NPRW1 FFFFFFFF80C31A00 FFFFFFFF80CA11FF SYSTEM_SYNCHRONIZATION_UNI no 0000000000000000 FFFFFFFFFFFFFFFF NPRO0 FFFFFFFF80078000 FFFFFFFF800835FF NPRW1 FFFFFFFF80CA1200 FFFFFFFF80CA35FF total images: 40 bytes allocated: 2803296 - PROMPT -error-program-prompt-------------------------------------------------- %DEBUG-I-INIBRK, target system interrupted %DEBUG-I-DYNIMGSET, setting image SYS$BASE_IMAGE %DEBUG-W-SCRUNAOPNSRC, unable to open source file X6P3_RESD$:[SYSLIB]SYSTEM_ROUTINES.M64; -RMS-E-FNF, file not found DBG> show image DBG> go

This chapter describes the OpenVMS Alpha System Dump Debugger (SDD) and how you can use it to analyze system crash dumps.

SDD is similar in concept to SCD as described in Chapter 8. Where SCD allows connection to a running system with control of the system's execution and the examination and modification of variables, SDD allows analysis of memory as recorded in a system dump.

Use of the SDD usually involves two systems, although all the required environment can be set up on a single system. The description that follows assumes that two systems are being used:

• The build system, where the image that causes the system crash has been built
• The test system, where the image is executed and the system crash occurs

In common with SCD, the OpenVMS debugger's user interface allows you to specify variable names, routine names, and so on, precisely as they appear in your source code. Also, SDD can display the source code where the software was executing at the time of the system crash.

SDD recognizes the syntax, data typing, operators, expressions, scoping rules, and other constructs of a given language. If your code or driver is written in more than one language, you can change the debugging context from one language to another during a debugging session.

To use SDD, you must do the following:

• Build the system image or device driver that is causing the system crash.
• Boot a system, including the system image or device driver, and perform the necessary steps to cause the system crash.
• Reboot the system and save the dump file.
• Invoke SDD, which is integrated with the OpenVMS debugger.

The following sections cover these tasks in more detail, describe the available user-interface options, summarize applicable OpenVMS Debugger commands, and provide a sample SDD session.

9.1 User-Interface Options

SDD has the following user-interface options.

• A DECwindows Motif interface for workstations.
  When using this interface, you interact with SDD by using a mouse and pointer to choose items from menus, click on buttons, select names in windows, and so on.
  Note that you can also use OpenVMS Debugger commands with the DECwindows Motif interface.
• A character cell interface for terminals and workstations.
  When using this interface, you interact with SDD by entering commands at a prompt. The sections in this chapter describe how to use the system dump debugger with the character cell interface.
  For more information about using the OpenVMS DECwindows Motif interface and OpenVMS Debugger commands with SDD, see the OpenVMS Debugger Manual.

To prepare a system dump for analysis, perform the following steps:

1. Compile the sources you will want to analyze, and use the /DEBUG (mandatory) and /NOOPT (preferred) qualifiers.

   Note Because you are analyzing a snapshot of the system, it is not as vital to use unoptimized code as it is with the system code debugger. But note that you cannot access all variables. SDD may report that they are optimized away.

2. Link your image using the /DSF (debug symbol file) qualifier. Do not use the /DEBUG qualifier, which is for debugging user programs. The /DSF qualifier takes an optional filename argument similar to the /EXE qualifier. For more information, see the OpenVMS Linker Utility Manual. If you specify a name in the /EXE qualifier, you will need to specify the same name for the /DSF qualifier. For example, you would use the following command:

   $ LINK/EXE=EXE$:MY_EXECLET/DSF=EXE$:MY_EXECLET OPTIONS_FILE/OPT

   
   The .DSF and .EXE file names must be the same. Only the extensions will be different, that is, .DSF and .EXE.
   The contents of the .EXE file should be exactly the same as if you had linked without the /DSF qualifier. The .DSF file will contain the image header and all the debug symbol tables for .EXE file. It is not an executable file, and cannot be run or loaded.

3. Put the .EXE file on your test system.
4. Boot the test system and perform the necessary steps to cause the system crash.
5. Reboot the test system and copy the dump to the build system using the System Dump Analyzer (SDA) command COPY. See Chapter 4.

The only requirement for the test system is that the .DSF file matching the .EXE file that causes the crash is available on the build system.

There are no other steps necessary in the setup of the test system. With the system image copied to the test system, it can be booted in any way necessary to produce the system crash. Since SDD can analyze most system crash dumps, any system can be used, from a standalone system to a member of a production cluster.

To set up the build system, you need access to all system images and drivers that were loaded on the test system. You should have access to a source listings kit or a copy of the following directories:

SYS$LOADABLE_IMAGES: SYS$LIBRARY: SYS$MESSAGE:

You need all the .EXE files in those directories. The .DSF files are available with the OpenVMS Alpha source listings kit.

Optionally, you need access to the source files for the images to be debugged. SDD will look for the source files in the directory where they were compiled. You must use the SET SOURCE command to point SDD to the location of the source code files if they are not in the directories used when the image was built. For an example of the SET SOURCE command, see Section 9.9.

Before you can analyze a system dump with SDD, you must set up the logical name DBGHK$IMAGE_PATH, which must be set up as a search list to the area where the system images or .DSF files are kept. For example, if the copies are in the following directories:

DEVICE:[SYS$LDR] DEVICE:[SYSLIB] DEVICE:[SYSMSG]

you would define DBGHK$IMAGE_PATH as follows:

$ define dbghk$image_path DEVICE:[SYS$LDR],DEVICE:[SYSLIB],DEVICE:[SYSMSG]

This works well for analyzing a system dump using all the images normally loaded on a given system. However, you might be using SDD to analyze new code either in an execlet or a new driver. Because that image is most likely in your default directory, you must define the logical name as follows:

$ define dbghk$image_path [],DEVICE:[SYS$LDR],DEVICE:[SYSLIB],DEVICE:[SYSMSG]

If SDD cannot find one of the images through this search path, a warning message is displayed. SDD will continue initialization as long as it finds at least one image. If SDD cannot find the SYS$BASE_IMAGE file, which is the OpenVMS Alpha operating system's main image file, an error message is displayed and the debugger exits.

If and when this happens, check the directory for the image files and compare it to what was loaded on the test system.

9.5 Starting the System Dump Debugger

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.

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

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

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

	privacy and legal statement
6549PRO_032.HTML