exec09

This is a rewrite of Arto Salmi's 6809 simulator. Many changes have been made to it. This program remains licensed under the GNU General Public License.

Build and install

The instructions provided here apply to Linux and OS X / macOS. You will need make, gcc, aclocal, automake and probably some other stuff. On OS X and macOS, these can get installed with Macports by

    sudo port install readline autoconf automake

Files generated by autoconf, automake etc. are not included into this repository so you need to run

    autoreconf -vfi

once before the usual

    ./configure
    make
    sudo make install

There is one executable, m6809-run. You can install it (make install) or simply reference it explicitly.

To see configure options:

    ./configure --help

A typical configuation could look like this:

    ./configure --enable-6309 --enable-readline --prefix=/opt/gcc6809/

Enable readline libraries if you have them installed; this will allow you to use command-line recall and other shortcuts at the debugger command-line:

    ./configure --enable-readline
    make

If you'd like to keep the source directory clean from object files, it is also possible to build outside the source tree:

    mkdir build
    cd build
    ../configure
    make
    sudo make install

Machines

The simulator now has the notion of different 'machines': which says what types of I/O devices are mapped into the 6809's address space and how they can be accessed. Adding support for a new machine is fairly easy.

There are several machine types builtin:

• simple - assumes that you have a full 64KB of RAM, minus some input/output functions mapped at $FF00. If you compile a program with gcc6809 with no special linker option, you'll get an S-record file that is suitable for running on this machine. The S-record file will include a vector table at $FFF0, with a reset vector that points to a _start function, which will call your main() function. When main returns, _start writes to an 'exit register' at $FF01, which the simulator interprets and causes it to stop.

• kipper1 - a basic SBC with 32 KB RAM at $0000, 16 KB ROM at $C000 and 6850 ACIA based serial I/O at $A000,$A001

• eon (and eon2) - still in development, is called 'eon' (for Eight-O-Nine). It is similar to simple but has some more advanced I/O capabilities, like a larger memory space that can be paged in/out, and a disk emulation for programs that wants to have persistence. Refer to eon.h and eon2.c for more information.

• smii - The Scroungemaster II machine, a platform for 6809 CamelForth. Lots of RAM, MMU and serial I/O. See Brad Rodriguez http://www.camelforth.com/page.php?6 and http://www.bradrodriguez.com/papers/impov3.htm

• multicomp09 - a FPGA-based computer, described at https://github.com/nealcrook/multicomp6809/wiki

• wpc - an emulation of the Williams Pinball Controller which was the impetus for Brian Dominy working on the compiler in the first place.

Faults

gcc6809 also has a builtin notion of which addresses are used for text and data. The simple machine enforces this and will "fault" on invalid accesses.

Command-line options

Use --help to see the command-line options:

Motorola 6809 Simulator     Version 0.92
m6809-run [options] [program]

Options:
   -d, --debug           Enter the monitor immediately
   -h, --help            Show this help text
   -b, --binary
   -M, --mhz
   --68a09               Emulate the 68A09 variation (1.5Mhz)
   --68b09               Emulate the 68B09 variation (2Mhz)
   -R, --realtime        Limit simulation speed to match realtime
   -I, --tIckfreq        Automatically calls the machine's tick every so many cycles
   -C, --cycledump
   -o, --os9call         Treat SWI2 as an OS9/NitrOS9 system call and report postbyte
   -t, --loadmap
   -T, --trace
   -m, --maxcycles       Set maximum number of cycles to run (0 to disable)
   -s, --machine         Specify the machine (exact hardware) to emulate
   -p, --persistent      Use persistent machine state

Debugging

The simulator supports interactive debugging, similar to that provided by gdb, using the following commands:

Breakpoints

Set a breakpoint on EXECUTION at the given address. Eg:

    b <expr>
    break 0xf003

Ignore 4 times then break on 5th time:

    break 0xf000 ignore 4

Break if the S register has the value shown:

    break 0x1200 if <expr>
    break 0x1200 if $s==02:0x0043

Watchpoints

Set a watchpoint on WRITE to the given address. Each write to this address breaks and is reported:

    wa <expr>
    wa 0xf003

To report writes to this address report w/o stopping execution:

    wa 0xf003 print

Break and report on each write to this address only if the write data ANDed with the mask value is non-zero:

    wa 0xf003 mask 0x10

Set a watchpoint on READ from the given address. See examples above for wa.

    rwa <expr>

