OpenVMS Alpha System Analysis Tools Manual

Document revision date: 30 March 2001

OpenVMS Alpha System Analysis Tools Manual

Contents

Index

EXAMINE

Displays either the contents of a location or range of locations in physical memory, or the contents of a register. Use location parameters to display specific locations or use qualifiers to display the entire process and system regions of memory.

Format

EXAMINE [/qualifier[,...]] [location]

Parameter

location
Location in memory to be examined. A location can be represented by any valid SDA expression. (See Chapter 2, Section 2.6.2 for additional information about expressions.) To examine a range of locations, use the following syntax:

m:n Range of locations to be examined, from m to n

m;n Range of locations to be examined, starting at m and continuing for n bytes

The default location that SDA uses is initially 0 in the program region (P0) of the process that was executing at the time the system failed (if you are examining a crash dump) or your process (if you are examining the running system). Subsequent uses of the EXAMINE command with no parameter specified increase the last address examined by eight. Use of the /INSTRUCTION qualifier increases the default address by four. To examine memory locations of other processes, you must use the SET PROCESS command.

Qualifiers

/ALL
Examines all the locations in the program, and control regions and system space, displaying the contents of memory in hexadecimal longwords and ASCII characters. Do not specify parameters when you use this qualifier.
/CONDITION_VALUE
Examines the specified longword, displaying the message that the $GETMSG system service obtains for the value in the longword.
/INSTRUCTION
Translates the specified range of memory locations into assembly instruction format. Each symbol in the EXAMINE expression that is defined as a procedure descriptor is replaced with the code entry point address of that procedure, unless you also specify the /NOPD qualifier.
/NOPD
Can be used with the /INSTRUCTION qualifier to override treating symbols as procedure descriptors. You can place the qualifier immediately after the /INSTRUCTION qualifier, or following a symbol name.
For more details on using the /NOPD qualifier, see the description for the /PD qualifier.
/NOSUPPRESS
Inhibits the suppression of zeros when displaying memory with one of the following qualifiers: /ALL, /P0, /P1, /SYSTEM, or when a range is specified.
/P0
Displays the entire program region for the default process. Do not specify parameters when you use this qualifier.
/P1
Displays the entire control region for the default process. Do not specify parameters when you use this qualifier.
/PD
Causes the EXAMINE command to treat the location specified in the EXAMINE command as a procedure descriptor (PD). PD can also be used to qualify symbols.
The /PD and /NOPD qualifiers can be used with the /INSTRUCTION qualifier to override treating symbols as procedure descriptors. Placing the qualifier right after a symbol will override how the symbol is treated. /PD will force it to be a procedure descriptor, and /NOPD will force it to not be a procedure descriptor.
Only the /PD qualifier can be placed right after the /INSTRUCTION qualifier. It treats the calculated value as a process descriptor.
In the following examples, TEST_ROUTINE is a PD symbol. Its value is 500 and the code address in this procedure descriptor is 1000. The first example displays intructions starting at 520.
EXAMINE/INSTRUCTION TEST_ROUTINE/NOPD+20
The next example fetches code address from TEST_ROUTINE PD, adds 20 and displays instructions at that address. In other words, it displays code starting at location 1020.
EXAMINE/INSTRUCTION TEST_ROUTINE+20
The final example treates the address TEST_ROUTINE+20 as a procedure descriptor, so it fetches the code address out of a procedure descriptor at address 520. It then uses that address to display instructions.
EXAMINE/INSTRUCTION/PD TEST_ROUTINE/NOPD+20
/PHYSICAL
Examines physical addresses. The /PHYSICAL qualifier cannot be used in combination with the /P0, /P1, or /SYSTEM qualifiers.
/PS
Examines the specified quadword, displaying its contents in the format of a processor status. This qualifier must precede any parameters used in the command line.
/PTE
Interprets and displays the specified quadword as a page table entry (PTE). The display separates individual fields of the PTE and provides an overall description of the PTE's type.
/SYSTEM
Displays portions of the writable system region. Do not specify parameters when you use this qualifier.
/TIME
Examines the specified quadword, displaying its contents in the format of a system-date-and-time quadword.

Description

The following sections describe how to use the EXAMINE command.
Examining Locations

