\documentstyle[a4,12pt]{article}
\begin{document}
\author{APM Manual pages}
\title{SOFTWARE FRONT PANEL}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in

\section{Preamble}
The SFP is a facility for debugging programs, in particular those
which run on "the bare machine", i.e. operating systems. It was written
specifically for the benefit of those attempting the CS3 Operating
Systems exercise. \hspace{ 0.3 in} The features offered are \hspace{ 0.2 in} those \hspace{ 0.2 in} which \hspace{ 0.2 in} were
traditionally provided by a real front panel with lights and switches.
The contents of memory and registers may be examined and altered, and
programs may be executed one instruction at a time, one "statement" at a
time, or continuously. \hspace{ 0.2 in} Watchpoints, breakpoints, and breaklines may be
set.

A watchpoint is a longword location which is monitored after the
execution of each instruction or line, and causes the SFP to be invoked
if its contents have changed.

A breakpoint is a point at a specified absolute PC address (which
must be on an instruction boundary) at which normal execution of the
program is suspended (broken) and the SFP invoked.

A breakline is similar to a breakpoint, except that its position is
specified in terms of a high-level-language line number rather than an
absolute PC value. \hspace{ 0.2 in} Breaklines can only be specified for programs which
have been compiled with the -TRACE qualifier.

\section{Running programs (operating systems) under control of the SFP}

The command TRY $<$filename$>$ will load the file $<$filename$>$.MOB into
main memory, starting at the low-address end. \hspace{ 0.2 in} In addition, the code of
the Software Front Panel is loaded into local memory. \hspace{ 0.2 in} The SFP is then
invoked such that giving the RUN command causes the loaded program to be
entered, with the registers initialised as follows:

\small\tt \begin{verbatim}D0-D3:  undefined     A0-A3:  undefined
   D4:  0                A4:  points at the program's data area
   D5:  0                A5:  points to the process's data area
   D6:  LOW+256          A6:  undefined
   D7:  16_80808080     SSP:  HIGH
   SR:  16_2700         USP:  undefined
\end{verbatim}\rm  \normalsize 
The bulk of the remainder of free memory (memory not occupied by the
program's code and data or the process's data area) is bracketed by the
values LOW (inclusive) and HIGH (exclusive).

In fact the program's data area will be adjacent to the program's
stack [A4 = SP+4, (SP) = return address], which is a compiler-imposed
requirement.

The process data area is a 2048-byte area initialised to zeroes. The
event mechanism reserves the first 360 of these.

\section{Invoking the front panel}

Once the loaded program is running, the SFP may be invoked in one of
the following ways:

Following the execution of a single instruction or statement, or
after a breakpoint has been reached or a watchpoint has changed.

Following the occurrence of some unexpected exception such as address
error, privilege violation, uninitialised interrupt vector.

Once invoked, the SFP dumps the contents of all the processor
registers, as well as a selected 32-byte area of store, on the upper
part of the terminal screen, together with a message stating the reason
for the invocation.

\section{Using the front panel}

Once invoked, the SFP accepts single-character commands which take
immediate effect, i.e. are not subject to line-editing. \hspace{ 0.2 in} Some of these
commands cause direct action, while others solicit further information,
which IS subject to line-editing (DEL only). \hspace{ 0.2 in} A summary of the commands
is given below.

\subsection{($\hat{ }${}Y) Reload Standard System}

This causes the session to be abandoned and the standard system to be
re-loaded.

\subsection{(S) Single Instruction}

One single instruction of the program under test is executed, and the
SFP is then re-invoked.

\subsection{(G) Go}

This causes the program under test to be executed slowly, one
instruction at a time, until the next break-point or break-line is
reached, or one of the watch-points has changed.

\subsection{(R) Run}

This causes full control to be passed to the program under test.
Watch-points are not monitored, nor are break-lines (unless the program
was compiled with the -TRACE qualifier). Break-points remain in effect,
though, because they are implemented by temporarily replacing the
instruction at the breakpoint(s) by a special instruction.

\subsection{(V) Change View Area Address}

This command is used to determine the start address of the 32-byte
area of memory to be dumped to the screen whenever the SFP is invoked.
The parameter is a REFERENCE (see below).

Notice that where the parameter denotes a memory location involving a
register as a pointer, the register contents used are those at
display-time, \hspace{ 0.2 in} not \hspace{ 0.2 in} specify-time, i.e. the reference-expression is
dynamic.

By default, the view area is at P-10, so that the next instruction to
be executed will appear in the middle of the view area.

\subsection{(Cursor keys) Scroll view area}

The offset part of the view area address may be amended by adding or
subtracting 2 or 16, by using the cursor keys. \hspace{ 0.2 in} The up/down keys modify
the address by 16, the left/right ones by 2.

\subsection{(P) Poke: Alter contents of memory}

This command is used to alter the contents of memory or registers.
One or more locations may be affected, and they may be either 8-bit
bytes, 16-bit words, or 32-bit longwords. The parameters are:

