crash(1M) DG/UX 4.30 crash(1M)
NAME
crash - examine system images
SYNOPSIS
crash [-l log_file] [ image_file ] [ symbol_table_file ]
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. The arguments to crash are:
-l log_file This option causes crash to log all
input and output to the specified
log_file.
-p This option causes all addresses to be
physical rather than logical.
image_file The name of a file to used as a memory
image. This file may 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.
symbol_table_file The name of a file containing the
executable system image used to produce
the memory image file; /dgux is the
default.
COMMANDS
Once crash has started, you enter a crash command line
interpreter. Crash has four sets of commands:
memory/symbol, general, debugger and support.
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:
od Display memory
ow View or modify memory
os Memory search
Licensed material--property of copyright holder(s) Page 1
crash(1M) DG/UX 4.30 crash(1M)
rs Regular expression search
pd Pattern dump
vi View memory in code format
do View down
up View up
ts Translate an expression value to a symbol
nm Print symbol table entry
ust Change the symbol table
General Commands
The general commands are:
eval Evaluate expressions
print Print values
mode Change the radix of numeric output
global Create a 32-bit variable to be used in an
expression
alias Assign an alias to a command
func Define a function used in an expression
macro Define a macro
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.
break Set breakpoints
delete Delete breakpoints
proceed Proceed with execution of the kernel
trace Trace back through a process's stack
Licensed material--property of copyright holder(s) Page 2
crash(1M) DG/UX 4.30 crash(1M)
reg Display the contents of the general registers
ctl Display the contents of the control registers
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 Descibe a virtual processor
fo Look at the address space of a given process
halt Halt the system
Support Commands
These commands control the crash program itself.
quit Exit 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:program_name:vp]
Where:
jp is the current job processor number.
program_name is the name of the currently focused process.
vp is the virtual processor number of the currently focused
process.
Crash supports a help facility that you invoke with the help
command.
Licensed material--property of copyright holder(s) Page 3
crash(1M) DG/UX 4.30 crash(1M)
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 system dump is a physical memory dump created by
running the system shutdown code.
Running system
A running system is a system in normal operation. Crash
may be used to analyze this system by reading physical
memory from /dev/mem.
Address translation
Address translation is the process of converting a
logical address to a physical address.
Slot Number
Many structures are referenced by their index into an
array. This index is called a slot number. For example,
processes are referenced by their index into the
process table, not their process id.
VP A VP is 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 (od, ow, os, rs,
pd and vi) have a common format. Rather than restate this
format for each command, we describe it below. (Note: This
is the general format. Defaults and arguments definitions
may differ between commands. See each command for details.)
The format is:
command [options] [memory_address] [count] [format]
command Specify the name of the command to be
used.
[options] Options are given after the command name
and are preceded with a dash.
[memory_address] The memory address is the starting address
Licensed material--property of copyright holder(s) Page 4
crash(1M) DG/UX 4.30 crash(1M)
to be examined. The memory address is
given as an expression. This argument is
optional. If not given, the default is the
current view_pc.
[count] The count argument determines how many
elements are to be operated on. This
argument is optional. If not given, the
default is determined by the command
itself.
[format] The format argument describes the format
of the elements to be examined. This
argument is optional. If not given, the
default is determined by the command
itself.
The options for the memory commands must be preceded with a
dash. Multiple options may be grouped into one string with
a preceding dash. The memory command options are:
p The p option specifies that the memory address
is a physical address, not a logical address.
This means the read or write physical routine
will be called directly to read or write data.
v The v option is the verify option for the octal
write command. See the octal write command for
more information.
n The n option turns off converting labels to
their symbolic form during printing memory
locations.
Formats
The formats supported for the memory commands are described
below.
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).
Licensed material--property of copyright holder(s) Page 5
crash(1M) DG/UX 4.30 crash(1M)
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.
hex The memory location is a 32-bit hex value.
Aliases for octal 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.
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.
od: Display Memory Dump
The od 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 longoct and the default count is 1.
ow: View and modify memory
The ow 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 longoct and the default count is infinite.
Octal 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
Licensed material--property of copyright holder(s) Page 6
crash(1M) DG/UX 4.30 crash(1M)
responses are listed below.
q Exit octal write.
^ 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 again, 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.
os: Memory Search
The os 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 infinite and the default format is longoct. 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.
rs: Regular Expression Search
The rs command is essentially the result of taking the
output of an od command and piping the output through a
regular expression search. You will be prompted for the
search value. All command line arguments are identical to
that of od.
pd: Pattern Dump
The command name for the pattern dump command is pd. The
pattern dump has a similar interface to the od 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 od 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.
Licensed material--property of copyright holder(s) Page 7
crash(1M) DG/UX 4.30 crash(1M)
vi: View Memory in Code Format
The vi command is similar to the octal dump 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.
do: View Down
The do (view down) 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:
nm [regular_expression]
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 symbol cannot be found, the value is
converted to an octal string. The resulting string is then
printed. The syntax for this command is as follows:
up
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:
ts [expression]
ust: Change the Symbol Table
The ust command allows you to redefine the current symbol
table. Filename is the name of a program image containing a
symbol table. The syntax for this command is as follows:
ust filename
Licensed material--property of copyright holder(s) Page 8
crash(1M) DG/UX 4.30 crash(1M)
GENERAL COMMANDS
eval: Evaluate Expressions
The eval 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 for
this command 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.
The syntax for this command is as follows:
mode [oct | dec | hex]
global
The syntax for the global command follows:
global [ global_name ] [ expression ]
or
global -d [ global_name ...]
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 global_name is
not given, the current list of global_names 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.
alias
The syntax for the alias command follows:
alias [ alias_name ] [ alias_value ]
or
alias -d [ alias_name ...]
With the alias command, you can assign an alias to any
Licensed material--property of copyright holder(s) Page 9
crash(1M) DG/UX 4.30 crash(1M)
command supported by this system. The alias_value will
replace an occurrence of the alias_name at the beginning of
a command line. The alias feature is not recursive. If the
alias command is given alone, all of the current aliases
will be printed. You can delete an alias with the -d
option.
func
The syntax for the func command follows:
func [ function_name ] [ function_expression ]
or
func -d [ functionname ...]
You use the func command to define a function for use with
an expression. The function_name is the name used in an
expression, and the function_expression is an expression to
be evaluated when used in an expression. A function that
contains a reference to itself will cause the parser to loop
infinitely. You can delete a function with the -d option.
macro
The macro command has the following syntax:
macro [-d] name macro_contents
The macro command allows the creation of a macro that may be
executed as if it were a command with no arguments. When
creating a macro, the macro_contents are read until a blank
line is received. If no arguments are given, the current
macros are displayed. The -d option is used to delete a
macro.
set
The syntax for the set command follows:
set [ global_name ] [ 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 [command_name]
Licensed material--property of copyright holder(s) Page 10
crash(1M) DG/UX 4.30 crash(1M)
DEBUGGER COMMANDS
break: Set or List Breakpoints
The break command is used to set and list breakpoints in the
kernel debugger. Since crash can not be run on live
kernels, its break command is a no-op.
delete: Delete Breakpoints
The delete command is used to delete breakpoints in the
kernel debugger. Since crash can not be run on live
kernels, its delete command is a no-op.
proceed: Proceed from a Breakpoint
The break command is used to continue execution from a
breakpoint kernel debugger. Since crash can not be run on
live kernels, its proceed command is a no-op.
trace: Trace Back through a Process's Stack
The trace command will display a traceback of a process's
kernel and/or user stack. If a process index is not given,
the currently bound process will be traced. If a process
index is given, that process will be traced. The syntax for
this command is as follows:
trace [options] [process_index]
reg: Display the Value of a General Register
The 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.
ctl: Display the Value of a Control Register
The 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 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:
Licensed material--property of copyright holder(s) Page 11
crash(1M) DG/UX 4.30 crash(1M)
stat
vp: Describe a VP
The vp command displays the state of the specified virtual
processor state block. If no vp_id is given, states for all
of the VP state blocks will be displayed. The syntax for
this command is as follows:
vp [vp_id]
fo: Look at the Address Space of a Given Process
The 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] [process_index]
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 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 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.
Licensed material--property of copyright holder(s) Page 12
crash(1M) DG/UX 4.30 crash(1M)
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.
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.
The values used in the expression come from:
Symbol table values.
Integers.
Expression evaluations.
Addresses.
Symbols are resolved in the order listed as follows:
User-defined symbols
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.
Global variables
The user sets up the values of a global variable.
Function values
These values are the result of a function used in an
expression.
Symbol table values
Licensed material--property of copyright holder(s) Page 13
crash(1M) DG/UX 4.30 crash(1M)
These values are symbols in the symbol table of the
program.
Hex symbols
If a symbol cannot be resolved, it is assumed to be a
hex number. If this assumption is wrong, the symbol is
rejected.
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).
Licensed material--property of copyright holder(s) Page 14