Usage guide

Summary: exor [options] [-0 disk0] [-1 disk1] [-2 disk2] [-3 disk3]

Options: --trace Produce instruction trace on stderr --dtrace Produce disk access trace on stderr --skip nnn Skip first nnn insns in trace --swtpc Simulate SWTPC instead of EXORciser --exbug name Give name for ROM if not 'exbug.bin'/'swtbug.bin' -x Go into EXBUG/SWTBUG instead of directly into MDOS/FLEX --facts file Process facts files for commented disassembly --lower Allow lowercase --mon Start at monitor prompt --lpt file Save line printer output to a file --append file Append line printer output to a file (default is listing.lp) --no_protect Allow writing to ROMs

Paths

Disk images are selected as follows:

If "-0 path" is given on the command line, then path is the location of the drive 0 disk image.
Otherwise if the environment variable EXOR_DRIVE0 (for exor) or EXOR09_DRIVE0 (for exor09) is given, it provides the location of the drive 0 disk image.
Otherwise mdos.dsk, flex.dsk, exor09.dsk or flex09.dsk is the default name, depending on which emulator you are running.

It's the same for the drive1 .. drive3, but there is no final default built-in name as there is for drive0.

Initial memory image is selected as follows:

The "--exbug" option supplies the path to the initial memory image. If it not given, then the environment variable EXOR_EXBUG or EXOR09_EXBUG is used. Otherwise the default is "exbug.bin".

For SWTPC (when the "--swtpc" option is given), "--exbug" supplies the path to the initial memory image. But if it is not set, then the environment variable EXOR_SWTBUG or EXOR09_SWTBUG is used. Otherwise the default is "swtbug.bin".

Debug "facts" file is selected as follows:

If "--facts path" is given, then path is the location of the "facts" file. If this option is not provided, then if the environment variable EXOR_FACTS or EXOR09_FACTS exists, it provides the path. Otherwise the default name is "facts" or "facts09".

To load MDOS from EXBUG, type MAID followed by E800;G

To load FLEX from SWTBUG, type D

For example, to simulate an EXORciser with exbug.bin and mdos.dsk in the current directory:


~/exor-1.0$ ./exor
Load facts file 'facts'
'exbug.bin' loaded.
'mdos.dsk' opened for drive 0 (single sided)

Hit Ctrl-C for simulator command line.  Starting simulation...

Floppy error: attempt to access non-existent disk 1

MDOS 03.00
=

To simulate SWTPC instead, run with the --swtpc option:


~/exor-1.0$ ./exor --swtpc
Load facts file 'facts'
'swtbug.bin' loaded.
'flex.dsk' opened for drive 0 (tracks=80 sectors=72)

Hit Ctrl-C for simulator command line.  Starting simulation...

FLEX 2.0

DATE (MM,DD,YY)? 02,07,11

+++

About exbug.bin and swtbug.bin

These memory images must each be exactly 64K bytes. They contain the initial memory image to be used by the simulator.

swtbug.bin contains SWTBUG at $E000 - $E3FF, but patched to boot the floppy to $A100 for FLEX2 instead of $2400 for miniFlex.

exbug.bin contains EXBUG at $F000 - $FBFF and the diskette controller at $E800 - $EBFF.

EXORsim inspects the image and detects either EXBUG-1.1 and EXBUG-1.2. If either of these is detected, the EXBUG INCH (input character) function is intercepted and emulated. If they are not detected, ACIA polling is used for input

I saved the images right at the point where the disk boot function is called so that EXORsim immediately boots the DOS instead of going into the monitor. This automatic booting is suppressed if EXBUG is not detected (for MDOS), or if the "-x" option is specified on the command line.

About diskette images

EXORsim supports two MDOS disk image formats:

Single sided: 2002 128-bit sectors, image size is 256,256 bytes (77 tracks of 26 sectors)
Double sided: 4004 128-bit sectors, image size is 512,512 bytes (154 tracks of 26 sectors)

EXORsim supports these eight FLEX image formats:

35 tracks of 10 sectors, image size is 89,600 bytes
40 tracks of 10 sectors, image size is 102,400 bytes
35 tracks of 20 sectors, image size is 179,200 bytes
40 tracks of 20 sectors, image size is 204,800 bytes
80 tracks of 18 sectors, image size is 368,640 bytes
80 tracks of 20 sectors, image size is 409,600 bytes
80 tracks of 36 sectors, image size is 737,280 bytes
80 tracks of 72 sectors, image size is 1,474,560 bytes

Monitor

To enter the debug monitor, hit Ctrl-C. The 128 instruction trace buffer will be displayed and then the monitor prompt is presented.


~/exor-1.0$ ./exor
Load facts file 'facts'
'exbug.bin' loaded.
'mdos.dsk' opened for drive 0 (single sided)

Hit Ctrl-C for simulator command line.  Starting simulation...

Floppy error: attempt to access non-existent disk 1

MDOS 03.00
=Interrupt!