\hspace*{ 0.2 in} (1) A reference, which determines the (first) location to be altered.
\\ \hspace*{ 0.2 in} (2) An operand size designator (.L/.W/.B), it may be omitted in which
case .L is assumed.
\\ \hspace*{ 0.2 in} (3) A value (hex number).
\\ \hspace*{ 0.2 in} (4) (optionally) an asterisk followed by a repetition count.
\\ \hspace*{ 0.2 in} (5) (3) and (4) may be repeated ad lib.

Examples:

\small\tt \begin{verbatim}Poke:r8 0             set A0 to 0
Poke:a5+2fc.w 1 2 3   set 2FC(A5) to 1, 2FE(A5) to 2, and 300(A5) to 3.
Poke:a4-0 0*200 1*5   clear 200 longwords at (a4) and set the next 5 to 1.
\end{verbatim}\rm  \normalsize 
\subsection{(B) Add or Remove Breakpoint}

The parameter is the absolute address of an instruction. \hspace{ 0.2 in} If
positive, a breakpoint with that address is inserted. \hspace{ 0.2 in} If negative, an
existing breakpoint at the (re-negated) address is removed.

Up to eight breakpoints may be in effect at a time.

The instruction at the specified address is remembered somewhere and
replaced by the opcode 16\_FEED, which is an illegal instruction. \hspace{ 0.2 in} When
this instruction is executed, the code which deals with illegal
instructions recognises it as the break instruction, searches its table
for the address, replaces the original instruction, executes it,
restores the break instruction and finally invokes the SFP.

\subsection{(W) Add or Remove Watchpoint}

The parameter is a REFERENCE, and may be follwed by a minus sign.
The specified point is added to the list of locations to be watched (or
removed from it if the minus sign is present).

Up to eight watchpoints may be in effect at a time.

\subsection{(L) Add or Remove Breakline}

The parameter is a decimal number (note: everywhere else numbers are
assumed to be in hex - ONLY line numbers are in decimal). \hspace{ 0.2 in} If positive,
a breakline is added, if negative it is removed. If line 0 is specified
this means that the SFP is invoked EVERY TIME the line number is
updated.

Up to eight distinct breaklines may be in effect at a time.

\subsection{What is a REFERENCE?}

A "reference" is a parameter to the V, P, or W command and identifies
a location in memory (or a register). It can be any of the following:

(1) \hspace{ 0.3 in} The letter R followed by a number. \hspace{ 0.2 in} This designates a register:
R0-R7 denote D0-D7, R8-RF denote A0-A7, R10-R12 denote USP, SR, and PC.

(2) \hspace{ 0.3 in} A number. \hspace{ 0.2 in} This designates the memory location with the given
absolute address.

(3) \hspace{ 0.3 in} (*) The letter A followed by a number. \hspace{ 0.2 in} This designates the
memory location pointed at by the specified address register.

(4) \hspace{ 0.3 in} (*) The letter U, which denotes the memory location pointed at by
the User Stack Pointer.

(5) \hspace{ 0.3 in} (*) The letter P, which denotes the memory location pointed at by
the Program Counter.

(6) \hspace{ 0.3 in} (*) The symbol @ followed by a number, which denotes the memory
location pointed at by the contents of the memory location whose
absolute address was specified.

(*) \hspace{ 0.3 in} Each of (3) to (6) above must be followed by an OFFSET which is a
number (possibly preceeded by a - or + symbol).

Examples:

\hspace*{ 0.2 in} U6 denotes the location whose address is USP+6.
\\ \hspace*{ 0.2 in} A5-8 denotes the location whose address is A5-8.
\\ \hspace*{ 0.2 in} A3+20 (or A3 20) denotes the location whose address is A3+20.
\\ \hspace*{ 0.2 in} @4-4 denotes the location whose address is
\\ \hspace*{ 0.2 in} (the contents of the long word at address 4) minus four.


\section{Environmental considerations}
Trial operating systems run on the bare machine, outwith the cocoon
of the run-time-support environment which would be present were the
program running under the normal operating system. \hspace{ 0.2 in} There is no
provision for running programs which expect to be linked with other
modules of external procedures or data.

A minimal environment has, however, been made available to enable use
of some of the operations normally taken for granted. \hspace{ 0.2 in} These are:
integer multiplication and division (but not exponentiation), support
for the Imp EVENT signalling and trapping mechanism, the Imp procedures
PRINTSYMBOL, PRINTSTRING, READSYMBOL, SKIPSYMBOL, NEXTSYMBOL (but to the
terminal only), and the READFILE procedure, though this latter one must
be explicitly SPECked. \hspace{ 0.3 in} Certain Imp language features which are
implemented by way of an implicit (hidden) external spec are not
available (string resolution in particular).

\vspace{.75in} view:sfp printed on 16/02/89 at 14.01

\newpage
\tableofcontents
\end{document}