An SDA symbol can represent several value types. It can represent
a constant, a data address, a procedure or function descriptor
address, or a routine address. Constants are usually offsets of
a particular field in a data structure; however, they can also
represent constant values such as the BUG$_xxx symbols.
Symbols are composed of up to 31 letters and numbers, and can
include the dollar sign ($) and underscore (_) characters. When
you invoke SDA, it reads in the global symbols from the symbols
table section of SYS$BASE_IMAGE.EXE, and from REQSYSDEF.STB, a
required subset of the symbols in the file SYSDEF.STB. You can
add other symbols to SDA's symbol table by using the DEFINE and
READ commands.
All address symbols identify memory locations. SDA generally
does not distinguish among different types of address symbols.
However, for a symbol identified as the name of a procedure
descriptor, SDA takes an additional step of creating an
associated symbol to name the code entry point address of the
procedure. It forms the code entry point symbol name by appending
_C to the name of the procedure descriptor.
Also, SDA substitutes the code entry point symbol name for the
procedure descriptor symbol when you enter the following command:
SDA> EXAMINE/INSTRUCTION procedure-descriptor
For example, enter the following command:
SDA> EXAMINE/INSTRUCTION SCH$QAST
SDA displays the following information:
SCH$QAST_C: SUBQ SP,#X40,SP
Now enter the EXAMINE command but do not specify the /INSTRUCTION
qualifier, as follows:
SDA> EXAMINE SCH$QAST
SDA displays the following information:
SCH$QAST: 0000002C.00003009 ".0..,..."
This display shows the contents of the first two longwords of the
procedure descriptor.
Note that there are no routine address symbols on Alpha systems,
except for those in MACRO-64 assembly language modules.
Therefore, SDA creates a routine address symbol for every
procedure descriptor it has in its symbol table. The new symbol
name is the same as for the procedure descriptor except that it
has an _C appended to the end of the name.
1 – Sources of Symbols
SDA obtains its information from the following:
o Images (.EXE files)
o Image symbol table files (.STB files)
o Object files
SDA also defines symbols to access registers and to access common
data structures.
The only images with symbols are shareable images and executive
images. These images contain only universal symbols, such as
constants and addresses.
The image symbol table files are produced by the linker with the
/SYMBOLS qualifier. These files normally contain only universal
symbols, as do the executable images. However, if the SYMBOL_
TABLE=GLOBALS linker option is specified, the .STB file also
contains all global symbols defined in the image. See the OpenVMS
Linker Utility Manual for more information.
Symbols can include lowercase letters. Commands that manipulate
symbols (such as DEFINE, SHOW SYMBOL, and UNDEFINE) require these
symbols to be enclosed within quotation marks ("symbol" ).
Some SDA commands predefine additional symbols. This includes
SET CPU and SET PROCESS (as shown in the following subtopics) and
also SHOW DEVICE and SHOW CLUSTER.
1.1 – Modules Containing Symbols
Object files can contain global constant values. An object
file used with SDA typically contains symbol definitions for
data structure fields. Such an object file can be generated by
compiling a MACRO-32 source module that invokes specific macros.
The macros, which are typically defined in SYS$LIBRARY:LIB.MLB
or STARLET.MLB, define symbols that correspond to data structure
field offsets. The macro $UCBDEF, for example, defines offsets
for fields within a unit control block (UCB). OpenVMS Alpha
and Integrity servers provide several such object modules in
SDA$READ_DIR, as listed in the following table. For compatibility
with OpenVMS VAX, the modules' file types have been renamed to
.STB.
File Contents
DCLDEF.STB Symbols for the DCL interpreter
DECDTMDEF.STB Symbols for transaction processing
GLXDEF.STB Symbols for OpenVMS Galaxy data
structures
IMGDEF.STB Symbols for the image activator
IODEF.STB I/O database structure symbols
NETDEF.STB Symbols for DECnet data structures
REQSYSDEF.STB Required symbols for SDA
RMSDEF.STB Symbols that define RMS internal and
user data structures and RMS$_xxx
completion codes
SCSDEF.STB Symbols that define data structures for
system communications services
SYSDEF.STB Symbols that define system data
structures, including the I/O database
TCPIP$NET_GLOBALS.STB* Data structure definitions for TCP/IP
internet driver, execlet, and ACP data
structures
TCPIP$NFS_GLOBALS.STB* Data structure definitions for TCP/IP
NFS server
TCPIP$PROXY_GLOBALS.STB* Data structure definitions for TCP/IP
proxy execlet
TCPIP$PWIP_GLOBALS.STB* Data structure definitions for TCP/IP
PWIP driver, and ACP data structures
TCPIP$TN_GLOBALS.STB* Data structure definitions for TCP/IP
TELNET/RLOGIN server driver data
structures
* The TCPIP$*.STB files are available only if TCP/IP has been
installed. These files are found in SYS$SYSTEM, so that all files
are not automatically read in when you issue a READ/EXEC command.
1.2 – Symbols Defined on Initialization
The following table lists symbols that SDA defines automatically
on initialization.
ASN Address space number
AST Both the asynchronous system trap status
and enable registers: AST<3:0> = AST enable;
AST<7:4> = AST status
BR0 through BR7 Branch registers (Integrity servers only)
CYCLE_COUNTER Process cycle counter
ESP Executive stack pointer
EBSP Executive register stack pointer (Integrity
servers only)
FEN Floating-point enable
FP Frame pointer (R29)
FP0 through FP31 Floating-point registers (Alpha only)
FP0 through FP127 Floating point registers (Integrity servers
only)
FPCR Floating-point control register (Alpha only)
FPSR Floating-point status register (Integrity
servers only)
GP Global pointer (R1) (Integrity servers only)
G FFFFFFFF.80000000(16), the base address of
system space
H 00000000.7FFE0000(16), a base address in P1
space
I FFFFFFFF.FFFFFFFF(16), also fills the leading
digits of a hexadecimal number with the value
of F
KSP Kernel stack pointer
KBSP Kernel register stack pointer (Integrity
servers only)
PAL_RSVD PAL reserved area in process HWPCB
PC Program counter
PCC Process cycle counter
PS Processor status
PTBR Page table base register
R0 through R31 Integer registers (Alpha only)
R0 through R127 Integer registers (Integrity servers only)
SCC System cycle counter
SP Current stack pointer of a process
SSP Supervisor stack pointer
SBSP Supervisor register stack pointer (Integrity
servers only)
SYSPTBR Page table base register for system space
USP User stack pointer
UBSP User register stack pointer (Integrity servers
only)
VIRBND Virtual Address Boundary for RADs (Alpha only)
1.3 – Symbols Defined by SET CPU
After a SET CPU command is issued (for analyzing a crash dump
only), the symbols defined in the following table are set for
that CPU.
CPUDB Address of CPU database
IPL Interrupt priority level register
MCES Machine check error summary register
PCBB Process context block base register
PRBR Processor base register (CPU database address)
RAD Address of RAD database
SCBB System control block base register
SISR Software interrupt status register
VPTB Virtual Page Table Base register
1.4 – Symbols Defined by SET PROCESS
After a SET PROCESS command is issued, the symbols listed in the
following table are defined for that process.
ARB Address of access rights block
FRED Address of floating-point register and execution data
block
JIB Address of job information block
KTB Address of the kernel thread block
ORB Address of object rights block
PCB Address of process control block
PHD Address of process header
PSB Address of persona security block
2 – Initialization of Symbols
On initialization, SDA reads the universal symbols defined by
SYS$BASE_IMAGE.EXE. For every procedure descriptor address symbol
found, a routine address symbol is created (with _C appended to
the symbol name).
SDA then reads the object file REQSYSDEF.STB. This file contains
data structure definitions that are required for SDA to run
correctly. It uses these symbols to access some of the data
structures in the crash dump file or on the running system.
Finally, SDA initializes the process registers defined in the
SET PROCESS command and executes a SET CPU command, defining the
symbols as well.
3 – Using Symbols
There are two major uses of the address type symbols. First,
the EXAMINE command employs them to find the value of a known
symbol. For example, EXAMINE CTL$GL_PCB finds the PCB for the
current process. Then, certain SDA commands (such as EXAMINE,
SHOW STACK, and FORMAT) use them to symbolize addresses when
generating output.
When the code for one of these commands needs a symbol for an
address, it calls the SDA symbolize routine. The symbolize
routine tries to find the symbol in the symbol table whose
address is closest to, but not greater than the requested
address. This means, for any given address, the routine may
return a symbol of the form symbol_name+offset. If, however,
the offset is greater than 0FFF(16), it fails to find a symbol
for the address.
As a last resort, the symbolize routine checks to see if this
address falls within a known memory range. Currently, the only
known memory ranges are those used by the OpenVMS executive
images and those used by active images in a process. SDA searches
through the executive loaded image list (LDRIMG data structure)
and activated image list (IMCB data structures) to see if the
address falls within any of the image sections. If SDA does find
a match, it returns one of the following types of symbols:
executive_image_name+offset
activated_image_name+offset
The offset is the same as the image offset as defined in the map
file.
The constants in the SDA symbol table are usually used to display
a data structure with the FORMAT command. For example, the PHD
offsets are defined in SYSDEF.STB; you can display all the fields
of the PHD by entering the following commands:
SDA> READ SDA$READ_DIR:SYSDEF.STB
SDA> FORMAT/TYPE=PHD phd_address
4 – Address Resolution with Symbols
In OpenVMS, executive and user images are loaded into dynamically
assigned address space. To help you associate a particular
virtual address with the image whose code has been loaded at
that address, SDA provides several features:
o The SHOW EXECUTIVE command
o The symbolization of addresses, described in the Using_Symbols
help topic
o The READ command
o The SHOW PROCESS command with the /IMAGES qualifier
o The MAP command
The OpenVMS executive consists of two base images, SYS$BASE_
IMAGE.EXE and SYS$PUBLIC_VECTORS.EXE, and a number of other
separately loadable images. Some of these images are loaded on
all systems, while others support features unique to particular
system configurations. Executive images are mapped into system
space during system initialization.
By default, a typical executive image is not mapped at contiguous
virtual addresses. Instead, its nonpageable image sections
are loaded into a reserved set of pages with other executive
images' nonpageable sections. The pageable sections of a typical
executive image are mapped contiguously into a different part
of system space. An image mapped in this manner is said to be
sliced. A particular system may have system parameters defined
that disable executive image slicing altogether.
Each executive image is described by a data structure called a
loadable image data block (LDRIMG). The LDRIMG specifies whether
the image has been sliced. If the image is sliced, the LDRIMG
indicates the beginning of each image section and the size of
each section. All the LDRIMGs are linked together in a list that
SDA scans to determine what images have been loaded and into
what addresses they have been mapped. The SHOW EXECUTIVE command
displays a list of all images that are included in the OpenVMS
executive.
Each executive image is a shareable image whose universal
symbols are defined in the SYS$BASE_IMAGE.EXE symbol vector.
On initialization, SDA reads this symbol vector and adds its
universal symbols to the SDA symbol table.
Executive image .STB files define additional symbols within
an executive image that are not defined as universal symbols
and thus are not in the SYS$BASE_IMAGE.EXE symbol vector. You
can enter a READ/EXECUTIVE command to read symbols defined in
all executive image .STB files into the SDA symbol table, or a
READ/IMAGE filespec command to read the .STB for a specified
image only.
To obtain a display of all images mapped within a process,
execute a SHOW PROCESS/IMAGE command. See the description of the
SHOW PROCESS command for additional information about displaying
the hardware and software context of a process.
You can also identify the image name and offset that correspond
to a specified address with the MAP command. With the information
obtained from the MAP command, you can then examine the image
map to locate the source module and program section offset
corresponding to an address.