HP OpenVMS Systems Documentation

HP OpenVMS System Analysis Tools Manual

This example shows the output of detailed statistics and status for the cache.

Displays both the extent hash table (EHT) and the file hash table (FHT).

Format

SHOW TABLES [/ALL][/EXTENT][/FILE][/SUMMARY]

Parameters

None.

Qualifiers

/ALL

Displays the contents of the extent hash table (EHT) and file hash table (FHT). This is the default.

/EXTENT

Displays only the contents of the EHT.

/FILE

Displays only the contents of the FHT.

/SUMMARY

Displays summary information about EHT and FHT.

Description

The SHOW TABLES command outputs information about the two hash tables used by XFC to locate key data structures.

Example

SDA> XFC SHOW TABLES/SUMMARY
Full Map of CFB HashTable
-------------------------
FHT: Contents of 32768 buckets


 0(32366)
 1(401)
 2(1)
Total number of CFBs:    403
Longest chain length:    2
Shortest chain length:   0
Shortest chain length:   0
Average chain length:        0.01


Full Map of PECB HashTable
--------------------------
EHT: verifying 524288 buckets


 0(520501)
 1(3755)
 2(32)
Total number of PECBs:   3819
Longest chain length:    2
Shortest chain length:   0
Average chain length:        0.01
      

This example shows summary output about each of the hash tables.

Displays all or selected portions of the XFC trace buffer, starting with the most recent entry and moving backward in time.

Format

SHOW TRACE [/ALL]/CONTAINING=value |/CPU=cpu-num
|/LINENUMBER=linenumber
|/MATCH [=[AND|OR]] |/Px=value

Parameters

None.

Qualifiers

/ALL

Displays the entire trace buffer. This is the default.

/CONTAINING=value

Displays only records where any of the traced parameters is equal to value.

/CPU=cpu-num

Displays only records from threads executing on CPU cpu-num.

/LINENUMBER=linenumber

Displays only records from tracepoints at line linenumber in the relevant source files.

/MATCH [=AND|OR]

Alters the sense of the match condition when more than one of the filter qualifiers /CPU, /LINENUMBER, /FILENAME, /Px, or /CONTAINING are specified.

/Px=value

Displays only records where one of the traced parameters P1, P2, P3, or P4 is equal to value.

Description

The SHOW TRACE command outputs the contents of each entry in the XFC trace buffer. Currently, detailed XFC tracing is enabled only for debug versions of XFC.

Example

This example shows the output of XFC trace information.

Displays the contents of a cache volume block (CVB).

Format

SHOW VOLUME [address]/BRIEF|/FULL| /NAME=DISK $volume_label| /STATISTICS

Parameter

address

The address of a CVB. If no address is supplied, then all volumes are displayed.

Qualifiers

/BRIEF

Displays summary information for each volume.

/FULL

Displays a complete list of information about each volume. This is the default.

/NAME=DISK$volume_label

Displays information for the volume with the specified name.

/STATISTICS

Displays the read and write I/O activity for this volume. The /STATISTICS qualifier is incompatible with the /BRIEF qualifier.

Description

The SHOW VOLUME command shows state information and statistics about all volumes mounted on the system.

Examples

This example shows the output derived from invoking the /BRIEF qualifer.

2. SDA> XFC SHOW VOLUME FFFFFFFD831FE080
Cache Volume Block (CVB)
------------------------
Statistics Valid From:   19-APR-2002 07:10:23.54

Name:                  DISK$FRROOG_RUBY
CVB Address:           FFFFFFFD831FE080
Flink:                 FFFFFFFF80D30238
Blink:                 FFFFFFFD831FE300
Volume (VCB):          FFFFFFFF81905100
Unit (UCB):            FFFFFFFF8150F200
Files Queue:           FFFFFFFD831FE0C0
    Flink:               FFFFFFFD83111800
    Blink:               FFFFFFFD831FC0A0
Cached Open Files:            236
Cached Closed Files:          157
Files Ever Opened:            502
Files Ever Deposed:           109
Pages Allocated:             2726
Total QIOs:                  4195
Read Hit Count:              2408
Virtual Read Count:          4085
Virtual Write Count:          110
Read Percentage:               97 %
Hit Rate:                      57 %
Average Overall I/O response time to this Volume
 in milliseconds:             2.1186