When you use the EXAMINE command to look at a location, SDA displays the location in symbolic notation (symbolic name plus offset), if possible, and its contents in hexadecimal and ASCII formats:
SDA> EXAMINE G6605C0 806605C0: 64646464.64646464 "dddddddd"
If the ASCII character that corresponds to the value contained in a byte is not printable, SDA displays a period (.). If the specified location does not exist in memory, SDA displays this message:
%SDA-E-NOTINPHYS, address : virtual data not in physical memory
To examine a range of locations, you can designate starting and ending locations separated by a colon. For example:
SDA> EXAMINE G40:G200
Alternatively, you can specify a location and a length, in bytes, separated by a semicolon. For example:
SDA> EXAMINE G400;16
When used to display the contents of a range of locations, the EXAMINE command displays six or ten columns of information. Ten columns are used if the terminal width is 132 or greater, or if a SET OUTPUT has been entered; six columns are used otherwise. An explanation of the columns is as follows:

Each of the first four or eight columns represents a longword of memory, the contents of which are displayed in hexadecimal format.
The fifth or ninth column lists the ASCII value of each byte in each longword displayed in the previous four or eight columns.
The sixth or tenth column contains the address of the first, or rightmost, longword in each line. This address is also the address of the first, or leftmost, character in the ASCII representation of the longwords. Thus, you read the hexadecimal dump display from right to left, and the ASCII display from left to right.

If a series of virtual addresses does not exist in physical memory, SDA displays a message specifying the range of addresses that were not translated.
If a range of virtual locations contains only zeros, SDA displays this message:
Zeros suppressed from 'loc1' to 'loc2'
Decoding Locations

You can translate the contents of memory locations into instruction format by using the /INSTRUCTION qualifier. This qualifier causes SDA to display the location in symbolic notation (if possible) and its contents in instruction format. The operands of decoded instructions are also displayed in symbolic notation. The location must be longword aligned.
Examining Memory Regions

You can display an entire region of virtual memory by using one or more of the qualifiers /ALL, /SYSTEM, /P0, and /P1 with the EXAMINE command.
Other Uses

Other uses of the EXAMINE command appear in the following examples.

Examples

#1
SDA> EXAMINE/PS 7FF95E78 MBZ SPAL MBZ IPL VMM MBZ CURMOD INT PRVMOD 0 00 00000000000 08 0 0 KERN 0 EXEC

This example shows the display produced by the EXAMINE/PS command.

#2
SDA> EXAMINE/PTE @^QMMG$GQ_L1_BASE

3 3 2 2 2 1 1 1 1 0 9 7 0 8 6 5 7 6 0 +-+-+--+--------------+-+-+---+-+---------------+-+-----------+-+ |0|1|00| 0000 |0|X| 00|0| 11 |X| 04 |1| +-+-+--+--------------+-+-+---+-+---------------+-+-----------+-+ | 00000C37 | +---------------------------------------------------------------+ Valid PTE: Read Prot = K---, Write Prot = K--- Owner = K, Fault on = -E--, ASM = 00, Granularity Hint = 00 CPY = 00 PFN = 00000C37

The EXAMINE/PTE command displays and formats the level 1 page table entry at FFFFFFFF.FF7FC000.

EXIT

Exits from an SDA display or exits from the SDA utility.

Format

EXIT

Parameters

None.

Qualifiers

None.

Description

If SDA is displaying information on a video display terminal---and if that information extends beyond one screen---SDA displays a screen overflow prompt at the bottom of the screen:
Press RETURN for more. SDA>
If you want to discontinue the current display at this point, enter the EXIT command. If you want SDA to execute another command, enter that command. SDA discontinues the display as if you entered EXIT, and then executes the command you entered.
When the SDA> prompt is not immediately preceded by the screen overflow prompt, entering EXIT causes your process to cease executing the SDA utility. When issued within a command procedure (either the SDA initialization file or a command procedure invoked with the execute command (@)), EXIT causes SDA to terminate execution of the procedure and return to the SDA prompt.

FORMAT

Displays a formatted list of the contents of a block of memory.

Format

FORMAT [/TYPE=block-type] location [/PHYSICAL]

Parameter

location
Location of the beginning of the data block. The location can be given as any valid SDA expression.

Qualifiers

/TYPE=block-type
Forces SDA to characterize and format a data block at location as the specified type of data structure. The /TYPE qualifier thus overrides the default behavior of the FORMAT command in determining the type and/or subtype of a data block, as described in the Description section. The block-type can be the symbolic prefix of any data structure defined by the operating system.
/PHYSICAL
Specifies that the location given is a physical address.

Description

The FORMAT command performs the following actions:

Characterizes a range of locations as a system data block
Assigns, if possible, a symbol to each item of data within the block
Displays all the data within the block