- - - - - -

     610433 A=83 B=00 X=06A7 SP=E7EB ------          1B1E: EE 02    LDX 02,X  EA=06A9 D=0953 
     610434 A=83 B=00 X=0953 SP=E7EB ------          1B20: AD 0C    JSR 0C,X  EA=095F        

     610435 A=83 B=00 X=0953 SP=E7E9 ------          095F: 30       TSX                      
     610436 A=83 B=00 X=E7EA SP=E7E9 ------          0960: EE 00    LDX 00,X  EA=E7EA D=1B22 
     610437 A=83 B=00 X=1B22 SP=E7E9 ------          0962: EE 00    LDX 00,X  EA=1B22 D=1BE5 
     610438 A=83 B=00 X=1BE5 SP=E7E9 ------          0964: EE 00    LDX 00,X  EA=1BE5 D=0120 
     610439 A=83 B=00 X=0120 SP=E7E9 ------          0966: A6 01    LDA 01,X  EA=0121 D=83   
     610440 A=83 B=00 X=0120 SP=E7E9 --N---          0968: 2A 0B    BPL 0975  EA=0975        
     610441 A=83 B=00 X=0120 SP=E7E9 --N---          096A: 7C FF 53 INC FF53  EA=FF53(AECHO) 
     610442 A=83 B=00 X=0120 SP=E7E9 ------          096D: BD F0 15 JSR F015  EA=F015(INCHV) 

     610443 A=83 B=00 X=0120 SP=E7E7 ------ INCHV    F015: 7E FA A0 JMP FAA0  EA=FAA0(INCH)  Input char with echo (strip bit 7)
     610444 A=83 B=00 X=0120 SP=E7E7 ------ INCH     FAA0: 8D E9    BSR FA8B  EA=FA8B(INBYTE) Input character

     610445 ---- Subroutine at FA8B processed by simulator ---- RTS executed ---

>    610446 A=00 B=00 X=0120 SP=E7E7 ------          FAA2: 84 7F    ANDA #7F                 

Type 'help'
%

The '>' before the last line of the instruction trace indicates the current PC value, $FAA2 in this case. It's the next instruction to be executed if you step or continue.

You can hit Ctrl-C again to exit EXORsim.

Monitor commands

The follow commands are available:

q: Quit simulator
reset: Reset processor and continue simulating
abort: Abort (send NMI) to processor
t on: Turn tracing on
t off: Turn tracing off
c: Continue execution with current PC address
c hhhh: Continue execution, but with new PC address hhhh
s: Execute one instruction and return to monitor
s hhhh: Execute one instruction at new PC address hhhh and return to monitor
x hhhh: Call subroute at hhhh and return to monitor when it returns
b: Clear breakpoint
b hhhh: Set breakpoint at address hhhh
r: Show registers
r reg hhhh: Set register reg to hhhh
caps on: Force conversion to uppercase when simulation is running
caps off: Allow lower case letters to reach simulation
d hhhh [nnnn]: Hex dump beginning at hhhh of size nnnn
m hhhh: Modify memory beginning at hhhh
a hhhh: Assemble beginning at hhhh
u hhhh: Disassemble beginning at hhhh
u: Disassemble next 20 instructions
clr: Clear symbol table
sy: Show symbol table
p hhhh nnnn [ssss]: "Punch" (to paper tape) memory image in S19 format starting at hhhh, size nnnn. Put starting execution address ssss in S9 record.
l: Load (from paper tape) S19 formatted image into memory.
save: Save all 64K of memory in file called "dump"
save file: Save 64K of memory in file
save file start size: Save memory block in file
read: Read file "dump" into memory
read file: Read file into memory starting at 0
read file start: Read file into memory starting at start
poll on: Turn ACIA (serial port) polling on. This means that when the program reads the ACIA status register, the simulator will check for keyboard input and sleep for a few milliseconds.
poll off: Turn ACIA (serial port) polling off. This means that when the program reads the ACIA status register, the simulator will immediately indicate that input is available. When the program reads the data register, the simulator executes a blocking Linux read to get the character. In this way, less trace output is generated and less CPU time is used. However, some programs read from the ACIA data register even when no input is expected, so the simulation can sometimes appear to be stuck.

The above commands can be modified with redirection operators:

Append >file to redirect output to file

Append >>file to append output to file

Append <file to redirect input from file

Examples

Here is an example monitor session where we type in a program from the Motorola User's Group Library- no. 72 by Don L. Jackson, which computes integer square root:


~/exor-1.0$ ./exor --mon
Load facts file 'facts'
'exbug.bin' loaded.
'mdos.dsk' opened for drive 0 (single sided)

Hit Ctrl-C for simulator command line.  Starting simulation...
>         0 A=00 B=00 X=0000 SP=FF8A ------ OSLOAD   E800: 8E FF 8A LDS #$FF8A                Load OS