Set a watchpoint on ACCESS (read or write) at the given address. See examples above for wa.

    awa <expr>

List all breakpoints/watchpoints:

    bl

Delete a breakpoint/watchpoint:

    d <num>

Continue execution:

    c

Misc

    di <expr>

Add a display expression. The value of the expression is displayed any time that the CPU breaks. Eg:

    di $d $x $y

print current value of D X and Y registers each time the CPU breaks.

    dump

Save machine-specific state information to a file, typically named .dmp. The dump might be in readable or in binary format.

    dumpi <1 | 0>

Turn instruction dump on or off. With no argument, report the current instruction dump state (on or off). With instruction dump off, the 'c', 'n', 's' commands will report the last instruction that was executed before control returned to the prompt. With instruction dump on, those commands report each instruction as it is executed. Instruction dump is OFF by default.

    h or ?

Display help.

    l <expr>

List (disassemble) CPU instructions. Default is to start at the current value of the PC.

    me <expr>

Measure the amount of time that a function named by takes.

    n

Continue execution until the Next instruction is reached. If the current instruction is a call, then the debugger resumes after control returns.

    p [format] <expr>

Print the value of an expression. See 'Expressions' below. Eg:

    p/f <expr>

f specifies format. See below.

    p <expr>

use the previous format. f is the display format (default x for hex). Options:

      x X d u o a c s (match printf).

TODO: the code supports /u (unit) as well, but the b w options don't make any obvious difference to the output.

    pc <expr>

Set the CPU program counter to and list (disassemble) CPU instructions at that address.

    q

Quit the simulator.

    regs

Display the current value of the CPU registers.

    re

Reset the CPU/machine.

    restore

Restore machine state from a 'dump' file. NOT CURRENTLY IMPLEMENTED.

    runfor <number> [units]

Continue but break after a certain period of (simulated) time. The time can be expressed in ms (default) or s. The 'runfor' command cannot be nested; issuing a 'runfor' cancels any 'runfor that is in progress. Eg:

    runfor 100 ms
    runfor 1 s

runfor 0 gives a 'bad time value' error, but still cancels a 'runfor' in progress.

    s  <expr>

Step for a certain number of CPU instructions (1 by default).

    set <expr>
    set var <expr>

Sets the value of a location in target memory or the value of an internal variable. See 'Expressions' below for details on the syntax.

    so <file>

Run a set of debugger commands from another file. The commands may start/stop the CPU. When the commands are finished, control returns to the previous input source (the file that called it, or the keyboard.)

    sym <file>

Load a symbol table file named file.map -- Currently, the only format supported is an lwlink map file.

    td

Trace Dump. Display the last 256 instructions that were executed.

    vars

Show all program variables.

    x [format] <expr>

Examine target memory at the address . Eg:

    x/nfu addr

nfu specifies number, format, unit respectively. See below.

    x/nfu

continue from previous address, in new format.

    x addr

use previous format, continue from previous address.

    x

use previous format, continue from previous address.

