archambe@sombre.iro.umontreal.ca (Benoit Archambault) (12/13/88)
SIMON is an OS9 level1 machine language debuger I wrote last year. It was
entirely written in assembly language. It's small efficient but unfortunately
not perfect. I'm preparing a C version of SIMON that will run on a CoCo3 this
time.
You can email me your comments : archambe@iro.umontreal.ca
This file is TROFF file, you can print it using the UNIX command :
tbl simon.doc | eqn | troff -ms -t | lpr -t -Printer
------------------------------CUT HERE--------------------------------------
.TL
SIMON
.sp 12
.AU
Machine language debuger for OS9 Level 1
version 1.00
.sp
(c) Copyright 1987 by Benoit Archambault
ALL RIGHTS RESERVED
.sp 20
.LP
SIMON is the copyrighted property of B. Archambault and is not public
domain software. You may distribute it, upload it, download it, use it, etc,
as long as it is FREE. It may NOT be used as part of any commercial ventures,
nor as a sales aid without the expressed written consent of the author.
.sp 3
.PP
.SH
INTRODUCTION
.PP
SIMON is intended to provide the user a mean to debug 6809 machine
code on the CoCo II running OS-9 Level 1. As its name states, it permits
you to SIMulate by software 6809 instructions. It also gives the standard
tools a MONitor provides.
.PP
SIMON lets you to disassemble any program in memory, simulate programs
in memory either step by step or by trace mode and set breakpoints. SIMON
keeps track of the execution time taken by a programs while simulating so you
can time critical routines and optimize them as needed. Although SIMON simulates
programs by software it won't let you simulate drivers, system modules or
system calls. Needless to say that SIMON is not well suited for real time
applications.
.SH
RUNNING SIMON
.PP
First you have to install SIMON in the current execution directory so you
can call it from the shell. Now all you have to do is type SIMON. The screen
clears and a copyright message should appear at the top left corner of your
monitor.
.PP
At this point you can type any command SIMON understands. To get a summary of
those commands you can type ? (HELP) and all the commands will be printed with
a short description of what they let you do.
.sp 3
.SH
.ce
SUMMARY OF SIMON COMMANDS
.sp 2
.TS
center tab (/) allbox;
c c
l l .
Commands/Description
L {start} {#instructions}/Disassemble n instructions
X/Display all 6809 Registers
.{Reg. Name} {Value}/Modify or Visualise register content
?/Display help menu
FILL {start} {end} {value}/Fill a block of memory with value
MOVE {start} {end}/Move a block of memory
#{Decimal number}/Make a decimal to hexadecimal conversion
${Hex. number}/Make an hex. to decimal conversion
S {Start}/Simulate 1 instruction (Step by step)
T {Start} {End}/Simulate a block of instruction (Trace)
DSP {ON|OFF}/Enable or Disable printing during trace
C {Value}/Visualise or Modify cycle counter
G {Start} {end}/Execute a program
R ModuleName/Link to a module
D {start} {end}/Dump memory on screen
&{command}/Execute OS9 command
QUIT/Exit to OS9
.TE
.bp
.SH
SYNTAX
.PP
Before we go any further, we have to explain the way SIMON accepts the
commands. A line of commands is made of two members: The command and the
parameters. Each member has to be separated by a space. It's quite the same
way the Shell (OS9 interpreter) processes commands given to it.
.SH
THE L COMMAND
.PP
This command is used to disassemble instructions at the memory location
specified by the user. The two parameters are facultative i.e. if they're
not given the default values are used.
.sp
.PP
L {starting address} {Number of instructions}
.TS
tab (/);
l l .
L 300 #16/Disassemble 16 instructions at starting address $0300
L E000/Disassemble n instructions at starting address $E000
L/Disassemble n instructions following the last disassembled instruction
.TE
.TS
tab (/);
c c c c
l l l l .
Memory address/Mnemonic/Operand/# of cycles
_
A000 -/LDA/#$FF/~2
.TE
.SH
THE X COMMAND
.PP
This command is used to dump to the screen all 6809 registers. No parameters
are necessary.
.SH
THE . COMMAND
.PP
This commands enables the user to visualise or to modify a specified 6809
register. If no paramater is given then the content is displayed. This doesn't
affect the actual content of the register.
.PP
.{Registers} {Value}
.TS
tab (/);
l l .
.S 1000/Put value $1000 in S register
.A C/Put value $0C in Accumulator A
.X/Print content of X register
.TE
.SH
.ce
REGISTERS
.TS
center allbox tab(/);
c c c
c c l .
Register/Data/Type of register
A/8 bits/Accumulator
B/8 bits/Accumulator
CC/8 bits/Status Register
DP/8 bits/Direct page register
X/16 bits/Index register
Y/16 bits/Index register
U/16 bits/User stack
S/16 bits/System stack
.TE
.SH
THE FILL COMMAND
.PP
This command fills a specified block of memory with an 8 bit value. All
arguments are necessary. You specify the starting address, the ending address
and the value that fills the block. This is a potentially dangerous command
, initializing certain memory locations can bomb the system.
.LP
FILL {Starting Address} {Ending Address} {Value}
.TS
tab (/);
l l .
FILL C00 1FF9 #128/Fill memory between $0C00 and $1FF9 with $80
.TE
.SH
THE MOVE COMMAND
.PP
This command moves data from a block of memory to an another location.
.LP
MOVE {Destination Address} {Source Starting Address} {Source Ending Address}
.TS
tab (/);
l l .
MOVE 2000 3000 4000/Move block $3000 - $4000 to $2000
.TE
.SH
THE # and $ COMMAND
.PP
Those commands are used to perform HEX to DEC or DEC to HEX conversions. You
type the command and then the number WITHOUT A SPACE. The result is
printed on the screen.
.TS
tab (/);
l l .
#32768/Convert decimal number 32768 to Hexadecimal
$FFFF/Convert hexadecimal number $FFFF to decimal
.TE
.SH
THE S COMMAND
.PP
This command is used to perform simulation step by step starting at a given
memory location. Before using this command you can use the R command to link
to a module and then start simulating at the address of the entry point. The
Instruction is simulated and the content of all CPU registers are printed to
the screen. The instruction timing is also counted and cumulated with the
current value of the cycle counter. It is recommended to reset the counter to
zero before you start (see C command).
.sp
.EQ
delim %%
.EN
.EQ
T sub {total} = n sub {cycles} ~ times ~ CPU sub {clock}
.EN
.IP
Where %CPU sub {clock}% is % approx % 1.117 % mu secs% on a CoCo2 and 562 % eta secs% on a CoCo3.
.sp
.PP
OS9 system calls are not actually simulated, rather they're directly executed
by the CPU (Simulating system calls is not useful). Instructions like CWAI and
SYNC will wait for you to press the letter (on the keyboard) that will
simulate the interrupt you want: 'F' (firq), 'I' (irq) and 'N' (nmi). When the
proper letter is pressed the simulation will start at the address which is
contained in the interrupt vector ($FFF0 - $FFFF).
.sp
.LP
S {Entry point}
.IP
If {Entry point} is not given then the next instruction following the last
instruction executed is taken as the new address to begin simulation.
.TS
tab (/);
l l .
R simon/Link to a module
Start of module : $9500/
Entry point : $9580/
C 0/Reset counter to zero
S 9580/simulate first instruction
S/Next instruction
.sp
etc.../
.TE
.SH
THE T COMMAND
.PP
This command is similar to the S command Except that it will keep on simulating
as long as the break address is not reached. While the program executes it
displays all registers and cycle count for each simulated instruction. This
means that the screen will continuously scroll as the program executes but
you can disable the display by using the DSP command (If you don't need
the information T gives you) or you can simply stop the trace by pressing the 'S' key.
.LP
T {Starting address} {Ending address}
.TS
tab (/);
l l .
DSP ON/Enable display
C 0/Reset counter to zero
T 8756 87AF/Trace execution
.sp
DSP OFF/Disable display
C 0/Reset counter
T 8756 87AF/Do trace (Nothing is displayed)
C/Tell me how many cycles it took
.TE
.SH
THE DSP COMMAND
.PP
This command enable or disable the printing during the Trace command. It doesn't
affect the display for other commands.
.LP
DSP {ON or OFF}
.TS
tab (/);
l l .
DSP OFF/Disable display
DSP ON/Enable display
DSP/Without parameter tells display status (ON or OFF)
.TE
.SH
THE C COMMAND
.PP
This command lets you see/modify the value of the cycle counter.
.LP
C {value}
.TS
tab (/);
l l .
C/Without parameter displays value of counter in decimal
C 300/Put $0300 in counter (768 in Dec.)
C #1000/Put $03E8 in counter
.TE
.SH
THE R COMMAND
.PP
This command is used to link to a module in memory. The starting address and
the entry point in the module is printed on the screen.
.LP
R {ModuleName}
.SH
THE G COMMAND
.PP
This command lets the user execute a program directly by the CPU. You can
specify a breakpoint so you can return to SIMON and examine the registers. This
command is also useful for debuging code that has to be executed directly for
a real time application. It is to be noted that the program will return to
SIMON only if it encounters a RTS (if you don't specify a breakpoint).
.LP
G {Starting address} {Break address}
.TS
tab (/);
l l .
G 9580/Execute program at $9580
G 9580 95AF/Execute program at $9580 and break at $95AF
.TE
.SH
THE D COMMAND
.PP
This command is used to display memory on the screen with its HEX and ASCII
equivalent. A 32 column screen is assumed.
.LP
D {Starting address} {Ending address}
.SH
THE I COMMAND
.PP
This command lets you visualise and modify data contained in a specific
memory location. You can enter the data in decimal, hexadecimal and ASCII.
.LP
I {Adress}
.TS
tab (@);
l l .
I 9580@Modify data at $9580
@Typing '-' goes backward in memory
@Typing 'ENTER' goes forward in memory
@Typing 'Q' quits the I command
@Typing '/' puts you in modify mode
9580- 87 /1@Put $01 at $9580
9580- 87 /#10@Put $0A at $9580
9580- 87 /'A@Put ASCII character ($41) at $9580
@Press 'ENTER' to modify memory.
9581- CD@Next location
.TE
.SH
THE & COMMAND
.PP
This command lets you execute a command by the OS9 interpreter (shell).
.LP
&{command}
.TS
tab (/);
l l .
&dir/Execute DIR
&load attr/Load attr in memory
&/Goes to the shell, type 'CTRL' 'BREAK' to get back to SIMON
.TE
.SH
THE QUIT COMMAND
.PP
Exit to OS9.
-----------------------------------CUT HERE------------------------------------
--
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Benoit Archambault +
+ Universite de Montreal, Dep. I.R.O. Y-222, C.P. 6128, succursale A +
+ Montreal (Quebec) H3C 3J7, (514) 343-7480, archambe@iro.umontreal.ca +
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++