Average Cache Hit I/O response time to this Volume
 in milliseconds:             0.0789
Average Disk I/O response time to this Volume
 in milliseconds:             4.8671
Accuracy of I/O resp time:     83 %
Readahead Count:              233
Volume Caching Mode:   evcmVIOCCompatible
Mounted /NOCACHE:      False     VCML Allows Caching:   True
Quiescing:             False     Quiesce in Progress:   False
No Cache from Logio:   False     VIL Blk AST Stall:     False
Flush Pending:         False     VCML Blk AST Stall:    False
VCML Blk CTX Stall:    False     VIL Blk CTX Stall:     False
Dismount Stall:        False     Logio Stall:           False
Flush in Progress:     False     Cluster Trans Stall:   False
Dismount Pending:      False     VIL Up Needed:         False
Tqe In Use:            False     VCML Up Needed:        False
VIL blocking AST CTX:  0000000000000000
VCML blocking AST CTX: 0000000000000000
Dismount Stall CTX:    0000000000000000
LogIO Stall CTX:       0000000000000000
Up conversion CTX:     0000000000000000
VIL lock id:           0100007A
VIL LogIO lock id:     00000000
VCML lock id:          010000FF
VCML LogIO lock id:    00000000
Logical IO safety:     elogioNotSafe
LogIOMutex:            00000000818EB610
Last LogIO time:       00000000
Active I/O count:              0
Stalled Ops Queue:     FFFFFFFD831FE0B0
    Flink:               FFFFFFFD831FE0B0
    Blink:               FFFFFFFD831FE0B0


Volumes found: 1

This example shows the output for a specific cache volume block (CVB).

This chapter describes how to write, debug, and invoke an SDA Extension. This chapter also describes the routines available to an SDA Extension.

10.1 Introduction

When analysis of a dump file or a running system requires intimate knowledge of data structures that are not known to the System Dump Analyzer, the functionality of SDA can be extended by the addition of new commands into which the necessary knowledge has been built. Note that in this description, whenever a reference is made to accessing a dump file (ANALYZE/CRASH_DUMP), this also includes accessing memory in the running system (ANALYZE/SYSTEM).

For example, a user-written device driver allocates nonpaged pool and records additional data about the device there (logging different types of I/O, perhaps), and a pointer to the new structure is saved in the device-specific extension of the UCB. After a system crash, the only way to look at the data from SDA is to do the following:

• Invoke the SDA command DEFINE to define a new symbol (for example, UCB$L_FOOBAR) whose value is the offset in the UCB of the pointer to the new structure.
• Invoke the SDA commands "SHOW DEVICE <device>" and "FORMAT UCB" to obtain the address of the nonpaged pool structure.
• Invoke the SDA command "EXAMINE <address>;<length>" to display the contents of the data in the new nonpaged pool structure as a series of hexadecimal longwords.
• Decode manually the contents of the data structure from this hexadecimal dump.

An SDA extension that knows the layout of the nonpaged pool structure, and where to find the pointer to it in the UCB, could output the data in a formatted display that alerts the user to unexpected data patterns.

10.2 Description

The following discussion uses an example of an SDA extension that invokes the MBX command to output a formatted display of the status of the mailbox devices in the system. The source file, MBX$SDA.C, is provided in SYS$EXAMPLES.

An SDA extension consists of a shareable image, in this case MBX$SDA.EXE, either located in the directory SYS$LIBRARY or found by translating the logical name MBX$SDA. It contains two universal symbols: SDA$EXTEND, the entry point; and SDA$EXTEND_VERSION, the address of a longword that contains the version of the interface used (in the format of major/minor ident), which allows SDA to confirm it has activated a compatible extension. The image contains at least two modules: MBX$SDA, the user-written module that defines the two symbols and provides the code and data necessary to produce the desired formatted output; and SDA_EXTEND_VECTOR, which provides jackets for all of the callable SDA routines, and is found in SYS$LIBRARY:VMS$VOLATILE_PRIVATE_INTERFACES.OLB. The user-written portion can be split into multiple modules.

