The ARM Windowing Debugger
armwd
AVAILABILITY
The ARM Windowing Debugger (armwd) is only available on
the SunOS and PC releases.
SYNOPSIS
armwd [options] [imagename [arguments]]
DESCRIPTION
armwd can be used to debug programs assembled by armasm
(the ARM Assembler), or compiled by armcc (the ARM C Com-
piler), if those programs have been produced with debug-
ging enabled. A limited amount of debugging information
can be produced at link time, even if the object code
being linked was not compiled with debugging enabled.
armwd is normally used to run ARM Image Format images.
See "The ARM C Compiler (armcc)", "The ARM Assembler
(armasm)" and "The ARM Linker (armlink)" starting on page
19 for more information on the generation of debugging
data. armwd can be used with a Platform Independent Eval-
uation (PIE) card, or with the software only ARM instruc-
tion set emulator which is built into armwd. The PC ver-
sion of armwd runs under DOS, in a 80 column, 50 row text
only mode, and like the other ARM development tools
requires an i386 or better.
The SunOS version of armwd is a direct port of the PC ver-
sion to SunOS, and does not make use of X Windows in the
normal way - there is just one armwd X Window, which is
treated by armwd as the whole screen. X Windows users may
find the DOS-like interface under SunOS a little different
to other X Windows applications.
OPTIONS
The options are listed below. Upper case is used to show
the allowable abbreviations.
-Size n
Specify the minimum memory size required for the
image being debugged. n may be prefixed by 0x for
hex values, and suffixed with either K or M to
specify KB or MB respectively. It should be noted
that whether this option actually does anything or
not is dependent on the user supplied memory model
linked in with armsd. For more information about
these see "Memory Models" of the Reference Manual.
-Little
Specify that memory should be little endian;
Specify that armwd should act as a front end to the
PIE Card (-SErial and -Armul are mutually exclu-
sive);
-Armul Specify that armwd should act as a front end to
ARMulator ( -SErial and -Armul are mutually exclu-
sive);
-Port n
This option may only be specified if -SErial is
being used. n specifies whether the first or sec-
ond serial port should be used;
-LINEspeed n
This option is only significant if -SErial is being
used. n specifies the linespeed for communication
through the serial port; only the values 9600,
19200 and 38400 are permitted.
Note that many of these options can be configured as the
default, so that they can be omitted from the armwd com-
mand line for convenience. See "The ARM Tool Reconfigura-
tion Utility (reconfig)" for details.
Armwd Line-Speed Negotiation
armwd will attempt to operate at the configured line speed
(9600, 19200 or 38400 baud).
When first invoked, and whenever it detects that the
debugee has been reset, armwd operates at 9600 baud. Simi-
larly, when the debug monitor (demon) is reset, it oper-
ates at 9600 baud. One of armwd's first acts after reset
is to send a request to the debug monitor (at 9600 baud)
to start operating at the configured (higher) line rate.
The default configured line speed for armwd is:
o under SunOS: 38400 baud;
o under PC/DOS: 19200 baud.
o under Macintosh: 19200 baud.
This can be re-configured after installation using the
reconfig Utility (see "The ARM Tool Reconfiguration Util-
ity (reconfig)").
armwd User Interface Issues
The following points should be noted by armwd users, as
they may not at first be obvious:
o There are several types of "cursor" used by armwd:
directed. Moving the mouse pointer cursor does
not affect the input focus or where keypresses
are directed. The execution cursor, a green
block. This is used to show where the current
execution position is.
o Breakpoint markers, red blocks. These indicate
where breakpoints have been set.
o The input cursor, a brown block. This is the
cursor which can be moved around by arrow keys,
page up, page down, home and end keys, and
clicking in other places within the window with
the input focus. It is this cursor which many
of the menu items refer to. There is at most
one of these at any time, and that one will
always be in the window with the current input
focus. If no window has the input focus, then
there will be no input cursor
o Input focus is indicated by a bright white title
bar. Keystrokes are directed to the window with
the input focus, although the menu bar will catch
short cut keystrokes.
o Opening a window which is already open (unless it
is a window type which may have multiple views,
eg. Memory Windows, Source Windows, Variable Type
Windows) will bring that window to the front -
often useful if the desired window is currently
hidden behind other windows.
o Double clicking is different to most windowing
systems in that any amount of delay between the
two clicks is acceptable. However, if the mouse
pointer moves between two clicks then they are not
considered a double click. In practice this works
as expected. Some visual feedback is given to
indicate whether a second click will cause a dou-
ble click or not - the line clicked on turns light
blue after the first click, and goes back to its
previous colour if the mouse moves or a second
click is made.
o When resizing or moving a window around the
screen, no "elastic banding" is used to give feed-
back. When moving a window, the titlebar merely
changes colour, and when resizing a window the
resize icon changes colour.
o The menu bar can be activated from the keyboard
using the Alt key, the cursor keys and the Return
under both X Windows and DOS.
o Dialog boxes can be used from both the mouse and
the keyboard using the following keys:
TAB moves to the next input field;
Left and right arrows move around a text field;
Return is equivalent to clicking on OK;
Escape is equivalent to clicking on Cancel.
armwd Menu Items
In this section menu items are specified in the form:
menubar entry: pull down menu entry [(keyboard short cut)]
The menu item is then followed by a description of that
menu item and, if applicable, the operations which can be
performed on the opened object.
File: About armwd
This gives the version number of your copy of armwd. This
should be included in any reports or feedback about armwd.
File: Load File
This allows a different image file to be loaded, and for
command line arguments for this image to specified. armwd
will look for the image relative to the current directory
unless a full pathname is given.
File: Exit
This ends the current armwd debugging session.
Window: Back
This sends the window with the input focus to the back of
the windows on the screen.
Window: Front
This brings the window with the input focus to the front
of the windows on the screen.
Window: Close
This closes the window with the input focus. Note that
the execution window cannot be closed.
Window: Search (F2)
This allows the window with the input focus to be searched
for various expressions. Note that the search is always
be taken to the start of the window (typically by pressing
Home).
The Search dialog box gives a list of special characters
which can be used in the search expression.
Window: Search Repeat (F3)
This allows the last successful search to be repeated,
again forward from the cursor position. The search is
performed in the window with the input focus, so if this
has changed since the last search then the search will be
in a different window.
Window: Goto Source Line (F4)
The window with the input focus is scrolled to display the
requested line of source code.
This option can only be used on Source windows and the
Execution window, if it is displaying source code.
Window: Toggle Interleaving (F7)
This toggles whether the window with the input focus dis-
plays C source only, or interleaved C source and disassem-
bled machine instructions.
This option can only be used on Source windows and the
Execution window, if it is displaying source code.
View: Local Variables (Ctrl L)
This pops up the Local Variables window, which shows the
variables local to the current context and their current
values.
When this window has the input focus the following opera-
tions may be performed on its contents:
o Double Click on left hand pane - pops up a window
which shows the type of the variable under the cursor.
o Double Click on right hand pane - pops up a window
which shows the contents of the variable under the
cursor if it is of a pointer type or array (the value
shown in the Local Variables Window in these cases is
the pointer rather than its contents).
o 'w' sets a watchpoint on the variable under the cur-
sor.
View: Global Variables (Ctrl G)
This pops up the Global Variables window, which shows the
global variables defined in the currently loaded image
together with their current values.
When this window has the input focus the following opera-
tions may be performed on its contents:
o Double Click on left hand pane - pops up a window
which shows the type of the variable under the cursor.
o Double Click on right hand pane - pops up a window
which shows the contents of the variable under the
cursor if it is of a pointer type or array (the value
shown in the Global Variables Window in these cases is
the pointer rather than its contents).
o 'w' sets a watchpoint on the variable under the cur-
sor.
o 'u' unsets a watchpoint on the variable under the cur-
sor.
View: View Expression (Ctrl E)
This allows an expression to be entered which will be dis-
played, and updated whenever execution stops or is inter-
rupted. The expression may include both high level and
low level symbols, eg. both C variable names and register
names.
For full details on the naming of variables in contexts
other than the current one see "Accessing Variables" of
the section on armsd. When the Expression Window has the
input focus 'u' can be used to remove an expression from
those being displayed.
View: Search Paths (Ctrl P)
This opens the Search Path Window, which displays the
search paths (other than the current directory) which
armwd will use to look for source files.
When the Search Path Window has the input focus the fol-
lowing operations may be performed:
o 'u' - unsets the search path under the cursor.
o 'm' - allows a search path to be modified (in case it
was previously mistyped).
Path menu item.
View: Source Files (Ctrl F)
This opens the Source Files Window which displays the
source files armwd knows about from which the currently
loaded image is derived.
When the Source Files Window has the input focus double
clicking on one of its entries will open a view of that
source file.
View: Function Names (Ctrl N)
This opens the Function Names Window, which displays the
names of all function which armwd knows about in the cur-
rently loaded image. When the Function Names Window has
the input focus the following operations may be performed
on it:
o Double Clicking on a function name will attempt to
open a Source Window with a view of the desired func-
tion.
o 'b' sets a breakpoint on entry to the function under
the cursor.
o 'u' unsets a breakpoint on entry to the function under
the cursor.
o 'm' modifies or allows creation of a complex break-
point on entry to the function under the cursor. For
details of complex breakpoints see "Setting Complex
Breakpoints".
View: Backtrace (Ctrl T)
This opens the Backtrace Window, which displays the cur-
rent stack backtrace. When the Backtrace Window has the
input focus the following operations may be performed on
it:
o Double Clicking on a backtrace entry will attempt to
open a Source Window or Disassembly Window with a view
of the appropriate code.
o 'b' sets a breakpoint at the code at the backtrace
entry under the cursor.
o 'u' unsets a breakpoint at the code at the backtrace
entry under the cursor.
the cursor. For details of complex breakpoints see "
Setting Complex Breakpoints".
View: Memory (Ctrl M)
This requests an address on which to centre a new Memory
Window. Each Memory Window gives a view of a 64Kb section
of memory centred on the initially requested address.
Note that performing a search in a Memory Window will only
search in the area of memory viewable by that Memory Win-
dow. When a Memory Window has the input focus the follow-
ing operations may be performed on it:
o Double Clicking or pressing 'm' over an entry allows
the contents of that memory address to be modified.
o 'w' sets a watchpoint on the memory address under the
cursor.
o 'u' unsets a watchpoint on the memory address under
the cursor.
View: Disassembly (Ctrl D)
This requests an address on which to centre a new Disas-
sembly Window. Each Disassembly Window gives a view of a
64Kb section of memory centred on the initially requested
address.
Note that performing a search in a Disassembly Window will
only search in the area of memory viewable by that Disas-
sembly Window.
When a Disassembly Window has the input focus the follow-
ing operations may be performed on it:
o 'b' sets a breakpoint on the instruction under the
cursor.
o 'u' unsets a breakpoint on the instruction under the
cursor.
o 'm' modifies or allows creation of a complex break-
point on the instruction under the cursor. For
details of complex breakpoints see "Setting Complex
Breakpoints".
View: Low Level Symbols (Ctrl Z)
This opens the Low Level Symbols Window, which displays
the low level symbols saved by the linker.
following operations may be performed on it:
o Double Clicking on the left hand pane opens a Memory
Window centred on the appropriate address.
o Double Clicking on the right hand pane opens a Source
Window or a Disassembly Window centred on the appro-
priate code, depending on whether the symbol refers to
an area of C code or not.
o 'b' sets a breakpoint on the code at the location
under the cursor.
o 'u' unsets a breakpoint on the code at the location
under the cursor.
o 'm' modifies or allows creation of a complex break-
point on the code at the location under the cursor.
For details of complex breakpoints see "Setting Com-
plex Breakpoints".
View: Breakpoints (Ctrl B)
This opens the Breakpoints Window, which displays all the
currently set breakpoints. When the Breakpoints Window
has the input focus the following operations may be per-
formed on it:
o Double Clicking on the right hand pane opens a Source
Window or a Disassembly Window centred on the appro-
priate code, depending on whether the breakpoint
refers to an area of C code or not.
o 'u' unsets the breakpoint under the cursor.
o 'm' modifies the breakpoint under the cursor. For
details of complex breakpoints see "Setting Complex
Breakpoints".
View: Watchpoints (Ctrl W)
This opens the Watchpoints Window, which displays all the
currently set watchpoints. When the Watchpoints Window
has the input focus 'u' may be pressed to unset the watch-
point under the cursor.
View: Console
This opens the Console Window, which contains the output
from the image being debugged. While the debugger is exe-
cuting the currently loaded image, the heading of the Con-
sole Window changes to "Active Console Window". In addi-
brought to the front. The Console Window is backed by a
limited buffer, and when this becomes full the top section
of the Console Window's contents are discarded.
View: RDI Protocol Log
This opens the RDI Protocol Log Window. The RDI Protocol
Log Window is in many ways similar to the Console Window,
except that it holds the RDI Protocol Log if this has been
enabled.
Such logging can be set using the Set RDI Log Level menu
item, see "Options: Set RDI Log Level".
View: Status Bar
This creates the Status Bar, which holds information about
what armwd is doing or has just finished doing.
For example while the image file is being loaded the Sta-
tus Bar will contain a "loading" message; when the current
image is being executed an "Executing" message will be
shown.
View: Debugger Internals
This opens the Debugger Internals Window, which shows the
following armwd variables, which may be modifed by press-
ing 'm' when the Debugger Internals Window as the input
focus.
vector_catch
specifies which vectors are trapped and which are
ignored, in the same way as $vector_catch under
armsd.
statistics, statistics_inc
these are the same as $statistics and $statis-
tics_inc under armsd. The values can be seen by
double clicking on the right hand pane, which will
open a
window holding the statistics.
cmdline
this is the command line for the currently loaded
image, specified either on the armwd command line
or by the Load File menu item.
rdi_log
this is the RDI Protocol Log level, which can also
be modified by using the Set RDI Protocol Log Level
menu item.
This opens the User Registers Window, which shows the con-
tents of the user mode registers, including the cpsr.
When the User Registers Window has the input focus the
following operations may be performed on it:
o Double Clicking on the left hand pane allows the con-
tents of the register under the cursor to be modified.
o Double Clicking on the right hand pane opens a Memory
Window centred on the contents of the register under
the cursor.
o 'm' allows the contents of the register under the cur-
sor to be modified.
Registers: Fiq Regs
Registers: Irq Regs
Registers: Svc Regs
Registers: Abort Regs
Registers: Undef Regs
These menu items open the register windows for other banks
of registers. These register windows allow the same oper-
ations as the User Registers Window.
Registers: FP Regs (F6)
Registers: Raw FP Regs
These menu items open windows showing the contents of the
ARM floating point registers in a floating point number
format and a binary format respectively.
When these windows have the input focus the contents of a
floating point register can be modified by either double
clicking on the left hand pane or pressing 'm' with the
cursor over the register to be modified, and a watchpoint
can be set on the register under the cursor by pressing
'w'.
Registers: CoPro15 Regs
Registers: Raw CoPro15 Regs
These menu items open windows showing the contents of Co-
processor 15 registers.
When these windows have the input focus the contents of a
co-processor 15 register can be modified by either double
clicking on the left hand pane or pressing 'm' with the
cursor over the register to be modified.
This tells armwd to execute the image from the current
execution position. Execution will continue until either
a breakpoint or watchpoint is encountered, the program
terminates or execution is interrupted with Ctrl C.
Execute: Step (F9)
This tells armwd to execute "one step". If the execution
position is in an area of code displayed as either disas-
sembly only or interleaved disassembly and C source then
"one step" will be one instruction.
If the execution position is in a section of non-
interleaved C source then "one step" is considered as one
C statement.
Note that Step considers calling a function or at the
instruction level, executing a a subroutine using BL to be
"one step", and will therefore execute the whole of the
function call before stopping.
Execute: Step In (F10)
This tells armwd to execute "one step", but considering a
function call or branch and link instruction as "one
step". Thus Step In will execute only the function entry
sequence (or branch and link instruction) returning with
the new execution position inside the function.
Execute: Set Breakpoint
This menu item will allow a complex breakpoint to be set
at the position under the cursor in the window with the
input focus.
For details of complex breakpoints see "Setting Complex
Breakpoints" starting on page 38 of the User Manual.
Note that not all windows are suitable for use of this
menu item, eg. setting a breakpoint in the Console Window
has no meaning.
It is also possible to set breakpoints without using this
menu item, by pressing 'b' in many windows. See individ-
ual window descriptions for details.
Execute: Set Watchpoint
This menu item will allow a watchpoint to be set at the
position under the cursor in the window with the input
focus.
the use of Set Watchpoint. It is also possible to set
watchpoints without using this menu item, by pressing 'w'
in many windows. See individual window descriptions for
details.
Execute: Current Context (Ctrl X)
This menu item scrolls the execution window so that it is
centred around the current execution position. This is
most useful after having scrolled around in the Execution
Window looking at other sections of code.
Options: Set RDI Log Level
This allows the RDI Log Level to be set. The default when
armwd is started up is 0, which produces no output in the
RDI Protocol Log Window.
Options: Add Search Path (Ctrl A)
This allows a search path to be added to those used by
armwd to search for source files. The search paths cur-
rently used can be viewed by the View Search Paths menu
item, see "View: Search Paths (Ctrl P)".
Other Windows and Dialog Boxes
Variable Structure Windows
These display the contents of a pointer type variable, and
are obtained by double clicking on the right hand pane of
either the Global Variables Window or the Local Variables
Window. Double clicking on the right hand pane of a Vari-
able Structure Window will open another Variable Structure
Window if the object under the cursor is of a pointer
type. If the object is an integer then a Memory Window
centred on the address under the cursor will be openned.
Variable Type Windows
These display the type of a variable, and are obtained by
double clicking on the left hand pane of either the Global
Variables Window or the Local Variables Window.
Source Windows
These provide a view of a source file, and can be obtained
in several ways, eg. double clicking in the Source Files
Window or the Function Names Window. The following opera-
tions may be performed on a Source Window with the input
focus:
o 'b' sets a breakpoint at the location under the cur-
sor.
o 'm' modifies or allows creation of a complex break-
point at the location under the cursor. For details
of complex breakpoints see "Setting Complex Break-
points".
Additionally the menu item Toggle Interleaving can be used
to allow the C source and a disassembly of instructions to
be displayed interleaved.
The Execution Window
This window is always present, but can change between
being a Disassembly Window and a Source Window, depending
on whether there is high level debugging information
relevent to the current execution position. The opera-
tions which can be performed on the Execution Window
depend on which mode it is in. For details see Source
Windows reference and Disassembly Window Reference.
Setting Complex Breakpoints
Complex breakpoints can be set in a variety of ways,
although all will produce the dialog box which comes up
when the Set Breakpoint menu item is used. Only the
"Expression" field and the "Count out of" fields may be
modified. If the expression field is not empty then the
breakpoint will only halt execution if the expression
evaluates to a non zero value.
The "Count out of" field can be used to stop execution
only after a breakpoint has been passed a specific number
of times.
Key Shortcuts
F1
F2 Search
F3 Search Repeat
F4 Goto Source Line
F5 View User Registers
F6 View FP Registers
F7 Toggle Interleaving
F8 Go
F10 Step In
^A Add Search Path
^B View Breakpoints
^C Interrupt Execution
^D View Disassembly
^E View Expression
^F View Source Files
^G View Global Variables
^L View Local Variables
^M View Memory
^N View Function Names
^P View Search Paths
^T View Backtrace
^W View Watchpoints
^X Show Current Context
^Z View Low Level Symbols
SEE ALSO
reconfig(1), armsd(1)
Reference Manual, User Manual