Most OpenVMS Alpha control blocks include two bytes that indicate the block type and/or subtype at offsets 0A₁₆ and 0B₁₆, respectively. The type and/or subtype associate the block with a set of symbols that have a common prefix. Each symbol's name describes a field within the block, and the value of the symbol represents the offset of the field within the block.
If the type and/or subtype bytes contain a valid block type/subtype combination, SDA retrieves the symbols associated with that type of block (see $DYNDEF) and uses their values to format the block.
For a given block type, all associated symbols have the form
<block_type>$<field>_<name>
where field is one of the following:
B Byte W Word L Longword Q Quadword O Octaword A Address C Constant G Global Longword P Pointer R Structure (variable size) T Counted ASCII string (up to 31 characters)
If SDA cannot find the symbols associated with the block type specified in the block-type byte or by the /TYPE qualifier, it issues this message:
%SDA-E-NOSYMBOLS, no <block type> symbols found to format this block
If you receive this message, you may want to read additional symbols into the SDA symbol table and retry the FORMAT command. Many symbols that define OpenVMS Alpha data structures are contained within SDA$READ_DIR:SYSDEF.STB. Thus, you would issue the following command:
SDA> READ SDA$READ_DIR:SYSDEF.STB
If SDA issues the same message again, try reading additional symbols. Table 2-4 lists additional modules provided by the OpenVMS operating system. Alternatively, you can create your own object modules with the MACRO-32 Compiler for OpenVMS Alpha. See the READ command description for instructions on creating such an object module.
Certain OpenVMS Alpha data structures do not contain a block type and/or subtype. If bytes contain information other than a block type/subtype---or do not contain a valid block type/subtype---SDA either formats the block in a totally inappropriate way, based on the contents of offsets 0A₁₆ and 0B₁₆, or displays this message:
%SDA-E-INVBLKTYP, invalid block type in specified block
To format such a block, you must reissue the FORMAT command, using the /TYPE qualifier to designate a block-type.
The FORMAT command produces a 3-column display:

The first column shows the virtual address of each item within the block.
The second column lists each symbolic name associated with a location within the block.
The third column shows the contents of each item in hexadecimal format, including symbolization if a suitable symbol exists.

Example


SDA> READ SDA$READ_DIR:SYSDEF.STB %SDA-I-READSYM, 913 symbols read from SYS$COMMON:[SYS$LDR]SYSDEF.STB SDA> FORMAT G41F818 FFFFFFFF.8041F818 UCB$L_FQFL 8041F818 UCB UCB$L_MB_MSGQFL UCB$L_RQFL UCB$W_MB_SEED UCB$W_UNIT_SEED FFFFFFFF.8041F81C UCB$L_FQBL 8041F818 UCB UCB$L_MB_MSGQBL UCB$L_RQBL FFFFFFFF.8041F820 UCB$W_SIZE 0110 FFFFFFFF.8041F822 UCB$B_TYPE 10 FFFFFFFF.8041F823 UCB$B_FLCK 2C FFFFFFFF.8041F824 UCB$L_ASTQFL 00000000 UCB$L_FPC UCB$L_MB_W_AST UCB$T_PARTNER . . .

SDA> READ SDA$READ_DIR:SYSDEF.STB
%SDA-I-READSYM, 913 symbols read from SYS$COMMON:[SYS$LDR]SYSDEF.STB
SDA> FORMAT G41F818
FFFFFFFF.8041F818   UCB$L_FQFL                      8041F818        UCB
                    UCB$L_MB_MSGQFL                 
                    UCB$L_RQFL                      
                    UCB$W_MB_SEED                   
                    UCB$W_UNIT_SEED                 
FFFFFFFF.8041F81C   UCB$L_FQBL                      8041F818        UCB
                    UCB$L_MB_MSGQBL                 
                    UCB$L_RQBL                      
FFFFFFFF.8041F820   UCB$W_SIZE                          0110         
FFFFFFFF.8041F822   UCB$B_TYPE                        10     
FFFFFFFF.8041F823   UCB$B_FLCK                      2C       
FFFFFFFF.8041F824   UCB$L_ASTQFL                    00000000         
                    UCB$L_FPC                       
                    UCB$L_MB_W_AST                  
                    UCB$T_PARTNER                   
   .
   .
   .

The READ command loads the symbols from SDA$READ_DIR:SYSDEF.STB into SDA's symbol table. The FORMAT command displays the data structure that begins at G41F818₁₆, a unit control block (UCB). If a field has more than one symbolic name, all such names are displayed. Thus, the field that starts at 8041F824₁₆ has four designations: UCB$L_ASTQFL, UCB$L_FPC, UCB$L_MB_W_AST, and UCB$T_PARTNER.
The contents of each field appear to the right of the symbolic name of the field. Thus, the contents of UCB$L_FQBL are 8041F818₁₆.

