BUGGY monitor readme.txt

MC6809 ASSEMBLER AND SIMULATOR.

These are the third version of the 6809 assembler and simulator.
Both compile currently under POSIX compatible Unix systems and
(with some porting) other systems.  The assembler should contain very
few system dependencies and should work under MS-DOS as well. 
The Unix version of the simulator depends on the POSIX header file termios.h.
Most modern Unix systems with ANSI C have this. 

THE ASSEMBER

The assembler is a09. Run it with

 a09 [-l listing] [-o object|-s object] source

Source is a mandatory argument. The -l listing and -o or -s object arguments are
optional. By default there is no listing and the object file is the
sourcefile name without an extension and if the source file name has no
extension it is the source file name with .b extension. 

A09 recognizes standard 6809 mnemonics. Labels should start in the first
column and may or may not be terminated by a colon. Every line starting with
a non-alphanumeric is taken to be a comment line. Everything after the
operand field is taken to be comment. There is a full expression evaluator
with C-style operators (and Motorola style number bases). 

There are the usual pseudo-ops such as ORG EQU SET SETDP RMB FCB FDB FCC etc. 
Strings within double quotes may be mixed with numbers on FCB lines. There 
is conditional assembly with IF/ELSE/ENDIF and there is INCLUDE. The
assembler is case-insensitive.

The object file is either a binary image file (-o) or Motorola S-records (-s).
In the former case it contains a binary image of the assembled data starting
at the first address where something is assembled. In the following case
 
	ORG 0
VAR1	RMB 2
VAR2	RMB 2

	ORG $100
START	LDS #$400
        ...

the RMB statements generate no data so the object file contains the memory
image from address $100.
     
The list file contains no pretty lay-out and no pagination. It is assumed
that utilities (Unix pr or enscript) are available for that.

There are no macros and no linkable modules yet. Some provisions are taken
for it in the code.

After the assembler has finished, it prints the number of pass 2 errors.
This should be zero. So if you see
  0 Pass 2 Errors.
then you are lucky.

THE SIMULATOR

The simulator is v09. Run it with
  v09 [-l loadaddr] [-r runaddr] [-t tracefile [-tl tracelo] [-th tracehi]]
      [-e escchar] imagefile

loadaddr runaddr tracelo and tracehi are addresses. They can be entered in
decimal, octal or hex using the C conventions for number input.

If a tracefile is specified, all instructions at addresses between
tracelo and tracehi are traced. Tracing information such as program
location, register contents and opcodes are written to the trace file.

escchar is the escape character. It must be entered as a number. This is
the character that you must type to get the v09 prompt. This is ^]
by default. (0x1d)

imagefile is the file that contains the binary image of the program. This is
the object file generated by a09.

By default the program is loaded at address 0x100 and it is run at the load
address.

At addresses $E000 and $E001 there is an emulated serial port (ACIA). All
bytes sent to it (or read from it) are send to (read from) the terminal and
sometimes to/from a file.
Terminal I/O is in raw mode.

If you press the escape char, you get the v09 prompt. At the prompt you
can enter the following things.
 
 X         to exit the simulator.
 R         to reset the emulated 6809 (very useful).
 Lfilename (no space in between) to log terminal output to a file.
           Control chars and cr are filtered to make the output a normal
           text file. L without a file name stops logging.
 Sfilename to send a specified file to the simulator through its terminal
           input. LF is converted to CR to mimic raw terminal input.
 Ufilename (terminal upload command) to send a file to the 6809 using the
	   X-modem protocol. The 6809 must already run an X-modem receiving
           program.
 Dfilename (terminal download command) to receive a file from the 6809 using
           the X-modem protocol. The 6809 must already run an X-modem
	   sending program.

THE MONITOR PROGRAM

To run the monitor program on the 6809 simulator you just type.

./v09 -l 0xe400 monitor

If all goes well you see something like

Welcome to BUGGY 1.0

and you can type text. Excellent, you are now running 6809 code.

The monitor program has the following single-letter commands.

Daddr,len  Hex/ascii dump of memory region.
Daddr      length=64 bytes by default.
D          address is address after previous dump.

Examples:
  DE400,100
Dump 256 bytes starting at $E400
  D
Dump the next 64 bytes.

Eaddr bytes Enter hexadecimal bytes at address.
Eaddr"ascii" Enter ascii at address.
Eaddr      Enter interactively at address (until empty line).

Examples:
  E0400 86449D033F
Enter the bytes 86 44 9D 03 3F at address $400. 
  E5000"Welcome"
Enter the ASCII codes of "Welcome" at address $400.


Faddr bytes   Find byte string or ascii string from address.
Faddr"ascii"

Find the specified string in memory, starting at the specified address. The
I/O addresses $E000-$E0FF are skipped. The addresses of the first 16
occurrences are shown.

Example
 FE400"SEX"
Search for the word "SEX" starting in the monitor.

Maddr1,addr2,len Move region of memory from addr1 to addr2. If addr2 is
                 1 higher than addr1, a region is filled. 
Example:
 M400,500,80
Move 128 bytes from address $400 to $500.

Sbytes     Enter Motorola S records.

S records are usually entered from a file, either ASCII transfer (S command
from the v09 prompt) or X-MODEM transfer (XX command in monitor, U command
from v09 prompt). Most Motorola cross assemblers generate S records. 

SSaddr,len  Dump memory region as Motorola S records.

These S records can be loaded later by the monitor program.

Usually you capture the S records into a file (use L command at v09 prompt)
or use XSS instead.
The XSS command is the same as SS, except that it outputs the S records
through the X-modem protocol (use D command at v09 prompt).