Type 'help'
% a 0		Assemble
0000:  NAM ISQRT
0000: *********************************************************
0000: * THIS SUBROUTINE CALCULATES THE INTEGER
0000: * SQUARE ROOT OF ANY POSITIVE NUMBER UP
0000: * TO 255 DECIMAL.  ENTER WITH NUMBER IN
0000: * ACCUMULATOR A, RESULT WILL BE RETURNED
0000: * IN ACCUMULATOR A.  B AND CC REGISTERS
0000: * ARE AFFECTED.  PROGRAM IS RELOCATABLE.
0000: *
0000: * PROGRAMMED BY DON L. JACKSON 11/27/76
0000: ***************************************************************
0000:  SPC 1
0000:  ORG $2100	Notice that ORG changes address
2100: ISQRT LDA B #$FF
2102: ISQRT2 ADD B #2
2104:  SBA
2105:  BCC ISQRT2
2107:  TBA
2108:  LSR A
2109:  RTS
210a:  SPC 1
210a:  END ISQRT
210a: 
% u 2100	Unassemble
2100: C6 FF               LDB #$FF
2102: CB 02               ADDB #$02
2104: 10                  SBA
2105: 24 FB               BCC $2102
2107: 17                  TBA
2108: 44                  LSRA
2109: 39                  RTS
210A: 00                  ???
210B: 00                  ???
210C: 00                  ???
210D: 00                  ???
210E: 00                  ???
210F: 00                  ???
2110: 00                  ???
2111: 00                  ???
2112: 00                  ???
2113: 00                  ???
2114: 00                  ???
2115: 00                  ???
2116: 00                  ???
2117: 00                  ???
2118: 00                  ???
% sy		Show symbol table
2102 ISQRT2
2100 ISQRT
% r a 19	Set register A to decimal 25
% t on		Enable tracing
% x 2100	Call subroutine
          0 A=19 B=00 X=0000 SP=FF8A ------ ISQRT    2100: C6 FF    LDB #FF   EA=2101 D=FF   
          1 A=19 B=FF X=0000 SP=FF8A --N--- ISQRT2   2102: CB 02    ADDB #02  EA=2103 D=02   
          2 A=19 B=01 X=0000 SP=FF8A H----C          2104: 10       SBA                      
          3 A=18 B=01 X=0000 SP=FF8A H-----          2105: 24 FB    BCC 2102  EA=2102(ISQRT2) 
          4 A=18 B=01 X=0000 SP=FF8A H----- ISQRT2   2102: CB 02    ADDB #02  EA=2103 D=02   
          5 A=18 B=03 X=0000 SP=FF8A ------          2104: 10       SBA                      
          6 A=15 B=03 X=0000 SP=FF8A ------          2105: 24 FB    BCC 2102  EA=2102(ISQRT2) 
          7 A=15 B=03 X=0000 SP=FF8A ------ ISQRT2   2102: CB 02    ADDB #02  EA=2103 D=02   
          8 A=15 B=05 X=0000 SP=FF8A ------          2104: 10       SBA                      
          9 A=10 B=05 X=0000 SP=FF8A ------          2105: 24 FB    BCC 2102  EA=2102(ISQRT2) 
         10 A=10 B=05 X=0000 SP=FF8A ------ ISQRT2   2102: CB 02    ADDB #02  EA=2103 D=02   
         11 A=10 B=07 X=0000 SP=FF8A ------          2104: 10       SBA                      
         12 A=09 B=07 X=0000 SP=FF8A ------          2105: 24 FB    BCC 2102  EA=2102(ISQRT2) 
         13 A=09 B=07 X=0000 SP=FF8A ------ ISQRT2   2102: CB 02    ADDB #02  EA=2103 D=02   
         14 A=09 B=09 X=0000 SP=FF8A ------          2104: 10       SBA                      
         15 A=00 B=09 X=0000 SP=FF8A ---Z--          2105: 24 FB    BCC 2102  EA=2102(ISQRT2) 
         16 A=00 B=09 X=0000 SP=FF8A ---Z-- ISQRT2   2102: CB 02    ADDB #02  EA=2103 D=02   
         17 A=00 B=0B X=0000 SP=FF8A ------          2104: 10       SBA                      
         18 A=F5 B=0B X=0000 SP=FF8A --N--C          2105: 24 FB    BCC 2102  EA=2102(ISQRT2) 
         19 A=F5 B=0B X=0000 SP=FF8A --N--C          2107: 17       TBA                      
         20 A=0B B=0B X=0000 SP=FF8A -----C          2108: 44       LSRA                     
         21 A=05 B=0B X=0000 SP=FF8A ----VC          2109: 39       RTS                      

>        22 A=05 B=0B X=0000 SP=FF8A ----VC          210A: 00       Huh?                     

Type 'help'
% r		Show answer in A...
PC=210A A=05 B=0B X=0000 SP=FF8A CC=C3
%

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

usage.md

usage.md

Usage guide

Paths

About exbug.bin and swtbug.bin

About diskette images

Monitor

Monitor commands

Examples

Files

usage.md

Latest commit

History

usage.md

File metadata and controls

Usage guide

Paths

About exbug.bin and swtbug.bin

About diskette images

Monitor

Monitor commands

Examples