Whenever SDA receives an unrecognized command, like "SDA> MBX", it attempts to activate the shareable image MBX$SDA at the SDA$EXTEND entry point. If you choose a command name that matches the abbreviation of an existing command, SDA can be forced to activate the extension using the "DO" command. For example, if you had an SDA extension called VAL$SDA, you could not activate it with a command like "SDA> VAL" as SDA would interpret that as an abbreviation of its VALIDATE command. But VAL$SDA can be activated by issuing "SDA> DO VAL".

With or without the "DO" prefix, the rest of the command line is passed to the extension; it is up to the extension to parse it. The example extension MBX$SDA includes support for commands of the form "SDA> MBX SUMMARY" and "SDA> MBX <address>" to demonstrate this. If the extension is invoked with no arguments, it should do no more than display a simple announcement message, or prompt for input. This assists in the debugging of the extension, as described in Section 10.3.

Section 10.2.1 describes how to compile, link, and invoke an SDA extension, and describes what an SDA extension should contain.

10.2.1 Compiling and Linking an SDA Extension

$cc mbx$sda + sys$library:sys$lib_c /library
$link /share -
                mbx$sda.obj, -
                sys$library:vms$volatile_private_interfaces /library, -
                sys$input /option
        symbol_vector = (sda$extend=procedure)
        symbol_vector = (sda$extend_version=data)

You can invoke the SDA extension as follows:

$define mbx$sda sys$disk:[]mbx$sda
$analyze /system
SDA>mbx summary
SDA>mbx <address>

At a minimum, the user-written module must contain:

• #include statements for DESCRIP.H and SDA_ROUTINES.H
• The global variable SDA$EXTEND_VERSION, initialized as follows:

  int sda$extend_version = SDA_FLAGS$K_VERSION;

• The routine SDA$EXTEND (prototype follows)

Optionally, the user-written module may also contain the statement:

        #define __NEW_STARLET

You should use this option because it provides type checking of function arguments and gives consistency in casing and naming conventions.

The entry point in the user-written module, SDA$EXTEND, is called as a routine with three arguments and no return value. The declaration is as follows:

        void sda$extend (
                int *transfer_table,
                struct dsc$descriptor_s *cmd_line,
                SDA_FLAGS sda_flags)

The arguments in this code example have the following meanings:

The first executable statement of the routine must be to copy TRANSFER_TABLE to SDA$VECTOR_TABLE (which is declared in SDA_ROUTINES.H):

        sda$vector_table = transfer_table;

If this is not done, you cannot call any of the routines described below. Any attempts to call the routines receive a status return of SDA$_VECNOTINIT. (For routines defined not to return a status, this value can be found only by examining R0.)

The next statement should be one to establish a condition handler, as it is often difficult to track down errors in extensions such as access violations because the extension is activated dynamically with LIB$FIND_IMAGE_SYMBOL. A default condition handler, SDA$COND_HANDLER, is provided that outputs the following information in the event of an error:

• The error condition
• The VMS version
• A list of activated images, with start and end virtual addresses
• The signal array and register dump
• The current call frame chain

You can establish this condition handler as follows:

        lib$establish (sda$cond_handler);

Thus, a minimal extension would be:

        #define __NEW_STARLET 1
        #include <descrip.h>
        #include <sda_routines.h>

        int sda$extend_version = SDA_FLAGS$K_VERSION;

        void sda$extend (int *transfer_table,
                         struct dsc$descriptor_s *cmd_line,
                         SDA_FLAGS sda_flags)
          {
          sda$vector_table = transfer_table;
          lib$establish (sda$cond_handler);

          sda$print ("hello, world");
          return;
          }

In addition to the "after-the-fact" information provided by the condition handler, you can debug SDA extensions using the OpenVMS Debugger. A second copy of the SDA image, SDA_DEBUG.EXE, is provided in SYS$SYSTEM. By defining the logical name SDA to reference this image, you can debug SDA extensions as follows:

• Compile your extension /DEBUG/NOOPT and link it /DEBUG or /DSF.
• Define logical names for SDA and the extension, and invoke SDA.
• Type SET BREAK START_EXTENSION at the initial DBG> prompt, and then type GO.
• Invoke the extension at the SDA> prompt.
• When Debug prompts again, use Debug commands to set breakpoints, and so on, in the extension and then type GO.
• Invoke the extension, providing the necessary arguments.