SOaddr    Set origin address for S-record transfer.

Before entering S records, it sets the first memory address where S records
will be loaded, regardless of the address contained in the S records.

Before the SS command, it sets the first address that will go into the S
records.

Examples.
  SO800
  S1130400etc...
Load the S records at address $800 even though the address in the S records
is $400
  SO8000
  SS400,100
Save the memory region of 256 bytes starting at $400 as S records. The S
records contain addresses starting at $8000.

Aaddr      Enter line-by-line assembler.

You are in the assembler until you make an error or until you enter an empty
line.

  A400
  LDB #$4B
  JSR $03
  SWI
  <empty line>

Uaddr,len  Disassemble memory region.
Uaddr      (disassemble 21 bytes)
U          

Examples:
  UE400,20
Diassemble first 32 bytes of monitor program.
  U
Disassemble next 21 bytes.

Baddr      Set/reset breakpoint at address.
B          Display active breakpoints.

Examples:
  B403
  B408
Set the breakpoints at the addresses $403 and $408.
  B
Show the breakpoints.
  B403
Remove the breakpoint at $403.

Jaddr      JSR to specified address.
Gaddr      Go to specified address.
G          Go to address in PC register.

The registers are loaded from where they are saved (on the stack) and at the
breakpoints SWI instructions are entered. Next the code is executed at the
indicated address. The SWI instruction (or RTS for the J command) returns to
the monitor, saving the registers.

Hexpr      Calculate simple expression in hex with + and -      

Examples:
  H4444+A5
  H4444-44F3

P         Put a temporary breakpoint after current instruction and exeucte it,

P is similar to T, because it usually executes one instruction and returns
to the monitor after it. That does not work for jumps though. Normally you
use P only with JSR instructions if you want to execute the whole subroutine
without single-stepping through it. Now that the T command is unimplemented,
P is the only single step command.

R         Register display.  
Rregvalue Enter new value into register Supported registers:
          X,Y,U,S,A,B,D(direct page),P(program counter),C(condition code).

The R command uses the saved register values (on the stack). There are some
restrictions on changing the S register.

Examples:
  R
Display all registers.
  RB03
  RP4444
Load the B register with $03 and the program counter with $4444

Tnum       Single step trace. UNIMPLEMENTED!!!!
T

Iaddr      Display the contents of the given address. (used to read input 
           port)

Example:
  IE001
Show the ACIA status.

XLaddr     Load binary data using X-modem protocol

Example:
  XL400
Type your escape character and at the v09 prompt type
  ubasic
to load the binary file "basic" at address $400.

XSaddr,len Save binary data using X-modem protocol.

Example:
  XS400,100
to save the memory region of 128 bytes starting at $400
Type your escape character and at the v09 prompt type:
  dfoo

Now the bytes are saved into the file "foo".

XSSaddr,len Save memory region as S records through X-modem protocol.

See SS command for more details.

XX         Execute commands received through X-modem protocol 
           This is usually used to receive S-records.  

Example:
 XX
Now type the escape character and at the v09 prompt type 
 usfile
where sfile is a file with S-records.

XOnl,eof   Set X-modem text output options, first number type of newline.
           1=LF,2=CR,3=CRLF, second number filler byte at end of file
           (sensible options include 0,4,1A) These options are used by
           the XSS command.

Example: Under a UNIX system you want X-modem's text output with just LF
         and a filler byte of 0. Type
      
         XO1,0

Apart from the monitor commands, the monitor program contains I/O routines
that can be used by applications started from it. 

The elementary routines are:
$00 getchar  Input one character into B register.
$03 putchar  Output one character in B register.
$06 getline  Input line at address in X, length in B.
$09 putline  Output string at address in X, length in B.
$0C putcr    Output a newline.

There are other routines that redirect these I/O operations through the
X-modem protocol.

EXAMPLE PROGRAMS

The following example programs you can run from the 6809 monitor.
All of them start at address $400. For example to run the program bin2dec
you type.

XL400

Then press your escape character (default is control-] ).

Then at the v09 prompt type 

ubin2dec

Now you see some lines displaying the progress of the X-modem session.
If that is finished, you type

G400

Now it runs and exits to the monitor with SWI, so that the registers are
displayed.  


cond09.asm
cond09.inc  Nonsense program to show conditional assembly and the like.

bench09.asm Benchmark program. Executes tight loop. Takes 83 secs on
            25 MHz 386. Should take about 8 sec. on 1MHz real 6809. :-(

test09.asm  Tests some nasty features of the 6809. Prints a few lines
            of PASSED nn and should never print ERROR nn.

bin2dec.asm Unusual way to convert numbers to decimal using DAA instruction.
            Prints some test numbers.

basic.asm Tiny BASIC by John Byrns. Docs are in basic.doc.
            To test it start the monitor and run basic.
	    
            Then press your escape char.
            At the v09 prompt type: sexampl.bas

	    Now a BASIC program is input.
	    Type RUN to run it.
	
	    Leave BASIC by pressing the escape char and entering x at the
	    prompt.
	    
kernel09 and the *.4 files. FORTH for the 6809. To run it, type
            XX
 
            Then press the escape char and at the v09 prompt type
 
            ukernel09
         
            Then type 

            G400
           
	    From FORTH type

            XLOAD

            Then press your escape char and at the v09 prompt type

            uextend09.4

            From FORTH type

            XLOAD

            Then press your escape char and at the v09 prompt type
   
            utetris.4

 	    From FORTH type

	    TT

            And play tetris under FORTH on the 6809!