The ARM Windowing Debugger (armwd) [PC and SunOS only]
------------------------------------------------------


About the ARM Windowing Debugger
................................

<armwd> can be used to debug programs assembled by <armasm> (the ARM 
Assembler), or compiled by <armcc> (the ARM C Compiler), if those programs have 
been produced with debugging 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 Evaluation (PIE) card, or with 
the software only ARM instruction set emulator which is built into <armwd>.

The PC version 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 version 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.


Command Line Options
....................

Invoke <armwd> using the command:

    armwd {<options>} <image-name> {<arguments>}

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;

    -Big        Specify that memory should be big endian;

    -SErial     Specify that <armwd> should act as a front end to the PIE Card 
                (-SErial and -Armul are mutually exclusive);

    -Armul      Specify that <armwd> should act as a front end to ARMulator (
                -SErial and -Armul are mutually exclusive);

    -Port n     This option may only be specified if -SErial is being used.  n 
                specifies whether the first or second serial port should be 
                used;

    -LINEspeed nThis 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> command line for convenience.  See "<The ARM 
Tool Reconfiguration Utility (reconfig)>" for details.


armsd 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. Similarly, when the debug monitor (<demon>) is 
reset, it operates 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:

 *  under SunOS: 38400 baud;

 *  under PC/DOS: 19200 baud.

 *  under Macintosh: 19200 baud.

This can be re-configured after installation using the <reconfig> Utility (see 
"<The ARM Tool Reconfiguration Utility (reconfig)>").


armwd User Interface Issues
...........................

The following points should be noted by <armwd> users, as they may not at first 
be obvious:

 *  There are several types of "cursor" used by <armwd>:

    The mouse pointer cursor - this is used solely to indicate where mouse 
    clicks will be 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.

    Breakpoint markers, red blocks.  These indicate where breakpoints have been 
    set.

    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.

 *  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.

 *  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.

 *  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 double 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.

 *  When resizing or moving a window around the screen, no "elastic banding" is 
    used to give feedback.  When moving a window, the titlebar merely changes 
    colour, and when resizing a window the resize icon changes colour.

 *  The menu bar can be activated from the keyboard using the Alt key, the 
    cursor keys and the Return key, in a manner very similar to most DOS text 
    mode applications.  This is the case for <armwd> under both X Windows and 
    DOS.

 *  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 forward from the current cursor 
position.  Therefore if you want to search the whole of a window the cursor 
should 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 displays C source only, or 
interleaved C source and disassembled 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 operations may be performed 
on its contents:

 *  Double Click on left hand pane - pops up a window which shows the type of 
    the variable under the cursor.

 *  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).

 *  'w' sets a watchpoint on the variable under the cursor.

 *  'u' unsets a watchpoint on the variable under the cursor.


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 operations may be performed 
on its contents:

 *  Double Click on left hand pane - pops up a window which shows the type of 
    the variable under the cursor.

 *  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).

 *  'w' sets a watchpoint on the variable under the cursor.

 *  'u' unsets a watchpoint on the variable under the cursor.


View : View Expression (Ctrl E)

This allows an expression to be entered which will be displayed, and updated 
whenever execution stops or is interrupted.  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 following operations may be 
performed:

 *  'u' - unsets the search path under the cursor.

 *  'm' - allows a search path to be modified (in case it was previously 
    mistyped).

A new search path can be added by using the Add Search 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 currently loaded image.  When the Function 
Names Window has the input focus the following operations may be performed on 
it:

 *  Double Clicking on a function name will attempt to open a Source Window 
    with a view of the desired function.

 *  'b' sets a breakpoint on entry to the function under the cursor.

 *  'u' unsets a breakpoint on entry to the function under the cursor.

 *  'm' modifies or allows creation of a complex breakpoint 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 current stack backtrace.  
When the Backtrace Window has the input focus the following operations may be 
performed on it:

 *  Double Clicking on a backtrace entry will attempt to open a Source Window 
    or Disassembly Window with a view of the appropriate code.

 *  'b' sets a breakpoint at the code at the backtrace entry under the cursor.

 *  'u' unsets a breakpoint at the code at the backtrace entry under the 
    cursor.

 *  'm' modifies or allows creation of a complex breakpoint at the code at the 
    backtrace entry under 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 Window.

When a Memory Window has the input focus the following operations may be 
performed on it:

 *  Double Clicking or pressing 'm' over an entry allows the contents of that 
    memory address  to be modified.

 *  'w' sets a watchpoint on the memory address under the cursor.

 *  '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 Disassembly 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 Disassembly Window.

When a Disassembly Window has the input focus the following operations may be 
performed on it:

 *  'b' sets a breakpoint on the instruction under the cursor.

 *  'u' unsets a breakpoint on the instruction under the cursor.

 *  'm' modifies or allows creation of a complex breakpoint 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.

When the Low Level Symbols Window has the input focus the following operations 
may be performed on it:

 *  Double Clicking on the left hand pane opens a Memory Window centred on the 
    appropriate address.

 *  Double Clicking on the right hand pane opens a Source Window or a 
    Disassembly Window centred on the appropriate code, depending on whether 
    the symbol refers to an area of C code or not.

 *  'b' sets a breakpoint on the code at the location under the cursor.

 *  'u' unsets a breakpoint on the code at the location under the cursor.

 *  'm' modifies or allows creation of a complex breakpoint on the code at the 
    location under the cursor.  For details of complex breakpoints see "<Setting 
    Complex 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 
performed on it:

 *  Double Clicking on the right hand pane opens a Source Window or a 
    Disassembly Window centred on the appropriate code, depending on whether 
    the breakpoint refers to an area of C code or not.

 *  'u' unsets the breakpoint under the cursor.

 *  '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 
watchpoint under the cursor.


View : Console

This opens the Console Window, which contains the output from the image being 
debugged.  While the debugger is executing the currently loaded image, the 
heading of the Console Window changes to "Active Console Window".  In addition, 
if the image halts requiring input from the user, then the Console Window is 
given the input focus and 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 Status 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 pressing '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 
                <$statistics_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.


Registers : User Regs (F5)

This opens the User Registers Window, which shows the contents 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:

 *  Double Clicking on the left hand pane allows the contents of the register 
    under the cursor to be modified.

 *  Double Clicking on the right hand pane opens a Memory Window centred on the 
    contents of the register under the cursor.

 *  'm' allows the contents of the register under the cursor 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 operations 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.


Execute : Go (F8)

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 disassembly 
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 page38.

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 individual 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.

As with Set Breakpoint, not all windows are suitable for 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 currently 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 Variable 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 operations may be performed on a Source Window with the input 
focus:

 *  'b' sets a breakpoint at the location under the cursor.

 *  'u' unsets a breakpoint at the location under the cursor.

 *  'm' modifies or allows creation of a complex breakpoint at the location 
    under the cursor.  For details of complex breakpoints see "<Setting Complex 
    Breakpoints>".

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 operations 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
    F9      Step
    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

 

 

