armsd Command Language
======================


Introduction
------------

This chapter describes the commands available under the command line based 
version of <armsd>.  For information on how to invoke <armsd> see section "<The 
ARM Assembler (armasm)>".  For details of how to produce 
images with suitable debugging data see the chapters on <armasm>, <armcc> and 
<armlink>.  Examples which demonstrate running programs under the command line 
based <armsd> are given in the Cookbook.

Command syntax patterns are given throughout to show you what you should type 
to achieve an effect. These are shown in a typewriter font. Plain text in this 
form should be typed in as it is; <oblique> text represents an item such as a 
filename or variable name - you should replace this with the name of your file, 
variable etc. Items in curly brackets are optional; the curly brackets are used 
for clarity and should not be typed. A star (*) following a set of curly 
brackets means that the items in those braces can be repeated as many times as 
required in that command. Note that many command names can be abbreviated; the 
braces here show what can be left out.

In one case curly brackets are required by <armsd> and these are depicted in 
the syntax pattern by curly brackets enclosed in quote marks.


Specifying Source Level Objects
-------------------------------


Variable Names and Context
..........................

It is often sufficient to refer to variables by their names in the original 
source code. To print the value of <variable>, simply type:

    print <variable>

With structured high-level languages, variables defined in the current context 
can be accessed by giving their names. Other variables should be preceded by 
the context (eg function name) in which they are defined; this will also give 
access to variables which are not visible to the executing program at the point 
at which they are being examined. The syntax in this case is:

    <procedure>:<variable>

Global variables can be referenced by qualifying them with the module or file 
name. If this is likely to lead to any ambiguity, because the module name is 
the same as a procedure name, for example, prefix the file or module name with 
#. The syntax in this case is:

    <#module>:<variable>

If a variable is declared more than once within the same procedure, resolve the 
ambiguity by qualifying the reference with the line number in which the 
variable is declared as well as, or instead of, the function name, ie.:

    #<module>:<procedure>:<line-no>:<variable>

To pick out a particular activation of a repeated or recursive function call, 
prefix <variable> with a backslash (\) followed by an integer. Use 1 for the 
first activation, 2 for the second and so on. A negative number will look 
backwards through activations of the function, starting with \-1 for the 
previous one. If no number is specified and multiple activations of a function 
are present, <armsd> will always look at the most recent activation. The way to 
refer to <variable> within a particular activation of a function is:

    <procedure>\{-}<activation-number>:<variable>

