HP OpenVMS System Analysis Tools Manual


Previous Contents Index


Chapter 12
OpenVMS System Dump Debugger

This chapter describes the OpenVMS 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 11. 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:

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:

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.

12.1 User-Interface Options

SDD has the following user-interface options.

12.2 Preparing a System Dump to Be Analyzed

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

12.3 Setting Up the Test System

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.

Note

It is assumed that the test system has a dump file large enough for the system dump to be recorded. Any dump style may be used (full or selective, compressed or uncompressed). A properly AUTOGENed system will meet these requirements.

12.4 Setting Up the Build System

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 source listings kits.

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 12.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 two images. If SDD cannot find the SYS$BASE_IMAGE and SYS$PUBLIC_VECTORS files, which are the OpenVMS operating system's main image files, 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.

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

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

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

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.

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

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.

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

12.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 11.11.

12.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 11.12, up to and including Example 11-9 (Using the Set Mode Screen Command).
  2. Enter the following OpenVMS Debugger commands:


    DBG> SET BREAK TEST_C_CODE5
    DBG> GO
    DBG> DEPOSIT K=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) 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.

Note that the example displays from Example 12-1 onwards are all taken from an OpenVMS Integrity server system. On an OpenVMS Alpha system, some of the output is different, but the commands entered are the same on both platforms.

Example 12-1 Invoking the System Dump Debugger

$ define dbg$decw$display " " 
$ debug/keep 
 
         OpenVMS I64 Debug64 Version V8.3-003 
 
 
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 12-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 12-3 Displaying the Source Code

 
DBG> Set Mode Screen; Set Step Nosource 
 
- SRC: module C_TEST_ROUTINES -scroll-source------------------------------------ 
    67: 
    68:     /* We want some global data cells */ 
    69: volatile __int64 c_test_array[34]; 
    70: 
    71: void test_c_code5(int *k) 
    72: { 
    73:     int i; 
    74:     char str[100]; 
    75:     for(i=0;i<100;i++) 
    76:       str[i]= 'a'; 
    77:     str[99]=0; 
->  78:     *k = 9; 
    79: } 
    80: void test_c_code4(void) 
    81: { 
    82:     int i,k; 
    83:     for(k=0;k<1000;k++) 
    84:       { 
    85:          test_c_code5(&i); 
    86:       } 
    87:     return; 
    88: } 
    89: int test_c_code3(int subrtnCount) 
- OUT -output------------------------------------------------------------------- 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
- PROMPT -error-program-prompt-------------------------------------------------- 
 
 
 
 
%DEBUG-I-SCRNOTORIGSRC, original version of source file not found for display in SRC 
        file used is SYS$COMMON:[SYSHLP.EXAMPLES]C_TEST_ROUTINES.C;1 
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 12-4 Using the Examine and Show Calls Commands

DBG> Set Mode Screen; Set Step Nosource 
 
- SRC: module C_TEST_ROUTINES -scroll-source------------------------------------ 
    67: 
    68:     /* We want some global data cells */ 
    69: volatile __int64 c_test_array[34]; 
    70: 
    71: void test_c_code5(int *k) 
    72: { 
    73:     int i; 
    74:     char str[100]; 
    75:     for(i=0;i<100;i++) 
    76:       str[i]= 'a'; 
    77:     str[99]=0; 
->  78:     *k = 9; 
    79: } 
    80: void test_c_code4(void) 
    81: { 
    82:     int i,k; 
    83:     for(k=0;k<1000;k++) 
    84:       { 
    85:          test_c_code5(&i); 
    86:       } 
    87:     return; 
    88: } 
    89: int test_c_code3(int subrtnCount) 
- OUT -output------------------------------------------------------------------- 
C_TEST_ROUTINES\test_c_code5\i: 100 
C_TEST_ROUTINES\test_c_code5\k: 0 
 module name     routine name     line           rel PC           abs PC 
*C_TEST_ROUTINES test_c_code5       78       0000000000000CD0 FFFFFFFF800BAED0 
*C_TEST_ROUTINES test_c_code4       85       0000000000000D60 FFFFFFFF800BAF60 
*C_TEST_ROUTINES test_c_code       118       00000000000010D0 FFFFFFFF800BB2D0 
                 XDT$INIT                    00000000000015C0 FFFFFFFF880955C0 
*SYS$DOINIT      EXE$INITIALIZE   1973       0000000000000360 FFFFFFFF88094360 
 SHARE$EXEC_INIT_CODE0                       000000000005C240 FFFFFFFF803BB640 
 SHARE$EXEC_INIT_CODE0                       0000000000057F20 FFFFFFFF803B7320 
 SHARE$EXEC_INIT_CODE0                       0000000000047850 FFFFFFFF803A6C50 
 SHARE$EXEC_INIT_CODE0                       0000000000042E90 FFFFFFFF803A2290 
- PROMPT -error-program-prompt-------------------------------------------------- 
 
%DEBUG-I-SCRNOTORIGSRC, original version of source file not found for display in SRC 
        file used is SYS$COMMON:[SYSHLP.EXAMPLES]C_TEST_ROUTINES.C;1 
DBG> examine i,k 
DBG> show calls 
DBG> 


Previous Next Contents Index