crash(1M) DG/UX 5.4R3.00 crash(1M)
NAME
crash - examine system images
SYNOPSIS
crash [-p] [-l logfile] [ imagefile ] [ symtabfile ]
where:
logfile The pathname of a file for logging crash input and
output.
imagefile The name of a file to used as a memory image. This
file can be a system image, memory dump, or /dev/mem.
You must have read permissions for the file (so for
/dev/mem, you must be superuser). If the file is an
executable (system file), the symbol table may be taken
from this file.
symtabfile The name of a symbol table file, a file containing the
executable system image used to produce the memory
image file; /dgux is the default.
DESCRIPTION
The crash interactive utility (located in /usr/bin) allows analysis
of a system image, dump, or a running system. It can display system
databases, look at logical memory, and perform miscellaneous
functions that are useful for inspecting a memory dump. Options are:
-p Read all data directly from the image file; do not use the
symbol table file to read kernel code and read-only data.
-l Log all input and output to the specified log file.
Command Summary
Once crash has started, you enter a crash command line interpreter.
Crash has four sets of commands: memory/symbol, general, debugger,
and support. Following is a summary of these commands by category;
alternate short command names are listed where they exist:
Memory and Symbol Commands
These commands let you read a program's symbol table or display its
memory. In addition, there are several expression evaluation
commands that let you compute the values of octal or hexadecimal
expressions. The memory and symbol commands are:
memread (mr)
Read and display memory
memwrite (mw)
View or modify memory
memsearch (ms)
Search memory
regsearch (rs)
Regular expression search
patdump (pd)
Pattern dump
Licensed material--property of copyright holder(s) 1
crash(1M) DG/UX 5.4R3.00 crash(1M)
view (vi) View memory in code format
down (do) View down
up View up
translate (ts)
Translate an expression value to a symbol
name (nm) Print symbol table entry
General Commands
The general commands are:
eval (ev) Evaluate expressions
print Print values - unformatted
printf Print values - formatted
mode Change the radix of numeric output
global Create a 32-bit variable to be used in an expression
set Set a global variable to the value of an expression
help Print help information (?)
Debugger Commands
These commands report and control the state of the hardware and the
kernel execution. (Command abbreviations appear in parentheses.)
brk Set breakpoints (b, bp, br)
delete Delete breakpoints (d)
proceed Proceed with execution of the kernel (p)
trace Trace back through a VP's stack (tr)
register Display the contents of the general registers (reg)
control Display the contents of the control registers (ctl)
cmmu Display the contents of the cache and memory
management unit
ltop Translate a logical to a physical address
status Display the status of a physical processor
vp Describe a virtual processor
focus Look at the address space of a given process (fo)
halt Halt the system
Support Commands
These commands control the crash program itself.
quit Exit from crash
fh Print program information from the file header
x Execute a file containing crash commands
Each command is discussed in this man page. However, in general the
syntax of crash commands is of the form:
command [ options ] [ arguments ]
Each command must be on one line terminated by a newline, carriage
return, form-feed, or null character. The prompt for crash is
[jp:programname:vp]
where:
Licensed material--property of copyright holder(s) 2
crash(1M) DG/UX 5.4R3.00 crash(1M)
jp The current job processor number
programname The name of the currently focused process
vp The virtual processor number of the currently focused
process
Crash supports a help facility that you invoke with the help command.
Terminology
The following terms are used in this document:
System image file The DG/UX System bootable image, normally called
dgux. This image file contains the code for the
system and the symbol table. A system image is
required to execute crash.
System dump A physical memory dump created by running the
system shutdown code.
Running system A system in normal operation. crash may be used
to analyze this system by reading physical memory
from /dev/mem.
Address translation The process of converting a logical address to a
physical address.
Slot number An index by which many structures are referenced
into an array. For example, processes are
referenced by their index, not their process id,
into the process table.
VP A virtual processor. A VP contains the necessary
information to allow a process to run on a
processor. There are a limited number of VPs in
a system.
Memory and Symbol Commands
These commands allow you to display symbol table data and program
memory. All of the memory commands (mr, mw, ms, rs, pd, and vi) have
a common syntax. Rather than restate this syntax for each command,
we describe it below. (Note: This is the general syntax. Defaults
and arguments definitions may differ between commands. See each
command for details.) The syntax is:
command [options] [memaddr] [count] [format]
where:
command The name of the command to be used
options One or more of the following options (multiple options may
be grouped into one string with a preceding dash):
-p Interpret the memory address as a physical address,
not a logical address. This means the read or write
Licensed material--property of copyright holder(s) 3
crash(1M) DG/UX 5.4R3.00 crash(1M)
physical routine will be called directly to read or
write data.
-u Specify that the memory address is in user space,
not kernel space.
-ln Specify that n elements can be printed across a
line.
-v Verify; see the the memwrite command description
below.
n Turn off converting labels to their symbolic form
during printing memory locations.
memaddr An expression specifying the starting address in memory to
be examined; the default is the current viewpc.
count How many elements are to be operated on; the default is
determined by the command itself.
format The format of the elements to be examined; the default is
determined by the command itself.
Formats
The formats supported for the memory commands are as follows:
decimal The memory location is a 16-bit decimal value. Aliases
for decimal are dec and d.
octal The memory location is a 16-bit octal value. Aliases for
octal are oct and o.
character The memory location is an 8-bit character value. Aliases
for character are char and c.
i The memory location is the start of an instruction.
b The memory location is an 8-bit value in the default
radix (octal, decimal, or hexadecimal). Set the default
radix with the mode command.
ld The memory location is a 32-bit decimal value.
lo The memory location is a 32-bit octal value.
lh The memory location is a 32-bit hexadecimal value.
hex The memory location is a 32-bit hex value. Aliases for
hex are h and x.
s The memory location is a 16-bit value in the default
radix (octal, decimal, or hexadecimal). Set the default
radix with the mode command.
Licensed material--property of copyright holder(s) 4
crash(1M) DG/UX 5.4R3.00 crash(1M)
l The memory location is a 32-bit value in the default
radix (octal, decimal, or hexadecimal). Set the default
radix with the mode command.
ssym The memory location is a 16-bit symbolic value.
sym The memory location is a 32-bit symbolic value.
str The memory location is the start of a string, terminated
by a null.
pte The memory location is a page table entry.
def If no format is specified, the default format is used.
Each memory command has its own real default format.
The memory reference commands are listed below.
memread: Display Memory
The memread (or mr) command displays memory starting at the memory
address, in the given format, for the specified number of elements.
The number of elements displayed per line depends on the format
selected. The current memory address is displayed at the beginning
of the line. The default format is long and the default count is 1.
memwrite: View and modify memory
The memwrite (or mw) command allows the user both to view and modify
memory locations one at a time. The modification starts at the
memory address. It will continue until either count elements have
been displayed or a q has been entered. Memory elements must be
modified in the format specified. The default format is long and the
default count is 1.
Memory write displays the element at the memory address in the format
specified followed by a right angle bracket (>). You may then enter
a response to that value. The valid responses are listed below.
q Exit memwrite.
^ Leave this location untouched, but display the previous
element for modification.
NL,CR Leave this location untouched, but display the next
element for modification.
expression Resolve the expression, expecting the format specified and
write the results into the memory location. If the verify
flag is set, redisplay this element, otherwise display the
next element for modification.
In short, you are allowed to scan through memory modifying it
selectively. Please note that modifying instructions is allowed, but
this may affect the content of the next instruction.
Licensed material--property of copyright holder(s) 5
crash(1M) DG/UX 5.4R3.00 crash(1M)
memsearch: Search Memory
The memsearch (or ms) command searches through memory for a given
value in a given format. The search starts at memory address and
continues for a maximum of count elements. The default count is 1
and the default format is long. You will be prompted for the search
value. You must enter the search value in the format specified. If
a value matching the search value is found, a view (see view command)
is performed at the location where the match occurred.
regsearch: Regular Expression Search
The regsearch (or rs) command is essentially the result of piping the
output of an mr command through a regular expression filter. You
will be prompted for the search value. All command line arguments
are identical to that of mr.
patdump: Pattern Dump
The patdump (or pd) command has a similar interface to the mr
command. The pd command takes a regular expression rather than an
expression for the memory address. It then searches the symbol table
for all matches to the regular expression. When found, the mr
command is called using the arguments to the pd command with the
symbol found replacing the regular expression. This command allow
the user to look at a group of locations that can be described with a
regular expression. This is useful for dumping a set of meters,
counts, etc., that have a similar name.
view: View Memory in Code Format
The view (or vi) command is similar to the memread command, but it
displays elements in a different format. The view command is used to
display the element at the memory address surrounded by six elements
on either side of the memory address. This is useful when looking at
code in instruction mode and wanting to see the neighboring
instructions. The default format is instruction mode. The count
argument is not used and may be ignored. The default memory address
is the view_pc. If a memory_address is given to the view command,
that memory address becomes the new view_pc.
down: View Down
The down (or do) command increments the view_pc such that sequential
executions of this command will produce a continuous listing of
elements. The syntax for this command is as follows:
down
up: View Up
The up (view up) command decrements the view_pc such that sequential
executions of this command will produce a continuous listing of
elements. The syntax for this command is as follows:
up
ts: Translate an Expression Value to a Symbol
The ts command evaluates the expression given and converts it to a
symbolic value using the current set of symbol tables. If a relevant
Licensed material--property of copyright holder(s) 6
crash(1M) DG/UX 5.4R3.00 crash(1M)
symbol cannot be found, the value is converted based on the current
radix. The resulting string is then printed. The syntax for this
command is as follows:
ts [expression]
nm: Print Symbol Table Entry
The nm command searches the symbol table for a match to the regular
expression given. If a match is found, the symbol is printed along
with its value and symbol type. The syntax for this command is as
follows:
nm [regularexpression]
General Commands
eval: Evaluate Expressions
The eval (or ev) command evaluates the expression given and prints
the result in octal, decimal, and symbol formats. The syntax for
this command is as follows:
eval [expression]
print: Print Values
The print command evaluates the contents of the memory address or
user-defined variable, and prints the value of the contents in the
current output radix. The syntax is as follows:
print [expression]
mode: Set Default Radix
The mode command sets the default radix (octal, decimal, hexadecimal)
for the short and long memory command options, and turns editread
(er) on or off. The syntax is as follows:
mode [oct|dec|hex] [er {on|off}]
global
The syntax for the global command follows:
global [ globalname ] [ expression ]
or
global -d [ globalname ...]
The global command enables you to create a 32-bit variable that can
be used in expressions. This allows you to save values for later
use. A global variable will override the evaluation of a symbol of
the same name. If a globalname is not given, the current list of
globalnames with their values is printed. You can initialize the
global variable to a value by specifying an expression as the second
argument. Global variables can be deleted with the -d option.
set
The syntax for the set command follows:
Licensed material--property of copyright holder(s) 7
crash(1M) DG/UX 5.4R3.00 crash(1M)
set [ globalname ] [ expression ]
The set command allows you to set a global variable to the evaluation
of an expression.
help
The help command prints help information about a command. If the
help command is invoked with no arguments, the list of supported
commands is printed separated by subsystem. If a command name is
given, the help string associated with that command is printed. The
syntax for this command is as follows:
help [commandname]
Debugger Commands
b: Set or List Breakpoints
The brk command (same as b, br or bp) is used to set and list
breakpoints in the kernel debugger. Since crash cannot be run on
live kernels, its brk command is a no-op.
delete: Delete Breakpoints
The delete command is used to delete breakpoints in the kernel
debugger. Since crash cannot be run on live kernels, its delete
command is a no-op.
proceed: Proceed from a Breakpoint
The b command is used to continue execution from a breakpoint kernel
debugger. Since crash cannot be run on live kernels, its proceed
command is a no-op.
trace: Trace Back through a VP's Stack
The trace command will display a traceback of a VP's kernel stack.
If a vp id is not given, the currently focused VP will be traced. If
a vp id is given, that VP will be traced. The syntax for this
command is as follows:
trace [options] [vpid]
register: Display the Value of a General Register
The register (or reg) command with no arguments displays the values
of all 32 general registers. With one argument (either an integer in
the range 0-31, or the letter "r" followed by such an integer), reg
displays the value of the indicated register only.
control: Display the Value of a Control Register
The control (or ctl) command with no arguments displays the values of
all 19 control registers. With one argument (either the letters "cr"
followed by such an integer in the range 2 through 20 or the mnemonic
name of a control register), ctl displays the value of the indicated
register only.
cmmu: Display the Contents of the CMMUs
The cmmu command causes the contents of the 88200 Cache and Memory
Licensed material--property of copyright holder(s) 8
crash(1M) DG/UX 5.4R3.00 crash(1M)
Management Units to be displayed, if they are available.
ltop: Convert a logical address to a physical address
The ltop command converts the given logical address to a physical
address and prints the result. The address space is assumed to be
the one currently bound.
status: Display DG/UX System Information
The stat command displays useful information about the DG/UX system.
The syntax for this command is as follows:
stat
vp: Describe a VP
The vp command displays the state of the specified virtual processor.
If no vp_id is given, states for all of the VPs in the system will be
displayed. The syntax for this command is as follows:
vp [vpid...]
Each status line lists the VP's id, its command name, its reason for
stopping, its state in the medium term scheduler (MTS), its transient
and process handles, and the PID of the process which owns the VP. A
detailed explanation of this data can be found in Using the DG/UX
Kernel Debugger.
focus: Look at the Address Space of a Given Process
The focus (or fo) command allows the user to look at the address
space of the given process. The process is selected by process
index. This allows the user to look at the per-process and user
state of that process. The syntax for this command is as follows:
focus [options] [processindex]
halt: Halt the System
The halt command takes no arguments and is used in the kernel
debugger to halt system execution and return to the SCM. Since crash
can not be run on live kernels, its halt command is equivalent to
quit and will cause the crash program to terminate.
Support Commands
quit: Exit from crash
The quit command is used to exit the program. This command will call
the exit(2) system call with a 0 status code. The syntax for this
command is as follows:
quit
fh: Print File Header Information
The fh command prints information obtained from the file header of
the kernel being debugged. It takes no arguments.
x: Execute an External Macro File
The x command takes a UNIX filename as an argument. It reads the
Licensed material--property of copyright holder(s) 9
crash(1M) DG/UX 5.4R3.00 crash(1M)
contents of that file one line at a time, executing each line as if
it were a command line typed into crash.
Expressions
This section describes valid expressions. An expression cannot
contain any white space. The expression is an arithmetic expression
that results in one value. The elements of the expression are
symbols, integers, the value of memory locations, binary operators,
and unary operators. Parentheses can be used.
The binary operators perform an operation on two values. For example
v1 op v2. The valid binary operators are:
+ Add v1 and v2.
- Subtract v2 from v1.
* Multiply v1 by v2.
/ Divide v1 by v2.
& Logical and.
| Logical or.
> 1 if v1 > v2 and 0 if v1 <= v2.
>= 1 if v1 >= v2 and 0 if v1 < v2.
< 1 if v1 < v2 and 0 if v1 >= v2.
<= 1 if v1 <= v2 and 0 if v1 > v2.
= 1 if v1 = v2 and 0 if v1 != v2.
The unary operators perform an operation on a single value. For
example op v1. The valid unary operators are:
# Read the 32-bit value at the address v1.
@ Read the 16-bit value at the address v1.
! Logical NOT.
: Translate user space address to kernel space address.
The values used in the expression come from:
Symbol table values.
Integers.
Expression evaluations.
Addresses.
Symbols are resolved in the order listed as follows:
Licensed material--property of copyright holder(s) 10
crash(1M) DG/UX 5.4R3.00 crash(1M)
Debugger symbol values These can be system constants or even machine
state. The user sets up the definition of
these symbols of the expression evaluation
routines. For the 88k debugger, the 32
general-purpose registers r0-r31 and the
control registers are available for use in
expressions.
User-defined values The user sets up the values of a global
variable.
Kernel symbol values Kernel symbols correspond to the names of C
language routines, functions, and global
variables in the kernel code.
Integers These are integer constants in either decimal,
octal, or hex representation.
Expression evaluations
FILES
/dev/mem Default system image file
/dgux Default namelist file
SEE ALSO
crash (8).
Using the DG/UX Kernel Debugger.
Licensed material--property of copyright holder(s) 11