HELP

Displays information about the SDA utility, its operation, and the format of its commands.

Format

HELP [topic-name]

Parameter

topic-name
Topic for which you need information. A topic can be a command name or one of the following keywords.

Keyword Function

ANALYZE_USAGE_SUMMARY Describes the parameters and qualifiers for the ANALYZE/CRASH_DUMP and ANALYZE/SYSTEM DCL commands

CPU_CONTEXT Describes the concept of CPU context as it governs the behavior of SDA

EXECUTE_COMMAND Describes the use of @ file to execute SDA commands contained in a file

EXPRESSIONS Prints a description of SDA expressions

INITIALIZATION Describes the circumstances under which SDA executes an initialization file when first invoked

OPERATION Describes how to operate SDA at your terminal and by means of the site-specific startup procedure

PROCESS_CONTEXT Describes the concept of process context as it governs the behavior of SDA

SDA_CLUE_EXTENSION_COMMANDS Provides an overview of SDA CLUE (Crash Log Utility Extractor)

SDA_EXTENSION_ROUTINES Describes how to write, debug, and invoke an SDA extension and provides details of all callable routines

SDA_SPINLOCK_TRACING_COMMANDS Provides an overview of SDA SPL (Spinlock Tracing Utility)

SYMBOLS Describes the symbols used by SDA

Keyword	Function
ANALYZE_USAGE_SUMMARY	Describes the parameters and qualifiers for the ANALYZE/CRASH_DUMP and ANALYZE/SYSTEM DCL commands
CPU_CONTEXT	Describes the concept of CPU context as it governs the behavior of SDA
EXECUTE_COMMAND	Describes the use of @ file to execute SDA commands contained in a file
EXPRESSIONS	Prints a description of SDA expressions
INITIALIZATION	Describes the circumstances under which SDA executes an initialization file when first invoked
OPERATION	Describes how to operate SDA at your terminal and by means of the site-specific startup procedure
PROCESS_CONTEXT	Describes the concept of process context as it governs the behavior of SDA
SDA_CLUE_EXTENSION_COMMANDS	Provides an overview of SDA CLUE (Crash Log Utility Extractor)
SDA_EXTENSION_ROUTINES	Describes how to write, debug, and invoke an SDA extension and provides details of all callable routines
SDA_SPINLOCK_TRACING_COMMANDS	Provides an overview of SDA SPL (Spinlock Tracing Utility)
SYMBOLS	Describes the symbols used by SDA

Qualifiers

None.

Description

The HELP command displays brief descriptions of SDA commands and concepts on the terminal screen (or sends these descriptions to the file designated in a SET OUTPUT command). You can request additional information by specifying the name of a topic in response to the Topic? prompt.
If you do not specify a parameter in the HELP command, it lists the features of SDA and those commands and topics for which you can request help, as follows:

Example


SDA> HELP HELP The System Dump Analyzer (SDA) allows you to inspect the contents of memory as saved in the dump taken at crash time or as exists in a running system. You can use SDA interactively or in batch mode. You can send the output from SDA to a listing file. You can use SDA to perform the following operations: Assign a value to a symbol Examine memory of any process Format instructions and blocks of data Display device data structures Display memory management data structures Display a summary of all processes on the system Display the SDA symbol table Copy the system dump file Send output to a file or device Read global symbols from any object module Send output to a file or device Read global symbols from any object module Search memory for a given value For help on performing these functions, use the HELP command and specify a topic. Format HELP [topic-name] Additional information available: ANALYZE_Usage_Summary ATTACH CLUE COPY CPU_Context DEFINE DUMP EVALUATE EXAMINE Execute_Command EXIT Expressions FORMAT HELP Initialization MAP MODIFY Operation Process_Context READ REPEAT SDA_CLUE_Extension_Commands SDA_Extension_Routines SDA_Spinlock_Tracing_Commands SEARCH SET SHOW SPAWN SPL Symbols UNDEFINE VALIDATE Topic?