The complete syntax for the various ways of expressing context is:

    {#}<module>{{:<procedure>}* {\{-}<activation-number>}}
    {#}<procedure>{{:<procedure>}* {\{-}<activation-number>}}
    #

The complete syntax for specifying a variable name is:

    {<context>:{<line-number>:}}<variable>

Despite the syntax of variables and contexts being complex, in practice the 
various syntax extensions needed to differentiate between different objects 
rarely have to be used together.


Program Locations
.................

Some <armsd> commands require arguments which refer to locations in the 
program. You can refer to a place in the program by procedure entry/exit, line 
number, statement within a line, or label. Program line numbers can be 
qualified in the same way as variable names, for example:

    #<module>:123
    <procedure>:3

Using a procedure name alone sets a breakpoint (see section "<Break>" starting 
on page95) at the entry point of that procedure. To set a breakpoint at the end 
of a procedure, just before it returns, use the syntax:

    <procedure>:$exit

To refer to a statement within a line, use the line number followed by the 
number of the statement within the line, in the form:

    <line-number>.<statement-number>

So, for example, 100.3 refers to the third statement in line 100.

Line numbers can sometimes be ambiguous, notably when a file is included within 
a function. To resolve any ambiguities, add the name of the file or module in 
which the line you want occurs in parentheses. The syntax is:

    <number>(<filename>)

C labels are simple identifiers and so can be used as they are for reference 
purposes.

In addition to the high-level program locations described here, low level 
locations can also be specified. See section "<Low Level Symbols>" starting on 
page98 for further details.


Expressions
...........

Some <armsd> commands require <expressions> as arguments. Their syntax is based 
on C.

A full set of operators is available. In descending order of precedence these 
are:

    Precedence    Operator    Purpose                 Syntax
    1             ()          Grouping                a * (b + c)
                  []          Subscript               isprime[n]
                  .           Record selection        rec.field,a.b.c
                  ->          Indirect selection      rec->next
                              (in fact rec->next is identical to (*rec).next)
    2             !           Logical NOT             !finished
                  ~           Bitwise NOT             ~mask
                  -           Unary minus             -a
                  *           Indirection             *ptr
                  &           Address                 &var
    3             *           Multiplication          a * b
                  /           Division                a / b
                  %           Integer remainder       a % b
    4             +           Addition                a + b
                  -           Subtraction             a - b
    5             >>          Right shift             a >> 2
                  <<          Left shift              a >> 2
    6             <           Less than               a < b
                  >           Greater than            a > b
                  <=          Less than or equal      a <= b
                  >=          Greater than or equal   a >= b
    7             ==          Equal                   a == 0
                  !=          Not equal               a != 0
    8             &           Bitwise AND             a & b
    9             ^           Bitwise EOR             a ^ b
    10            |           Bitwise OR              a | b
    11            &&          Logical AND             a && b
    12            ||          Logical OR              a || b

The lower the number, the higher the precedence of the operator. 

Subscripting can only be applied to pointers and array names. <armsd> will 
check both the number of subscripts and their bounds in languages which support 
such checking. Out-of-bound array accesses will be warned against. As in C, the 
name of an array may be used without subscripting to yield the address of the 
first element.

The prefix indirection operator * is used to dereference pointer values, in the 
same way as Pascal's postfix operator ^. If <ptr> is a pointer, <*ptr> will 
yield the object to which it points.

If the lefthand operand of a right shift is a signed variable, the shift is an 
arithmetic one and the sign bit is preserved. If the operand is unsigned, the 
shift is a logical one and zero is shifted into the most significant bit.


Constants
.........

Constants may be decimal integers, floating point numbers, octal integers or 
hexadecimal integers. Note that '1' is an integer whereas '1.' is a floating 
point number.

Character constants are also allowed. For example 'A' yields 65, the ASCII code 
for 'A'.


Names Used in Syntax Descriptions
.................................

The following terms are used throughout the following sections within the 
syntax descriptions for each command.

<context> is the activation state of the program as described above in "
<Variable Names and Context>". 

<expression> is an arbitrary expression using constants, variables and the 
operators described in "<Expressions>".

<location> is a location within the program as described in "<Program Locations>
".

<variable> is a reference to one of the program's variables. Use the simple 
variable name to look at a variable in the current context, or add more 
information as described in "<Variable Names and Context>", 
to see the variable elsewhere in the program.

<format> is a C printf function format descriptor, or one of the words <hex>, 
<ascii> or <string>. Some common descriptors are listed below.

    Type          Format      Description
    int           %d          Signed decimal integer (default for integers)
                  %u          Unsigned integer
                  %x          Hexadecimal (lower case letters) - same as hex
    char          %c          Character - same as ascii
    char *        %s          Pointer to character - same as string
    void *        %p          Pointer (same as %.8x), eg. 00018abc
    float         %e          Exponent notation, eg. 9.999999e+00
                  %f          Fixed point notation, eg. 9.999999
                  %g          General floating pint notation, eg. 1.1, 1.2e+06

<int> and <char> should only be used if the expression being printed yields an 
integer, and the <float> group should only be used for floating point results. 
%p is safe with any kind of pointer, but %s should be used only for expressions 
which yield a pointer to a zero-terminated string.

<string> is a sequence of characters enclosed in double quotes ("). A backslash 
(\) may be used as an escape character within a string.


Accessing Variables
-------------------


Print
.....

This command examines the contents of the debugged program's variables, or 
displays the result of arbitrary calculations involving variables and 
constants. Its syntax is:

    p{rint}{/<format>} <expression>

For example,

    print/%x listp->next

will print the field <next> of structure <listp>.

If no format string is entered, for integer values the format used is the 
current value of the variable <$format>. For floating point values the default 
format string is %g. Pointer values are treated as integers, using the fixed 
format %.8x by default, for example, 000100e4.

See the end of section "<Watch>" for details of possible 
difficulties with register variables.


Let
...

Let allows you to change the value of a variable or contents of a memory 
location. Its syntax is:

    {let} <variable> = <expression>{ <expression>}*
    {let} <memory-location> = <expression>{ <expression>}*

Either an equals sign or a colon can be used to separate the variable or 
location and the expression. If multiple expressions are used, they must be 
separated, either by commas or spaces.

Variables can only be changed to compatible types of expression. However the 
debugger will convert integers to floating point and vice versa, rounding to 
zero. The value of an array can be changed with this command, but not its 
address as array names are constants. If the subscript is omitted in this case, 
it defaults to zero. If multiple expressions are specified, each expression is 
assigned to <variable[n-1]>, where <n> is the nth expression.

This command is used in low-level debugging to change memory. If the left-hand 
side expression is a constant or a true expression (and not a variable) it will 
be treated as a word address, and memory at that (and if necessary following) 
locations will be changed to the values in the following expression(s).


Summary of armsd Variables
..........................

Many of the defaults in <armsd> can be modified by setting <armsd> variables.  
Most of these are described elsewhere in this chapter in more detail:

    $cmdline            argument string for the debuggee

    $echo               non zero if commands from obeyed files should be echoed 
                        (initially this is set to 0).

    $examine_lines      default number of lines for examine command (initially 
                        this is set to 8).

    $format             default format for printing integer values (initially 
                        this is set to "%d").

    $fpresult           floating point value returned by last 'called' function 
                        (junk if none, or if a floating point value was not 
                        returned).  This variable is read-only.

    $fr_full            non zero if the fpregisters command should print exact 
                        contents (initially this is set to 0).

    $inputbase          base for input of integer constants (initially this is 
                        set to 10).

    $list_lines         default number of lines for list command (initially 
                        this is set to 16).

    $rdi_log            rdi logging is enabled if non zero, and serial line 
                        logging is enabled if bit 1 is set (initially this is 
                        set to 0).

    $result             integer result returned by last 'called' function (junk 
                        if none, or if an integer result was not returned).  
                        This variable is read-only.

    $sourcedir          directory containing source code for the program being 
                        debugged (initially this is set to the current 
                        directory).

    $statistics         this variable can be used to output any statistics 
                        which the ARMulator has been keeping.  This variable is 
                        read only

    $statistics_inc     this variable is similar to $statistics, but outputs 
                        the difference between the current statistics and those 
                        when $statistics was last read.  This variable is read 
                        only.

    $type_lines         default number of lines for the type command

    $vector_catch       this variable indicates whether or not execution should 
                        be caught when various conditions arise.  The default 
                        value is %RUsPDifE.  Capital letters indicate that the 
                        condition is to be intercepted.  R stands for reset, U 
                        for undefined instruction, S for SWI, P for prefetch 
                        abort, D for data abort, I for IRQ, F for FIQ and E for 
                        Error.


Formatting Integer Results
..........................

Set the default format string used by the <print> command for the output of 
integer results by using <let> with the root-level variable <$format>. This is 
initially set to %d. The syntax is:

    {let} $format = <string>

Beware when using floating point formats, as integers will not print correctly. 
The contents of <string> should be a format as described in section "<Names 
Used in Syntax Descriptions>".


Specifying the Base for Input of Integer Constants
..................................................

Use the variable <$inputbase> to hold the base used for the input of integer 
constants. The syntax is:

    {let} $inputbase = <expression>

If the input base is set to 0, <armsd> will interpret numbers as octal or 
hexadecimal if they begin with 0 or 0x respectively. (This is the same 
convention as used by C). Note that <$inputbase> only specifies the base for 
the input of numbers and the output format should be specified by setting 
<$format> to an appropriate setting.


Symbols
-------

This command lists all symbols (variables) defined in the given or current 
context, along with their type information. The syntax for this command is:

    sy{mbols} {<context>}

The information produced is listed in the form:

    <name> <type>, <storage-class>

To see global variables quote the module name as the context, and to see 
variables defined outside any function definitions in C use the name of the 
source file as context.


Variable
........

The <variable> command provides type and context information on the <variable> 
(or structure field) specified. The syntax is:

    v{ariable} <variable>

<variable> can also return the type of an expression.


Arguments 
..........

This command is used to show the arguments which were passed to the current 
procedure, or another active procedure. Its syntax is:

    a{rguments} {<context>}

If <context> is not specified, the current context, normally the procedure 
which was active when the program was suspended, is used. Each argument's name 
and current value is displayed.


Accessing and Executing Programs
--------------------------------


Go
..

This command starts execution of the program. The first time <go> is executed, 
the program starts from its normal entry point. Subsequent <go> commands resume 
execution from the point at which it was suspended. The syntax is:

    g{o} {w{hile} <expression>}

If <while> is used <expression> is evaluated whenever a breakpoint is reached, 
and if  <expression> evaluates to true (ie non-zero) the breakpoint is not 
reported and execution is continued.


Type
....

This command types the contents of a source file, or any text file, between a 
specified pair of line numbers. Its syntax is:

    t{ype} {<expression1>} {, {{+}<expression2>} {,<filename>} }

The start line is given by <expression1>. If <expression1> is omitted, it 
defaults to:

 *  the source line associated with the current context minus 5, if the context 
    has changed since the last type command;

 *  the line following the last line displayed with the <type> command, if the 
    context has not changed.

The end line is given by <expression2> , in one of three ways:

 *  if <expressions2> is omitted, the end line is the start line +10.

 *  if <expression2> is preceded by + the end line is given by the value of the 
    start line + <expression2>

 *  if there is no + the end line is simply the value of <expression2> 

To look at a file other than that of the current context, specify the filename 
required and the locations within it to type.

To change the number of lines displayed from the default setting of 10, use the 
<$type_lines> variable.


Load
....

This command loads an image for debugging. Its syntax is:

    lo{ad} <image-file> {<arguments>}

<image-file> is the name of the program to be debugged, and <arguments> are the 
command-line arguments the program would normally take when run. <image-file> 
and any necessary arguments may also be specified on the <armsd> command-line 
when <armsd> is invoked. If no arguments are supplied, the arguments used in 
the most recent <load>, <reload>, setting od <$cmdline>,  or command-line 
invocation are used again. All breakpoints and watchpoints are cleared by <load>
.


Sourcedir

The variable <$sourcedir> is used to specify the directory containing program 
source files. It can be set by:

    {let} $sourcedir = <string>

The string should be a valid directory name in which <armsd> will search for 
source files.


Command Line Arguments

Command line arguments for the debuggee can be specified using the let command 
with the root-level variable <$cmdline>. The syntax in this case is:

    {let} $cmdline = <string>

The program name is automatically passed as the first argument, and thus should 
not be included in the string. The setting of <$cmdline> can be examined using 
print.


Reload
......

This command reloads the object file specified on the <armsd> command line, or 
the last <load> command. Its syntax is:

    rel{oad} {<arguments>}

If no arguments are specified with this command, the arguments used in the most 
recent <load>, <reload>, setting of<$cmdline> or command line invocation are 
used again. Breakpoints (but not watchpoints) remain set after a reload 
command.


Getfile
.......

This command reads the contents of an area of memory from a file.  Its syntax 
is:

    getfile <filename> <expression>

The contents of the file are written to memory as a sequence of bytes, starting 
at the address which is the value of <expression>.


Putfile
.......

This command writes the contents of an area of memory to a file.  Its syntax 
is:

putfile <filename> <expression1>, {+}<expression2>

The lower bound of the area of memory to be written is the value of <expression1>
.  The upper bound is:

 *  the value of <expression2> - 1 if <expression2> is not preceded by '+';

 *  the value of <expression1> + <expression2> - 1 if <expression2> is preceded 
    by '+'.

The file is written as a sequence of bytes.


Controlling Execution
---------------------


Step
....

This command steps execution through one or more statements. The syntax is:

    s{tep} {in} {<count>|whi{le} <expression>}

Use <in> to continue single stepping into procedure calls, so that each 
statement within a called procedure is single stepped. If <in> is absent, each 
procedure call counts as a single statement and is executed without single 
stepping. <count> specifies the number of statements to be stepped through: if 
it is omitted only one statement will be executed. The <while> clause continues 
single stepped execution until its <expression>, which is evaluated after every 
step, evaluates as false (ie zero).

To step by instructions rather than statements, set the language to none (using 
<language none>), or use the <istep> command.


Istep
.....

This command steps execution through one or more instructions.  Its syntax is:

    is{tep} {in} {<count>|whi{le} <expression>}

Its behaviour is identical to that of the <step> command when the language has 
been set to none.


Break
.....

This command is used to set breakpoints. These may be specified at procedure 
entry and exit, lines, statements within a line, or at program labels. Its 
syntax is:

    b{reak} {<location> {<count>} {do '{'<command>{;<command>}'}'} {if 
    <expression>}}

<location> specifies where the breakpoint is to be inserted, and <count> the 
number of times the statement there must be executed before the program is 
suspended. It defaults to 1, so if <count> is not specified the program will be 
suspended the first time the breakpoint is encountered.

The breakpoint can be made conditional upon the value of <expression> in the <if> 
clause, if one is used.

Use <do> to specify commands to be executed when the breakpoint is reached. 
Note that these commands must be enclosed in curly brackets, represented in the 
pattern above by curly brackets within quotes; commands should be separated by 
semicolons.

<break> usually displays the program and source line at the breakpoint, unless 
a <do> clause is specified; if you need this display as well as the commands in 
the <do> clause, use <where> as the first command in the <do> clause to display 
the line.

Each breakpoint is given a number prefixed by #; a list of current breakpoints 
and their numbers is displayed if <break> is used without any arguments.

If a breakpoint is set at a procedure exit, several breakpoints may be set, 
with one for each possible exit. Use <unbreak> to delete any unwanted 
breakpoints, referring to them by their number preceded by #. All such 
breakpoints can also be deleted by referring to them by location.


Unbreak
.......

This command removes a breakpoint. Its syntax is:

    unb{reak} {<location>}

<location> is either a source code location, or # followed by the breakpoint 
number as displayed by <break>. Note that breakpoints are not renumbered 
following deletion of other breakpoints unless the breakpoint deleted was the 
last one set. Once a breakpoint has been assigned a number it keeps it.

If there is only one breakpoint set <unbreak> without any arguments can be used 
to delete it.


Watch
.....

This command is used to set a watchpoint on a variable. When the variable is 
altered, program execution is suspended. The syntax is:

    w{atch} {<variable>}

If variable isnot specified, a list of current watchpoints is displayed along 
with their numbers. As with <break>/<unbreak> these numbers can subsequently be 
used to remove watchpoints.

The existence of watchpoints may make programs execute very slowly, because the 
value of variables has to be checked every time they could have been altered. 
It is probably more practical to set a breakpoint in the area of suspicion and 
set watchpoints once execution has been stopped there.

When using the C compiler, be aware that the code produced can use the same 
register to hold more than one variable if their lifetimes don't overlap. If 
the register variable you are investigating is no longer being used by the 
compiler at that point you may see a value pertaining to a completely different 
variable.


Unwatch
.......

This command clears a watchpoint. Its syntax is:

    unw{atch} {<variable>}

The argument <variable> can be either a variable name or the number of a 
watchpoint (preceded by #) set using <watch>. If only one watchpoint has been 
set <unwatch> alone will delete it.


Call
....

This command calls a procedure. The syntax is:

    ca{ll} <location> {(<expression-list>)}

<location> is a function or low-level address. Each expression is an argument 
to the procedure. Note that string literals are not permitted as arguments.  If 
more than one expression is to be specified, the expressions should be 
separated by commas. If the procedure (or function) returns a value, it can be 
examined using <print $result> for integer variables or <print $fpresult> for 
floating point variables.


Return
......

This command is used to return to the caller of the current procedure, passing 
back a result where required. The syntax of this command is:

    ret{urn} {<expression>}

Note that there is no way to specify the return of a literal compound data type 
such as an array or record using this command. However the value of a variable 
or expression or compound type may be returned.


Program Context
---------------


Where
.....

This command prints the current context in terms of a procedure name, line 
number in the file, filename and the line of code. Its syntax is:

    wh{ere} {<context>}

If a <context> is specified after the <where> command <armsd> will display the 
location of that context.


Backtrace
.........

This command prints information about all currently active procedures, starting 
with the most recent, or for a given number of levels, specified using <count>. 
The syntax is:

    ba{cktrace} {<count>}


Context
.......

This is used to set the context in which the variable lookups will occur. It 
affects the default context used by commands which take a context as an 
argument. When program execution is suspended, the search context is set to the 
active procedure. The syntax of this command is:

    c{ontext} {<context>}

If <context> is not specified, the context will be reset to the active 
procedure.


Out and In 
...........

These commands are a shorthand way of changing the current context by one 
activation level. Their syntax is simply:

    o{ut}
    i{n}

<Out> sets the context to that of the caller of the current context, and <in> 
sets the context to that called from the current level. It is an error to issue 
an <out> or <in> command when no further movement in that direction is 
possible.


Low Level Debugging
-------------------


Enabling Low Level Debugging
............................

Low level debugging tables are generated automatically when programs are linked 
with the -debug flag set. In fact it is not possible to include high-level 
debugging tables in an image without inlcuding the low-level ones as well. 
There is no need to enable debugging at the compilation stage if only low level 
debugging is to be done; all that need be done is specify debugging when 
linking the program.


Low Level Symbols
.................

Low-level symbols are differentiated from high-level ones by preceding them 
with @. A low-level symbol for a procedure refers to its call address, often 
the first instruction of the stack frame initialisation, whereas the 
corresponding high-level symbol (if any) refers to the address of the code 
generated by the first statement in the procedure.

Low-level symbols can be used with most <armsd> commands; for example with 
<watch> they stop execution if the word at the location named by the symbol 
changes. Memory addresses can also be used with commands and should also be 
preceded by @.

Low-level symbols can also be used where a command would expect an expression; 
its value is the address of the low-level symbol. @ need not be used unless 
there is a high-level symbol of the same name.

There are several pre-defined low-level symbols:

 *  r0, r1, r2, r3, r4, r5, r6, r7, r8, r9, r10, r11, r12, r13, r14
    These refer to the general-purpose ARM registers 0 to 14.

 *  r15
    This refers to the address of the instruction which is about to execute. 
    This may include the condition code flags, interrupt enable flags, and 
    processor mode bits, depending on the target ARM architecture (ie this 
    information will be included in 26-bit address mode; not otherwise). Note 
    that this value may be different from the real value of register 15 due to 
    the effect of pipelining.

 *  pc
    The address of the instruction which is about to execute, without any 
    processor status register (psr) flags.

 *  psr, cpsr, spsr
    <psr> and <cpsr> are synonyms for the processor status register for the 
    current mode.  <spsr> is the saved status register for the current mode.  
    The values displayed for  the condition code flags, interrupt enable flags, 
    and processor mode bits, are an alphabetic letter per condition code and 
    interrupt enable flag, and an underscore-preceded mode name for the mode 
    bits. This mode name will be one of _USER26, _IRQ26, _FIQ26, _SVC26, 
    _USER32, _IRQ32, _FIQ32, _SVC32, _UNDEF32 and _ABORT32. For full 
    information about these modes and the implications of 26- and 32-bit ARM 
    architectures please refer to the appropriate ARM datasheet.  Note that 
    <spsr> is not defined if the processor is not capable of 32-bit operation.

 *  f0, f1, f2, f3, f4, f5, f6, f7
    The floating point registers 0 to 7.

 *  fpsr
    The floating point status register.

 *  fpcr
    The floating point control register.

 *  a1, a2, a3, a4
    These refer to arguments 1 to 4 in a procedure call (stored in r0 to r3).

 *  v1, v2, v3, v4, v5, v6, v7
    These refer to the five to seven general purpose register variables which 
    the compiler may allocate as it pleases (stored in r4 to r10).

 *  sb
    Static base, as used in reentrant variants of the ARM Procedure Call 
    Standard (APCS) (r9/v6).

 *  sl
    The stack limit register, used in variants of the APCS which implement 
    software stack limit checking (r10/v7).

 *  fp
    The frame pointer (r11).

 *  ip
    Used in procedure entry and exit and as a scratch register (r12).

 *  sp
    The stack pointer (r13).

 *  lr
    The link register (r14).

All of these registers can be examined with the <print> command and changed 
with the <let> command.

For example, the form <print/%x psr> will display the processor status register 
(PSR).

<let> can also be used to set the processor status register (PSR), using the 
usual syntax for PSR flags . For example, the N and F flags could be set, the V 
flag cleared, and the I, Z and C flags left untouched and the processor set to 
26-bit supervisor mode, by typing:

    let psr = %NvF_SVC26

Note the percentage sign which must precede the condition flags and the 
underscore which must precede the processor mode description.

These symbols are defined in the root context, so if you have a variable <r0> 
and you wish to refer to register 0 you can use # to specify the register, as 
follows:

    print #r0


Language
........

<armsd> uses any high-level debugging tables generated by a compiler to set the 
default language to the appropriate one for that compiler, whether it is 
Pascal, Fortran or C. If it does not find high-level tables it sets the default 
language to none, and modifies the behaviour of <where> and <step>. In this 
case <where> reports the current program counter and instruction; <step> steps 
by one instruction.

If your program contains high-level debugging information and you wish to use 
low-level debugging, use the language command to set this up. The syntax is:

    la{nguage} none


Registers
.........

This command displays the contents of the ARM registers 0 to 14, the program 
counter (PC) and the status flags contained in the processor status register 
(PSR). The syntax is:

    r{egisters} {<mode>}

If used with no arguments, or if <mode> is the current mode, the contents of 
all registers of the current mode are displayed.  If the <mode> argument is 
specified, but is not the current mode, the contents of the banked registers 
for that mode are displayed.  In addition to the mode names listed in section "
<Low Level Symbols>", <mode> may take the value the value 
<all>, in which case the contents of all registers of the current mode are 
displayed, together with all banked registers for other modes with the same 
address width.

A sample display produced by registers might look like this:

    R0 = 0x00000000  R1 = 0x00000001  R2 = 0x00000002  R3 = 0x00000003
    R4 = 0x00000004  R5 = 0x00000005  R6 = 0x00000006  R7 = 0x00000007
    R8 = 0x00000008  R9 = 0x00000009  R10= 0x0000000a  R11= 0x0000000b
    R12= 0x0000000c  R13= 0x0000000d  R14= 0x0000000e
    PC = 0x00008000  PSR= %NzcVIF_SVC26


Fpregisters
...........

This command displays the contents of the eight floating point registers f0 to 
f7 and the floating point processor status register FPSR. Its syntax is:

    f{pregisters}

There are two formats for the display of floating point registers, selected 
using the root-level variable <$fr_full> with <let>. The simpler form displays 
the registers and FPSR, and the full version includes detailed information on 
the floating point numbers in the registers. Use:

    {let} $fr_full = 0

to produce the display:

    f0 = 0        f1 = 0        f2 = 0        f3 = 0
    f4 = 0        f5 = 0        f6 = 0        f7 = 0
    fpsr = %IZOux_izoux

Use the alternative:

    {let} $fr_full = 1

to produce the more detailed display:

    f0 = 0        f1 = 0        f2 = 0        f3 = 0
    f4 = 0        f5 = 0        f6 = 0        f7 = 0
    fpsr = %IZOux_izoux
         S Exp    J Mantissa                 S Exp    J Mantissa
    f0 = 0 0x0000 0 0x0000000000000000  f1 = 0 0x0000 0 0x0000000000000000
    f2 = 0 0x0000 0 0x0000000000000000  f3 = 0 0x0000 0 0x0000000000000000
    f4 = 0 0x0000 0 0x0000000000000000  f5 = 0 0x0000 0 0x0000000000000000
    f6 = 0 0x0000 0 0x0000000000000000  f7 = 0 0x0000 0 0x0000000000000000
    fpsr = 0x00070000

<S> is the sign, <Exp> is the exponent, and <J> the bit to the left of the 
binary point.

In the FPSR description the first set of letters indicates the floating point 
mask and the second the floating point flags. The status of the various 
floating point mask and flag bits is indicated by their case; upper case means 
the flag is set and lower case means that it is cleared. The flags are:

    I           Invalid operation

    Z           Divided by zero

    O           Overflow

    U           Underflow

    X           Inexact 


Examine
.......

This command allows you to examine the contents of the memory between a pair of 
addresses, displaying it in both hexadecimal and ASCII formats, with 16 bytes 
per line. Its syntax is:

    e{xamine} {<expression1>} {, {+}<expression2> }

The start address is given by <expression1>; if this is omitted the default 
address used is either:

 *  the address associated with the current context, minus 64, if the context 
    has changed since the last <examine> command was executed;

 *  the address following the last address displayed by the last <examine> 
    command, if the context has not changed since the last <examine> command 
    was executed.

The end address is specified in <expression2> , which may take three forms:

 *  if omitted the end address is the value of the start address +128 

 *  if <expression2> is preceded by +, the end address is given by the value of 
    the start line + <expression2>.

 *  if there is no + the end line is the value of <expression2>.

The <$examine_lines> variable can be used to alter the default number of lines 
displayed from its initial value of 8 (128 bytes).


List
....

This command displays contents of the memory between specified pair of 
addresses in hexadecimal, ASCII and instruction format, with 4 bytes (one 
instruction) per line. The syntax is:

    l{ist} {<expression1>}{, {+}<expression2> }

The start address is given by <expression1>; if no address is specifed the 
default setting is either:

 *  the address associated with the current context minus 32, if the context 
    has changed since the last <list> command was issued;

 *  the address following the last address displayed by the last list command, 
    if the context has not changed since the last <list> command was issued.

The end address is given by <expression2>; and may take three forms:

 *  if <expression2> is omitted, the end address is the value of the start 
    address + 64.

 *  if it is preceded by + the end address is given by the value of the start 
    line + <expression2>. 

 *  If there is no + the end line is the value of <expression2>. 

The <$list_lines> variable can be used to alter the default number of lines 
displayed from its initial value of 16 (64 bytes).


Find
....

This command finds all occurances in memory of a given integer value or 
character string.  Its syntax is either of the following:

    fi{nd} <expression1> {,<expression2> {,<expression3>}}

    fi{nd} <string> {,<expression2> {,<expression3>}}

<expression2> and <expression3> specify the lower and upper bounds for the 
search.  If <expression2> is absent, the base of the currently loaded image is 
used.  If <expression3> is absent, the top (R/W limit) of the currently loaded 
image is used.

If the first form is used, the search is for words in memory whose contents 
match the value of <expression1>.  If the second form is used, the search is 
for a sequence of bytes in memory (starting at any byte boundary) whose 
contents match those of string.


Lsym
....

This command displays low-level symbols and their values. Its syntax is:

    ls{ym} <pattern>

<pattern> is a symbol name or part of a symbol name. A wildcard (indicated by 
*) can be used at the beginning and/or end of the pattern to match any number 
of characters. Thus:

    ls fred     will display information about fred

    ls *fred    will display information about fred, alfred

    ls fred*    will display information about fred, frederick

    ls *fred*   will display information about alfred, alfreda, fred, frederick


Coprocessor Support
-------------------

<armsd>'s coprocessor support allows access to registers of a coprocessor 
through a debug monitor which is ignorant of the coprocessor. In order for this 
to be possible, the the registers of the coprocessor should be read (if 
readable) and written (if writeable) by a single CPDT or CPRT instruction in a 
non-user mode. For coprocessors with more exotic registers, there must be 
support code in a debug monitor.


Coproc
......

This command describes the register set of a coprocessor and specifies how the 
contents of the registers should be formatted for display. The syntax is:

    c{oproc} <cpnum> {<regdesc>}*

Each <regdesc> may describe one register, or a range of registers which are 
accessed and are to be formatted uniformly.  It has the syntax:

    <rno>{:<rno1>}  <size> <access-specifiers> <access-values> {<displaydesc>}*

<size> is the register size (in bytes)

<access-specifiers> may comprise the letters:

    R           the register is readable

    W           the register is writeable

    D           the register is accessed through CPDT instructions (if this is 
                not present, the register is accessed through CPRT 
                instructions).

The format of <access-values> depends whether the register is to be accessed 
through CPRT instructions. If so, it comprises four integer values separated by 
space or comma:

    r0_7, r16_23, w0_7, w16_23

to form bits 0 to 7 and 16 to 23 of a CPRT instruction to read the register, 
and bits 0 to 7 and 16 to 23 of a CPRT instruction to write the register.

If not, it comprises two integer values b12_15 and b22, to form bits 12 to 15 
and bit 22 of CPDT instructions to read and write the register.

<displaydesc> is one of the items:

<string>to be printed as is.

<field> <string>

    <string>    is to be used as a printf format string to display the value of 
                <field>.

    <field>     is one of the forms:
                w<n>              the (whole of the) nth word of the register 
                value
                w<n>[<bit>]       bit <bit> of the nth word of the register 
                value
                w<n>[<bit1>:<bit2>]
                bits <bit1> to <bit2> inclusive of the nth word of the register 
                value. <bit1> and <bit2> may be given in either order.

<field> '{' <string> {<string>}* '}'

    <field>     must take on of the forms w<n>[<bit>] or w<n>[<bit1>:<bit2>] 
                above. There must be one string for each possible value of 
                <field>.  The string in the appropriate position for the value 
                of <field> is displayed (the first string for value 0, and so 
                on).

<field> '<letters>'

    <field>     must take on of the forms w<n>[<bit>] or w<n>[<bit1>:<bit2>] 
                above. There must be one character in <letters> for each bit of 
                <field>.  The letters are displayed, in upper case if the 
                corresponding bit of the field is set, in lower case otherwise. 
                The lowest bit of the field corresponds to the first letter if 
                <bit1> < <bit2>, to the last letter otherwise.

For example, the floating point coprocessor might be described by the command 
(reformatted for clarity):

    copro 1 0:7 16 RWD 1,8
      8 4 RW 0x10,0x30,0x10,0x20 w0[16:20] 'izoux' "_" w0[0:4] 'izoux'
      9 4 RW 0x10,0x50,0x10,0x40


Cregisters
..........

This command displays the contents of all readable registers of a coprocessor, 
in the format specified by an earlier COPROC command. The syntax is:

    cr{egisters} <cpnum>


Cwrite
......

This command writes to a coprocessor register.  The syntax is:

    cw{rite} <cpnum> <rno> <val> {<val>}*

Register <rno> of coprocessor <cpnum> must have been specified as writeable; 
each <val> is an integer value and there must be one <val> item for each word 
of the coprocessor register.


Miscellaneous Commands
----------------------


While
.....

This command is only valid at the end of a multi-statement line. 
Multi-statement lines are entered by separating the statements with ';' 
characters. The syntax is:

    whi{le} <expression>

This causes interpretation of the line to continue until <expression> evaluates 
to false (i.e. zero).


Help
....

This command displays a list of available commands, or help on a particular 
command. Its syntax is:

    h{elp} {<command>}

If information about all commands as well as their names is required, type <help 
*>. The help displayed includes syntax and a brief description of the purpose 
of each command.


Alias
.....

This command defines, undefines or lists aliases. It allows you to define your 
own <armsd> commands. Its syntax is:

    al{ias} {<name> {<expansion>}}

If no arguments are given all currently defined aliases are displayed. If 
<expansion> is not specified, the alias named is deleted. Otherwise <expansion> 
is assigned to the alias <name>. The <expansion> may be enclosed in double 
quotes (") to allow the inclusion of characters not normally permitted or with 
special meanings, such as the alias expansion character '`' and the statement 
separator ';'.

Aliases are expanded whenever a command line or the command list in a <do> 
clause is about to be executed.

Words consisting of alphanumeric characters enclosed in backquotes (`) are 
expanded. If no corresponding alias is found they are replaced by null strings. 
If the character following the closing backquote is non-alphanumeric, the 
closing backquote may be omitted. If the word is the first word of a command, 
the opening backquote may be omitted. To use a backquote in a command, precede 
it with another backquote (i.e. '``').


Obey
....

This command executes a set of debugger commands which have previously been 
stored in a file, as if they were being typed at the keyboard. The syntax is:

    ob{ey} <command-file>

where <command-file> is the name of the file containing the list of commands to 
be executed.


Log
...

This command causes the output of subsequent commands to be sent to a file as 
well as to the screen. Its syntax is:

    log <filename>

where <filename> is the name of the file where the record of activity is being 
stored. To terminate logging, type <log> without an argument. The file can then 
be examined using a text editor or the <type> command.

Note that the <armsd:> prompt, and input / output to or from the program being 
debugged is not logged.


Pause
.....

This command prompts the user to press a key to continue.  Its syntax is:

    pa{use} <prompt-string>

The prompt string is written to stderr, and execution continues only when a key 
is pressed.  If ESC is pressed and commands are being read from a file then 
that file is closed before execution continues.


Comment
.......

This command writes a message to stderr.  The syntax is:

    com{ment} <message>


Quit
....

This command terminates the current <armsd> session and closes any open <log> 
or <obey> files. Its syntax is:

    q{uit}


!
.

Any command whose first character is ! will be passed to the host operating 
system for execution. This gives access to the Command line of the host system 
without quitting <armsd>.


Automatic Command Execution on Startup
--------------------------------------

<armsd> will obey commands from an initialisation file if one exists before it 
reads commands from the standard input.  The name of the initialisation file 
varies from host to host:

    SunOS         .asdinit

    PC DOS        armsd.ini

    Macintosh     asdinit

First the current directory is searched, and then the directory specified by 
the environment variable HOME.