n is the repeat count (default 1). It specifies how much memory (counting by units u to display. Display is formated multi-line if necessary.

f is the display format (default x for hex). Options:

    x X d u o a s (match printf) and i (instructions).

u is the unit size (default b for byte). Options:

    b (byte) w (word: 2 bytes)

The addr can be specified as an expression. Eg:

    x $pc
    x $pc+8

See 'Expressions' below.

    info

Describe machine, devices and address mapping.

Symbol Tables

Exec09 maintains variables, in 3 separate symbol tables:

• The program table. This is loaded automatically at startup or using the 'sym' command. The contents of this table is displayed by the 'vars' command. Entries in the program table are annotated onto 'list', 'step' and 'x' output.

• The auto table. The variables in this table are pre-defined. The following variables refer to CPU registers: pc a y u s d a b dp cc The following variables refer to simulator state: cycles - number of cycles since reset. et - number of cycles elapsed since et was last inspected. irqload - the average number of cycles spent in IRQ.

• The internal table. Variables are added to this table using the 'set var' command.

The three groups of variables behave in different ways:

Entries in the program table:

• converted to absolute address values when they are loaded.
• cannot be modified.
• new entries cannot be created interactively
• return either an address (their value) or the data at the addressed location, depending upon the context.

Eg: consider a variable 'start' referring to address 0x200. The byte at address 0x200 is 0xab.

Command	Comment
set start=5	changes the byte at address 0x200 from 0xab to 0x05.
print start	displays byte from location 0x200
print &start	displays 0x200
break start	breakpoint at 0x200
list start	list at 0x200
examine start	read/display memory at 0x200

Entries in the auto table:

• can be modified
• new entries cannot be created interactively
• a print always returns the value
• a set always changes the value (no memory read/write)

Entries in the internal table:

• can be created interactivelt using 'set var'
• can be modified
• are not converted to absolute address values
• return either an address (their value) or the data at the addressed location, depending upon the context.

Eg: consider the creation of a variable 'fred' from a pre-existing program variable 'start':

set var fred=&start+2

'fred' can now be used in exactly the same way as the examples above showed for 'start'.

Expressions

Many of the debug commands accept an expression. An expression is one or more numbers or variables, combined using operators. Eg: $pc+8

Depending on the context, an expression might be an rvalue or might be of the form lvalue=rvalue. In both cases, no white-space is allowed: the expression is silently truncated at the white-space, so that $pc + 8 is treated the same way as $pc.

The print command evalutes and displays the value of an rvalue and simultaneously creates an auto-table entry of the form $ where increments for each successive command. Eg:

$1 = 0x12
(dbg) print 2 + 4
$2 = 0x02
(dbg) print $1
$3 = 0x12

The values of these auto-table entries ($1, $2, $3 etc.) are static. Eg:

(dbg) print $pc
$4 = 0xE012
(dbg) step
02:0x0013 6EB1                  JMP   [,Y++]
(dbg) print $pc
$5 = 0xE013
(dbg) print $4
$6 = 0xE012

In this example, the 'print $4' returned the original value calculated, not the value resulting from the update of pc.

There are also two short-hand forms for referring to $ values:

$ refers to the most recent entry $$n refers to the value from n entries ago. $ is equivalent to $$0.

Eg:

(dbg) print 5
$0 = 0x05
(dbg) print 6
$1 = 0x06
(dbg) print 7
$2 = 0x07
(dbg) print 8
$3 = 0x08
(dbg) print $$2
$4 = 0x06
(dbg) print $
$5 = 0x06

The 'print' command also accepts an expression of the form lvalue=rvalue in which case it performs a memory store (like 'set') but also displays the value written. Eg:

(dbg) print 0=0xab
$60 = 0x00ab
(dbg) x/4X 0
01:0x0000                    : 0xAB 0xE5 0x1D 0x5A

The 'set' command can change memory and can create/change entries in the internal symbol table. Eg:

(dbg) x/4 0
01:0x0000                    : 0x00 0x00 0x00 0x00
(dbg) set 0=0x12
(dbg) set 3=0x1b
(dbg) x 0
01:0x0000                    : 0x12 0x00 0x00 0x1B
(dbg) set var fred=0x10000001
(dbg) x 0
01:0x0000                    : 0x12 0x00 0x00 0x1B
(dbg) print fred
$0 = 0x00
(dbg) set fred=0xab
(dbg) x 0
01:0x0000                    : 0x12 0xAB 0x00 0x1B
(dbg) print &fred
$1 = 0x10000001

If the lvalue is numeric, it is treated as an address and the result is a byte write to target memory. If the lvalue is a variable prefixed with '&' the result is an update to the variable's value.

Numbers are implicitly decimal. A leading 0 indicates an octal number and a leading 0x indicates a hex number.

The following operators are supported:

unary +, unary -, +, -, *, / == != &

Evaluation of expressions follows the usual rule that , / bind more tightly than +, - so that '4+37' evaluates to the same result as '3*7+4'.

The result of ==, != is 1 (true) or 0 (false).

The '&' is an indirection operator. &4 is the contents of address 4 in the target machine (however, this is of limited use because only byte access is supported).

The following expression errors are detected and reported:

• bad operator in expression
• bad lvalue
• bad rvalue
• non-existent symbol
• non-existent auto symbol
• bad numeric literal
• unrecognised $symbol in assignment
• missing assignment

However, the error-checking is not rigorous. In particular:

• an expression is silently truncated at first white-space
• an unrecognised operator is silently ignored
• set 3+1=9 does a write to location 4, but you cannot use arithmetic on the LHS with variables.
• an error in an assignment is reported but the assignment may have happened (Eg, to the wrong location or with the wrong value).

Authors

Arto Salmi              asalmi@ratol.fi
Joze Fabcic
Brian Dominy            brian@oddchange.com
Neal Crook              neal@pippaluk.org.uk
Nils Eilers             nils.eilers@gmx.de