crash(1M) DG/UX R4.11MU05 crash(1M)
NAME
crash - examine system images
SYNOPSIS
crash [-p] [-l log] [-d dump] [-n kernel] [[dump] kernel]
where:
log The pathname to a file for logging crash input and
output.
dump The name of a file to used as a memory image. This
file can be a memory dump generated by a previous
system halt, or /dev/mem. For crash to be able to
examine the dump, you must have permission to read the
dump file.
kernel The name of a kernel file, the file containing the
executable kernel image used to produce the dump file,
and the symbol table mapping symbolic names to their
addresses in the kernel address space. For crash to be
able to examine the dump, you must have permission to
read the kernel file.
DESCRIPTION
The crash interactive utility allows analysis of a kernel image,
dump, or running system. It can display system data structures, look
at logical and physical memory, and perform miscellaneous functions
that are useful for debugging DG/UX system kernels. Options are:
-p The file specified as the kernel is not an executable, but a
data file in some arbitrary format. The dump file is ignored
with this option.
-l log Log all input and output to the specified log file.
-d dump
An alternate to specifying the dump file as a command
argument. If this option is used, you may not also specify a
dump command argument.
-n kernel
An alternate to specifying the kernel file as a command
argument. If this option is used, no (non-option) command
arguments are allowed, and the dump file (if present) must be
specified with -d.
If a kernel file is specified without specifying a dump file, no dump
file will be used, and memory will be read from the boot-time memory
image contained in the kernel file. If you have permission to write
the kernel file, this mode can be used to patch it.
If a dump file is specified without specifying a kernel file, the
default kernel file is /dgux.
If neither the kernel file nor the dump file are specified on the
command line, a dump file of /dev/mem and a kernel file of /dgux will
be used as defaults.
Terminology
The following terms are used in this document:
Running system
A system in normal operation. crash may be used to analyze
this system by specifying /dev/mem as the dump file.
Using /dev/mem to examine a running system requires special
privilege. On traditional DG/UX systems, the required
privilege is granted only if your effective user ID is 0
(root). On systems with DG/UX information security, /dev/mem
does not exist, and it is not possible to examine a running
system.
Address translation
The process of converting a logical address to a physical
address. To examine the data at a logical address, crash must
translate the address, and then examine the physical address.
The data at a logical address cannot be examined by crash if
it is not present in physical memory.
VP A virtual processor. A VP contains the necessary information
to allow a thread of control to run on a physical processor.
Certain data are associated with a VP, including a call stack,
and a user address space. For more details on VP data, see
Using the DG/UX Kernel Debugger.
JP Job processor. This is a physical processor which can be
assigned to run a virtual processor
Current JP
The last JP selected by a focus command. For more on how the
current JP is determined, see Using the DG/UX Kernel Debugger.
View PC
This is the default memory location for most commands that
examine or modify memory. This location is changed by certain
commands: view, up, and down.
Command Summary
Once crash has started, you enter a crash command line interpreter.
crash has four categories of commands: memory/symbol, general,
debugger, and support. Following is a summary of these commands by
category. Some commands have alternate short command names, which
are shown in parentheses.
Memory and Symbol Commands
These commands let you read a program's symbol table or display its
memory. 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
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.
trace (tr)
Trace the call chain in a VP's stack.
register (reg)
Display the contents of the general registers.
ltop Translate a logical to a physical address.
status Display the status of the physical processors.
vp Describe a virtual processor
focus (fo)
Select the address space of a given process
Support Commands
These commands control the crash program itself.
quit (q) Exit from crash.
src Read commands and macros from a file.
Command Entry
Each crash command is discussed below in this man page. 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 The current job (physical) processor number
program_name The name of the currently focused process
vp The virtual processor id of the currently focused
process
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] [mem_addr [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 suppresses the implicit
address translation normally done for all memory
commands.
-u Specify that the memory address is in user space,
not kernel space. This option is ignored if it is
used with -p.
-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
while printing memory locations.
mem_addr An expression specifying the starting address in memory to
be examined; the default is the current view pc.
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.
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.
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
on platforms with variable length instructions (such as Intel based
systems) this can affect the content of the next instruction.
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 expression. 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 kernel symbol table. If a relevant 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 [regular_expression... ]
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 [ 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.
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 category. 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]
Debugger Commands
trace: Trace Back through a VP's Stack
The trace command will display a traceback of a VP's call 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 [vp_id... ]
register: Display the Value of General Registers
The register (or reg) command with no arguments displays the values
of all available processor registers for the currently focused VP.
With one argument (a valid register name), reg displays the value of
the indicated register only. The available registers and their names
depend on the architecture of the DG/UX system image being examined.
On 88k systems, the available registers are the general purpose
registers r0-r31. The register is named by using the letter 'r'
followed by the register's number.
On Intel systems, any of the 8 32-bit general purpose registers may
be named: eax, ebx, ecx, edx, esi, edi, ebp, esp. Other registers
are also available: the six segment registers cs, ss, ds, es, fs, and
gs, eip and eflags, the control registers cr0 and cr3, the debug
registers dr0, dr1, dr2, dr3, dr6, and dr7, and the task register,
tr.
ltop: Convert a logical address to a physical address
The ltop command translates the given logical address to its physical
address and prints the result. The address space is assumed to be
the one currently bound by the focus command.
status: Display DG/UX System Information
The status command displays useful information about the DG/UX system
processors. The syntax for this command is as follows:
status
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 [vp_id...]
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 its vp id.
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 [vp_id]
Support Commands
quit: Exit from crash
The quit (or q or bye) command is used to exit crash. The syntax for
this command is as follows:
quit
log: change logging
With no command arguments, this command prints the name of the
current logfile. With the single argument off, this command stops
logging of crash input and output, but leaves the log file name
unchanged. With the single argument on, this command resumes logging
to the current logfile. With the argument on followed by a command
name, this command resumes logging to the specified file, and changes
the logfile name to match the new file. The initial logfile (if any)
is set by the -l option. The syntax for this command is as follows:
log [ on [logfile] | off]
src: Execute an External Macro File
The src command takes a file pathname 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.
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.
% Read the 8-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:
Debugger symbol values crash has a number of built-in variables.
These include '.' (the current view pc), and
names of registers printed by the register
command. A complete list of these variables
appears in Using the DG/UX Kernel Debugger.
User-defined values These are variables assigned by the global and
set commands.
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 the default
radix.
FILES
/dev/mem Default memory dump file
/dgux Default kernel file
SEE ALSO
crash (8).
Using the DG/UX Kernel Debugger.
Licensed material--property of copyright holder(s)