|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
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).
SHOW TABLES [/ALL][/EXTENT][/FILE][/SUMMARY]
None.
/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.
The SHOW TABLES command outputs information about the two hash tables used by XFC to locate key data structures.
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.
SHOW TRACE [/ALL]/CONTAINING=value |/CPU=cpu-num
|/LINENUMBER=linenumber
|/MATCH [=[AND|OR]] |/Px=value
None.
/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.
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.
This example shows the output of XFC trace information.
Displays the contents of a cache volume block (CVB).
SHOW VOLUME [address]/BRIEF|/FULL| /NAME=DISK $volume_label| /STATISTICS
address
The address of a CVB. If no address is supplied, then all volumes are displayed.
/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.
The SHOW VOLUME command shows state information and statistics about all volumes mounted on the system.
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:
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
The user-written module is only supported when written in HP C (minimum
Version 5.2), following the pattern of the example extension,
MBX$SDA.C. It should be compiled and linked using commands of the
following form:
$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)
|
1. You can include the qualifier /INSTRUCTION=NOFLOAT on the compile command line if floating-point instructions are not needed. 2. The + ALPHA$LIBRARY:SYS$LIB_C /LIBRARY is not needed on the compile command line if the logical name DECC$TEXT_LIBRARY is defined and translates to ALPHA$LIBRARY:SYS$LIB_C.TLB. 3. If the user-written extension needs to signal SDA condition codes, or output their text with $PUTMSG, you should add the qualifier /INCLUDE=SDAMSG to the parameter ALPHA$LIBRARY:VMS$VOLATILE_PRIVATE_INTERFACES /LIBRARY . |
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:
int sda$extend_version = SDA_FLAGS$K_VERSION;
|
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:
| Line of Code | Meaning | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| transfer_table | Address of the vector table in the base image. The user-written routine SDA$EXTEND must copy this to SDA$EXTEND_VECTOR_TABLE_ADDR before any SDA routines can be called. | ||||||||||||||
| cmd_line | Address of the descriptor of the command line as entered by the user, less the name of the extension. So, if you enter "SDA> MBX" or "SDA> DO MBX", the command line is a zero length string. If you enter the command "SDA> MBX 80102030", the command line is " 80102030" (the separating space is not stripped). | ||||||||||||||
| sda_flags |
Definition for the following four bits in this structure:
|
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:
You can establish this condition handler as follows:
lib$establish (sda$cond_handler);
|
The error condition, signal array, and register dump are output directly to SYS$OUTPUT and/or SYS$ERROR, and are not affected by the use of the SDA commands SET OUTPUT and SET LOG. |
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:
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:
The full list of available routines is as follows:
| SDA$ADD_SYMBOL | SDA$GET_LINE_COUNT |
| SDA$ALLOCATE | SDA$GETMEM |
| SDA$DBG_IMAGE_INFO | SDA$INSTRUCTION_DECODE |
| SDA$DEALLOCATE | SDA$NEWPAGE |
| SDA$DISPLAY_HELP | SDA$PARSE_COMMAND |
| SDA$ENSURE | SDA$PRINT |
| SDA$FAO | SDA$READ_SYMFILE |
| SDA$FORMAT | SDA$REQMEM |
| SDA$FORMAT_HEADING | SDA$SET_ADDRESS |
| SDA$GET_ADDRESS | SDA$SET_CPU |
| SDA$GET_BLOCK_NAME | SDA$SET_HEADING_ROUTINE |
| SDA$GET_BUGCHECK_MSG | SDA$SET_LINE_COUNT |
| SDA$GET_CURRENT_CPU | SDA$SET_PROCESS |
| SDA$GET_CURRENT_PCB | SDA$SKIP_LINES |
| SDA$GET_DEVICE_NAME | SDA$SYMBOL_VALUE |
| SDA$GET_HEADER | SDA$SYMBOLIZE |
| SDA$GET_HW_NAME | SDA$TRYMEM |
| SDA$GET_IMAGE_OFFSET | SDA$TYPE |
| SDA$GET_INPUT | SDA$VALIDATE_QUEUE |
The details of all these routines follow. But there are some points to be aware of in using them:
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.
| Previous | Next | Contents | Index |