SDA> HELP
HELP 
 
 
     The System Dump Analyzer (SDA) allows you to inspect the contents 
     of memory as saved in the dump taken at crash time or as exists 
     in a running system. You can use SDA interactively or in batch 
     mode. You can send the output from SDA to a listing file. You can 
     use SDA to perform the following operations: 
 
                      Assign a value to a symbol 
                      Examine memory of any process 
                      Format instructions and blocks of data 
                      Display device data structures 
                      Display memory management data structures 
                      Display a summary of all processes on the system 
                      Display the SDA symbol table 
                      Copy the system dump file 
                      Send output to a file or device 
                      Read global symbols from any object module 
                      Send output to a file or device 
                      Read global symbols from any object module 
                      Search memory for a given value 
 
     For help on performing these functions, use the HELP command and 
     specify a topic. 
 
     Format 
 
       HELP  [topic-name] 
 
 
 
 
  Additional information available: 
 
  ANALYZE_Usage_Summary ATTACH     CLUE       COPY       CPU_Context 
  DEFINE     DUMP       EVALUATE   EXAMINE    Execute_Command       EXIT 
  Expressions           FORMAT     HELP       Initialization        MAP 
  MODIFY     Operation  Process_Context       READ       REPEAT 
  SDA_CLUE_Extension_Commands      SDA_Extension_Routines 
  SDA_Spinlock_Tracing_Commands    SEARCH     SET        SHOW       SPAWN 
  SPL        Symbols    UNDEFINE   VALIDATE 
 
Topic?

MAP

Transforms an address into an offset in a particular image.

Format

MAP address

Parameter

address
Address to be identified.

Qualifiers

None.

Description

The MAP command identifies the image name and offset corresponding to an address. With this information, you can examine the image map to locate the source module and program section offset corresponding to an address. MAP searches for the specified address in executive images first. It then checks activated images in process space to include those images installed using the /RESIDENT qualifier of the Install utility. Finally, it checks all image-resident sections in system space.
If the address cannot be found, MAP displays the following message:
%SDA-E-NOTINIMAGE, Address not within a system/installed image

Examples

#1
SDA> MAP G90308 Image Base End Image Offset SYS$VM Nonpaged read only 80090000 800ABA00 00000308

Examining the image map identified by this MAP command (SYS$VM.MAP) shows that image offset 308 falls within psect EXEC$HI_USE_PAGEABLE_CODE because the psect goes from offset 0 to offset 45D3:
. . . EXEC$HI_USE_PAGEABLE_CODE 00000000 000045D3 000045D4 ( 17876.) 2 ** 5... SYSCREDEL 00000000 0000149B 0000149C ( 5276.) 2 ** 5 SYSCRMPSC 000014A0 000045D3 00003134 ( 12596.) 2 ** 5 EXEC$NONPAGED_CODE 000045E0 0001B8B3 000172D4 ( 94932.) 2 ** 5... EXECUTE_FAULT 000045E0 0000483B 0000025C ( 604.) 2 ** 5 IOLOCK 00004840 000052E7 00000AA8 ( 2728.) 2 ** 5 LOCK_SYSTEM_PAGES . . .
Specifically, image offset 308 is located within source module SYSCREDEL. Therefore, to locate the corresponding code, you would look in SYSCREDEL for offset 308 in psect EXEC$HI_USE_PAGEABLE_CODE.

#2
SDA> MAP G550000 Image Base End Image Offset SYS$DKDRIVER 80548000 80558000 00008000

In this example, the MAP command identifies the address as an offset into an executive image that is not sliced. The base and end addresses are the boundaries of the image.

#3
SDA> MAP G550034 Image Base End Image Offset SYS$DUDRIVER Nonpaged read/write 80550000 80551400 00008034

In this example, the MAP command identifies the address as an offset into an executive image that is sliced. The base and end addresses are the boundaries of the image section that contains the address of interest.

#4
SDA> MAP GF0040 Image Resident Section Base End Image Offset MAILSHR 800F0000 80119000 00000040

The MAP command identifies the address as an offset into an image-resident section residing in system space.

#5
SDA> MAP 12000 Activated Image Base End Image Offset MAIL 00010000 000809FF 00002000

The MAP command identifies the address as an offset into an activated image residing in process-private space.

#6
SDA> MAP B2340 Compressed Data Section Base End Image Offset LIBRTL 000B2000 000B6400 00080340

Previous Next Contents Index

privacy and legal statement

6549PRO_006.HTML

m:n	Range of locations to be examined, from m to n
m;n	Range of locations to be examined, starting at m and continuing for n bytes

OpenVMS Alpha System Analysis Tools Manual

EXAMINE

Format

Parameter

location

Qualifiers

/ALL

/CONDITION_VALUE

/INSTRUCTION

/NOPD

/NOSUPPRESS

/P0

/P1

/PD

/PHYSICAL

/PS

/PTE

/SYSTEM

/TIME

Description

Examples

EXIT

Format

Parameters

Qualifiers

Description

FORMAT

Format

Parameter

location

Qualifiers

/TYPE=block-type

/PHYSICAL

Description

Example

HELP

Format

Parameter

topic-name

Qualifiers

Description

Example

MAP

Format

Parameter

address

Qualifiers

Description

Examples