An example of the preceding steps is as follows:

        $ cc /debug /noopt mbx$sda + alpha$library:sys$lib_c /library
        $ link /debug /share -
                mbx$sda.obj, -
                alpha$library:vms$volatile_private_interfaces /library, -
                sys$input /option
        symbol_vector = (sda$extend=procedure)
        symbol_vector = (sda$extend_version=data)
        $ !
        $ define mbx$sda sys$disk:[]mbx$sda
        $ define sda sda_debug
        $ analyze /system
        ...
        DBG> set break start_extension
        DBG> go
        ...
        SDA> mbx
        break at routine START\START_EXTENSION
        ...
        DBG> set image mbx$sda
        DBG> set language c
        DBG> set break /exception
        DBG> go
        MBX commands: 'MBX SUMMARY' and 'MBX <address>'
        SDA> mbx summary
        ...
        SDA> mbx <address>
        ...
        %DEBUG-I-DYNMODSET, setting module MBX$SDA
        %SYSTEM-E-INVARG, invalid argument
        ...
        DBG>

The user-written routine may call SDA routines to accomplish any of the following tasks:

• Read the contents of memory locations in the dump.
• Translate symbol names to values and vice-versa, define new symbols, and read symbol table files.
• Map an address to the activated image or executive image that contains that address.
• Output text to the terminal, with page breaks, page headings, and so on (and which is output to a file if the SDA commands SET OUTPUT or SET LOG have been used).
• Allocate and deallocate dynamic memory.
• Validate queues/lists.
• Format data structures.
• Issue any SDA command.

The full list of available routines is as follows:

The details of all these routines follow. But there are some points to be aware of in using them:

• There are three different routines available to read the contents of memory locations in the dump: SDA$TRYMEM, SDA$GETMEM, and SDA$REQMEM. They are used as follows:
  SDA$TRYMEM is called from both SDA$GETMEM and SDA$REQMEM as the lower-level routine that actually does the work. SDA$TRYMEM returns success/failure status in R0, but does not signal any errors. Use it directly when you expect that the location being read may be inaccessible. The caller of SDA$TRYMEM will handle this situation by checking the status returned by SDA$TRYMEM.
  SDA$GETMEM signals a warning when any error status is returned from SDA$TRYMEM. Signaling a warning will print out a warning message, but does not abort the SDA command in progress. You should use this routine when you expect the location to be read to be accessible. This routine does not prevent the command currently being executed from continuing. The caller of SDA$GETMEM must allow for this by checking the status returned by SDA$GETMEM.
  SDA$REQMEM signals an error when any error status is returned from SDA$TRYMEM. Signaling an error will print out an error message, abort the SDA command in progress and return to the "SDA>" prompt. You should use this routine when you expect the location to be read to be accessible. This routine will prevent the command currently being executed from continuing. The caller of SDA$REQMEM will not resume if an error occurs.
• You should use only the routines provided to output text. Do not use printf() or any other standard routine. If you do, the SDA commands SET OUTPUT and SET LOG will not produce the expected results. Do not include control characters in output (except tab); in particular, avoid <CR>, <LF>,<FF>, and the FAO directives that create them. Use the FAO directive !AF when contents of memory returned by SDA$TRYMEM, and so on, are being displayed directly, because embedded control characters will cause undesirable results. For example, displaying process names or resource names that contain particular control characters or escape sequences can lock up the terminal.
• You should use only the routines provided to allocate and deallocate dynamic memory. Do not use malloc() and free(). Where possible, allocate dynamic memory once, the first time the extension is activated, and deallocate it only if it needs to be replaced by a larger allocation. Because SDA commands can be interrupted by invoking another command at the "Press return for more" prompt, it is very easy to cause memory leaks.
• Some routines expect 32-bit pointers, and others expect 64-bit pointers. At first this not may appear to be logical, but in fact it is. All code and data used by SDA and any extensions must be in P0 or P1 space, as SDA does not need to (and does not) use P2 space for local data storage. However, addresses in the system dump (or running system, in the case of ANALYZE/SYSTEM) are 64-bit addresses, and SDA must provide access to all locations in the dump.

So, for example, the first two arguments to the routine SDA$TRYMEM are:

        VOID_PQ start   /* 64-bit pointer */

        void *dest      /* 32-bit pointer */

They specify the address of interest in the dump and the address in local storage to which the dump contents are to be copied.