Sunday, July 14, 2024

ALPP 01-06 -- Global Constants on the 6800, 6801, 6809, and 68000

Global Constants on the 6800, 6801, 6809, and 68000

(Title Page/Index)

 

So, now we have working environments set up for the 6800, 6809, 6801, and 68000,  and have taken a look at summing up a few small integer constants buried in the code on each of these processors.

Do you think having a list of numbers buried in the code might be a little clumsy? Just a little bit?

It is. Usually.

There are several ways to separate the numbers from the code that adds them. Let's take a look at one here, a way which we will call using global constants.

There are three related topics we will introduce here, in the process.

  • labels,
  • lists in memory
  • absolute addressing

And, while we're at it, you might want to think about object code size and execution time. We haven't taken up all the tools necessary to think about such things, but you might want to, anyway.

First, lets get the constants out of the code. 

In Motorola's 680X assemblers, the usual way to define a constant byte-sized integer is to use the FCB directive. You may think FCB stands for File Control Block, but in this context it means Form Constant Byte:

	FCB	8

We do not use "FCB #8" for two reasons. Well, three. One is that this is no longer immediate addressing. The other is that FCB is not an instruction for the microprocessor. It's a directive to the assembler. And the other other reason is that the assembler will complain if you do. Because of the first two reasons. And I promise this will make more sense later.

But it's not enough to have that small constant out there in memory somewhere. We need some way for the code to reference it. So we will give it a label, maybe call it BYTE8 (because it sounds cool or something):

BYTE8	FCB	8

You might remember the label START at the beginning of the code in our previous examples? It's basically the same thing in a slightly different context. 

This is quite literally just a label, a name by which a particular address in memory can be referenced.

Okay, here's the entire summing code for the 6800, using the separate constants:

ENTRY	JMP	START
*
BYTE8	FCB	8
BYTE5	FCB	5
BYTE2	FCB	2
BYTE7	FCB	7
BYTE4	FCB	4
*
START	LDAB	BYTE8
	ADDB	BYTE5
	ADDB	BYTE2
	ADDB	BYTE7	
	ADDB	BYTE4
	NOP
DONE	NOP	

Those asterisks at the start of those two lines are Motorola's way to show that the entire line is a comment. In this case, it's to make a deliberate empty line in the source code, to separate code from constants. It has zero effect in the object code.

That's a JuMP at label ENTRY. It jumps over the constants.

Is it necessary? 

Good question. 

:-)

Get a running EXORsim debugging session:

$ ./exor --mon
Load facts file 'facts'
'exbug.bin' loaded.
  EXBUG-1.1 detected
'mdos.dsk' opened for drive 0 (double sided)

OSLOAD...

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

>         0 A=00 B=00 X=0000 SP=00FF ------          0020: B6 E8 00 LDA E800                 

6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
%

Start an assembly at address $1000 and paste it in. Remember, right-click-paste to paste into the shell, because the shell thinks Ctrl-V means something else:

% a 1000
1000: ENTRY	JMP	START
1003: *
1003: BYTE8	FCB	8
1004: BYTE5	FCB	5
1005: BYTE2	FCB	2
1006: BYTE7	FCB	7
1007: BYTE4	FCB	4
1008: *
1008: START	LDAB	BYTE8
Address at 1001 set to 1008
100b: 	ADDB	BYTE5
100e: 	ADDB	BYTE2
1011: 	ADDB	BYTE7	
1014: 	ADDB	BYTE4
1017: 	NOP
1018: DONE	NOP	
1019: 

Disassemble it to see how it went:

% u 1000
1000: 7E 10 08            JMP $1008
1003: 08                  INX
1004: 05                  ???
1005: 02                  ???
1006: 07                  TPA
1007: 04                  ???
1008: F6 10 03            LDB $1003
100B: FB 10 04            ADDB $1004
100E: FB 10 05            ADDB $1005
1011: FB 10 06            ADDB $1006
1014: FB 10 07            ADDB $1007
1017: 01                  NOP
1018: 01                  NOP
1019: 00                  ???
101A: 00                  ???
...

Ackkkkkk! Where are the constants?!?!?!?!? And what is this INX and TPA and ????

If you don't jump over the constants, the processor will see that $08 as the op-code for the INcrement X instruction, and the $07 as the Transfer Processor status to A instruction. So that's what the disassembler shows you. And 5, 2, and 4 are not defined instructions, so the disassembler prints question marks.

And the processor, who knows what it would do?

(Interested geeks have researched this question. You can look it up if you are so inclined, but most undefined op-codes aren't all that interesting on the 6800.)

So. Maybe we do need that JMP instruction. Yes, we do. Sort of.

Now, since we are using the interactive debugger, we could just use the step or continue debugger command to tell it to start at address $1008. In fact, we could. We know that. 

But how does an operating system know that? How does someone who has neither the source code nor a debugger know what address to start at? I mean, without the source, here's all you have:

% d 1000
1000: 7E 10 08 08 05 02 07 04  F6 10 03 FB 10 04 FB 10 ~...............
1010: 05 FB 10 06 FB 10 07 01  01 00 00 00 00 00 00 00 ................
1020: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ................
...

So, on the one hand, no the JMP is not exactly necessary. On the other hand, it is a useful convention. We will use it, at least until we have something better.

So, set a breakpoint, turn trace on, and watch it do its stuff:

% b 1018
Breakpoint set at 1018
% t on
% c 1000

          9 A=00 B=1A X=0000 SP=00FF ------ ENTRY    1000: 7E 10 08 JMP 1008  EA=1008(START) 
         10 A=00 B=1A X=0000 SP=00FF ------ START    1008: F6 10 03 LDB 1003  EA=1003(BYTE8) D=08 
         11 A=00 B=08 X=0000 SP=00FF ------          100B: FB 10 04 ADDB 1004 EA=1004(BYTE5) D=05 
         12 A=00 B=0D X=0000 SP=00FF ------          100E: FB 10 05 ADDB 1005 EA=1005(BYTE2) D=02 
         13 A=00 B=0F X=0000 SP=00FF ------          1011: FB 10 06 ADDB 1006 EA=1006(BYTE7) D=07 
         14 A=00 B=16 X=0000 SP=00FF H-----          1014: FB 10 07 ADDB 1007 EA=1007(BYTE4) D=04 
         15 A=00 B=1A X=0000 SP=00FF ------          1017: 01       NOP                      

Breakpoint!
>        16 A=00 B=1A X=0000 SP=00FF ------ DONE     1018: 01       NOP                      

6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
% 

And we can see it adding those up in the B accumulator.

The 6801 version will be pretty much exactly the same, but go ahead and change directories to where you built my 6801-enabled version of EXORsim and run a session to prove it to yourself:

$ ./exor --6801 --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 1000
1000: ENTRY	JMP	START
1003: *
1003: BYTE8	FCB	8
Huh?: BYTE5	FCB	5
% 05: BYTE2	FCB	2
% 06: BYTE7	FCB	7
% 07: BYTE4	FCB	4
% 08: *
% 08: START	LDAB	BYTE8
% dress at 1001 set to 1008
% 0b: 	ADDB	BYTE5
% 0e: 	ADDB	BYTE2
% 11: 	ADDB	BYTE7	
% 14: 	ADDB	BYTE4
% 17: 	NOP
% 18: DONE	NOP	
% 19: 
% u 1000   
% 00: 7E 10 08            JMP $1008
% 03: 08                  INX
% 04: 05                  LSLD
% 05: 02                  ???
% 06: 07                  TPA
% 07: 04                  LSRD
% 08: F6 10 03            LDB $1003
% 0B: FB 10 04            ADDB $1004
% 0E: FB 10 05            ADDB $1005
% 11: FB 10 06            ADDB $1006
% 14: FB 10 07            ADDB $1007
% 17: 01                  NOP
% 18: 01                  NOP
% 19: 00                  ???
% 1A: 00                  ???
...

And so forth. 

One thing you'll notice is that, on the 6801, op-codes $05 and $04 are defined, whereas they are not on the 6800.

But we aren't using those, and even if you had a real 6801, even then, the timing would be the same. 

You may be wondering why I switched to using B to accumulate the sums here. As I mentioned in the chapter on getting started on the 6801, conventions on which accumulator was less significant switched between the 6800 and the 6809, and the 6801 follows the 6809 byte order in the D register instructions. But it follows the hard-wired 6800 stacking order during interrupts, to avoid too many surprises when re-using code from the 6800.

From here on out, we'll also be following the 6809 conventions on byte order where we can, not that you'll really notice it very often.

Now, let's see what happens on the 6809. In the first line of the code, change the LDAB to LDB:

ENTRY	JMP	START
...

The rest is the same source code.

Change back to Joe Allen's updated EXORsim and run a 6809 session. Paste in the code, making sure the LDAB is changed to LDB:

$ ./exor09 --mon
Load facts file 'facts09'
'exbug09.bin' loaded.
  EXBUG09-2.1 detected
'mdos09.dsk' opened for drive 0 (double sided)

OSLOAD...

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

>         0 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            0020: 86 10        LDA #$10                   

6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
% a 1000
1000: ENTRY	JMP	START
later = 1001
1003: *
1003: BYTE8	FCB	8
1004: BYTE5	FCB	5
1005: BYTE2	FCB	2
1006: BYTE7	FCB	7
1007: BYTE4	FCB	4
1008: *
1008: START	LDB	BYTE8
Address at 1001 set to 1008
100b: 	ADDB	BYTE5
100e: 	ADDB	BYTE2
1011: 	ADDB	BYTE7	
1014: 	ADDB	BYTE4
1017: 	NOP
1018: DONE	NOP	
1019: 
% u 1000
1000: 7E 1008             JMP $1008
1003: 08 05               ASL $05
1005: 02 07               ??? $07
1007: 04 F6               LSR $f6
1009: 1003 FB             COM $fb
100C: 1004 FB             LSR $fb
100F: 1005 FB             ??? $fb
1012: 1006 FB             ROR $fb
1015: 1007 12             ASR $12
1018: 12                  NOP 
1019: 00 00               NEG $00
101B: 00 00               NEG $00
...

YIKES! 

Oh. The op-code map is a little different on the 6809, and our small constant integers are actually two-byte op-codes instead of one-byte -- which throws the disassembly off at address $1007.

Easy. We can note that the JMP at ENTRY is to address $1008, and disassemble from there:

% u 1008
1008: F6 1003             LDB $1003
100B: FB 1004             ADDB $1004
100E: FB 1005             ADDB $1005
1011: FB 1006             ADDB $1006
1014: FB 1007             ADDB $1007
1017: 12                  NOP 
1018: 12                  NOP 
1019: 00 00               NEG $00
101B: 00 00               NEG $00
...

Okay, the op-codes are a little bit different in places, but that doesn't hurt us.

% b 1018
Breakpoint set at 1018
% t on
% c 1000

          0 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 -------- ENTRY      1000: 7E 1008      JMP $1008                  
          1 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 -------- START      1008: F6 1003      LDB $1003   EA=1003(BYTE8) D=08 
          2 A=00 B=08 X=0000 Y=0000 U=0000 S=00FF P=00 --------            100B: FB 1004      ADDB $1004  EA=1004(BYTE5) D=05 
          3 A=00 B=0D X=0000 Y=0000 U=0000 S=00FF P=00 --------            100E: FB 1005      ADDB $1005  EA=1005(BYTE2) D=02 
          4 A=00 B=0F X=0000 Y=0000 U=0000 S=00FF P=00 --------            1011: FB 1006      ADDB $1006  EA=1006(BYTE7) D=07 
          5 A=00 B=16 X=0000 Y=0000 U=0000 S=00FF P=00 --H-----            1014: FB 1007      ADDB $1007  EA=1007(BYTE4) D=04 
          6 A=00 B=1A X=0000 Y=0000 U=0000 S=00FF P=00 --------            1017: 12           NOP                        

Breakpoint!
>         7 A=00 B=1A X=0000 Y=0000 U=0000 S=00FF P=00 -------- DONE       1018: 12           NOP                        

6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
%  

The 6809 version works exactly the same.

So we should be able to move on to the 68000. 

Except.

The 6809

      has

            something called PC-relative addressing.

OHHHHHHHH HORRORS!!!!

8-o

;->

Take a look at the disassembly in the code above. Where immediate mode addressing buried the actual constants in the code, you'll see the addresses of the constants buried in the code.

	LDB	BYTE8

becomes

F6 1003 

if you start the assembly at $1000.

But if you start the assembly at $1100, BYTE8 will become a label for $1108, and the object code will assemble as "FB 1103".

Which means that, once you have assembled the code, you can't just copy the code somewhere else to run it. You have to do something called relocation, where you dig through every address in the object code and adjust it for where it want it to end up.

Relocation is not as hard as it sounds. Sort-of. (Gurgle. Cough. Sigh.) Once you know what assumptions you can make. Which ...

We don't want to go there just yet.

PC-relative code can be moved without relocation math. Which is why it is called position-independent, or, sometimes, "relocatable". Erk.

We'll talk about this more later, but right now I think we should take a quick advance look at it.

Here's how PC relative code for the global constants looks for the code above:

ENTRY	JMP	START
*
BYTE8	FCB	8
BYTE5	FCB	5
BYTE2	FCB	2
BYTE7	FCB	7
BYTE4	FCB	4
*
START	LDB	BYTE8,PCR    ; address relative to PC
	ADDB	BYTE5,PCR
	ADDB	BYTE2,PCR
	ADDB	BYTE7,PCR
	ADDB	BYTE4,PCR
	NOP
DONE	NOP

Quit your EXORsim 6809 session and start a fresh one, and paste the above code in.

$ ./exor09 --mon
Load facts file 'facts09'
'exbug09.bin' loaded.
  EXBUG09-2.1 detected
'mdos09.dsk' opened for drive 0 (double sided)

OSLOAD...

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

>         0 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            0020: 86 10        LDA #$10                   

6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
% a 1000
1000: ENTRY	JMP	START
later = 1001
1003: *
1003: BYTE8	FCB	8
1004: BYTE5	FCB	5
1005: BYTE2	FCB	2
1006: BYTE7	FCB	7
1007: BYTE4	FCB	4
1008: *
1008: START	LDB	BYTE8,PCR
Address at 1001 set to 1008
100b: 	ADDB	BYTE5,PCR
100e: 	ADDB	BYTE2,PCR
1011: 	ADDB	BYTE7,PCR
1014: 	ADDB	BYTE4,PCR
1017: 	NOP
1018: DONE	NOP
1019: 
% u 1000
1000: 7E 1008             JMP $1008
1003: 08 05               ASL $05
1005: 02 07               ??? $07
1007: 04 E6               LSR $e6
1009: 8C F8EB             CMPX #$f8eb
100C: 8C F6EB             CMPX #$f6eb
100F: 8C F4EB             CMPX #$f4eb
1012: 8C F2EB             CMPX #$f2eb
1015: 8C F012             CMPX #$f012
1018: 12                  NOP 
1019: 00 00               NEG $00
101B: 00 00               NEG $00
...
% u 1008 1008: E6 8C F8 LDB $1003,PCR 100B: EB 8C F6 ADDB $1004,PCR 100E: EB 8C F4 ADDB $1005,PCR 1011: EB 8C F2 ADDB $1006,PCR 1014: EB 8C F0 ADDB $1007,PCR 1017: 12 NOP 1018: 12 NOP 1019: 00 00 NEG $00 101B: 00 00 NEG $00 ...
% b 1018 Breakpoint set at 1018 % t on % c 1000 0 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 -------- ENTRY 1000: 7E 1008 JMP $1008 1 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 -------- START 1008: E6 8C F8 LDB $1003,PCR EA=1003(BYTE8) D=08 2 A=00 B=08 X=0000 Y=0000 U=0000 S=00FF P=00 -------- 100B: EB 8C F6 ADDB $1004,PCR EA=1004(BYTE5) D=05 3 A=00 B=0D X=0000 Y=0000 U=0000 S=00FF P=00 -------- 100E: EB 8C F4 ADDB $1005,PCR EA=1005(BYTE2) D=02 4 A=00 B=0F X=0000 Y=0000 U=0000 S=00FF P=00 -------- 1011: EB 8C F2 ADDB $1006,PCR EA=1006(BYTE7) D=07 5 A=00 B=16 X=0000 Y=0000 U=0000 S=00FF P=00 --H----- 1014: EB 8C F0 ADDB $1007,PCR EA=1007(BYTE4) D=04 6 A=00 B=1A X=0000 Y=0000 U=0000 S=00FF P=00 -------- 1017: 12 NOP Breakpoint! > 7 A=00 B=1A X=0000 Y=0000 U=0000 S=00FF P=00 -------- DONE 1018: 12 NOP 6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help' % q Bye

And, even though we only see the offsets in the code, the processor found the constants and was able to add them up.

We'll try more interesting things with this idea later. For now, file it away, and let's move on to the 68000 version of this. The code for absolute addressing first:

	OPT LIST,SYMTAB	; Options we want for the stand-alone assembler.
	MACHINE MC68000	; because there are a lot the assembler can do.
	OPT DEBUG	; We want the debugger to know our labels.
	OUTPUT
***********************************************************************
*	EVEN		; byte data doesn't have to be aligned.
ENTRY	JMP	START
*
BYTE8	DC.B	8
BYTE5	DC.B	5
BYTE2	DC.B	2
BYTE7	DC.B	7
BYTE4	DC.B	4
*
	EVEN		; But 68K code does have to be even aligned.
START	MOVE.B	BYTE8,D1
	ADD.B	BYTE5,D1
	ADD.B	BYTE2,D1
	ADD.B	BYTE7,D1
	ADD.B	BYTE4,D1
	NOP
DONE	NOP
* One way to return to the OS or other calling program
	clr.w	-(sp)	; there should be enough room on the caller's stack
	trap	#1			quick exit

Note that, instead of 

Form Constant Byte (FCB), 

the 68000 uses 

Define Constant Byte (DC.B).

Also notice that I've added a little formal quitting code at the end. And that's another something to talk about later.

I'm saving the source code as sumconst.s under in the working directory I made under the Hatari C drive emulation directory. In the above example, that would be

~/asmwork/share/hatari/C/primer/sumconst.s

And I'm assembling it with

$ vasmm68k_mot -Ftos -o SUMCONST.PRG -L sumconst.lst sumconst.s

Here's the listing it produces:

Sections:
00: "text" (0-24)


Source: "sumconst.s"
                            	     1: 	OPT LIST,SYMTAB	; Options we want for the stand-alone assembler.
                            	     2: 	MACHINE MC68000	; because there are a lot the assembler can do.
                            	     3: 	OPT DEBUG	; We want the debugger to know our labels.
                            	     4: 	OUTPUT
                            	     5: ***********************************************************************
                            	     6: *	EVEN		; byte data doesn't have to be aligned.
00:00000000 6006            	     7: ENTRY	JMP	START
                            	     8: *
00:00000002 08              	     9: BYTE8	DC.B	8
00:00000003 05              	    10: BYTE5	DC.B	5
00:00000004 02              	    11: BYTE2	DC.B	2
00:00000005 07              	    12: BYTE7	DC.B	7
00:00000006 04              	    13: BYTE4	DC.B	4
                            	    14: *
                            	    15: 	EVEN		; But 68K code does have to be even aligned.
00:00000008 123AFFF8        	    16: START	MOVE.B	BYTE8,D1
00:0000000C D23AFFF5        	    17: 	ADD.B	BYTE5,D1
00:00000010 D23AFFF2        	    18: 	ADD.B	BYTE2,D1
00:00000014 D23AFFEF        	    19: 	ADD.B	BYTE7,D1
00:00000018 D23AFFEC        	    20: 	ADD.B	BYTE4,D1
00:0000001C 4E71            	    21: 	NOP
00:0000001E 4E71            	    22: DONE	NOP
                            	    23: * One way to return to the OS or other calling program
00:00000020 4267            	    24: 	clr.w	-(sp)	; there should be enough room on the caller's stack
00:00000022 4E41            	    25: 	trap	#1			quick exit

If you know how to read the op-codes, you'll notice that the assembler seems to be doing something you're not expecting. Let's check.

Get Hatari running, Ctrl-Z to escape GEM and get a TOS (CP/M) shell, Alt-Pause to enter the debugger, use the mouse to bring up the host shell you started Hatari in, and set the breakpoint (b) to break when the CPU jumps to the TEXT segment, then do a continue (c) to return to the TOS (CP/M) shell:

CPU condition breakpoint 1 with 1 condition(s) added:
	pc = TEXT
-> Break only once, and delete breakpoint afterwards.
> c
Returning to emulation...

Invoke the assembled code in the TOS shell:

C:\primer>SUMCONST.PRG

Use the mouse to get back to the host shell where the debugger has taken the break and is waiting for you. Disassemble (d):

> d
(PC)
ENTRY:
00013d10 6006                     bra.b #$06 == $00013d18 (T)
BYTE8:
00013d12 0805 0207                btst.l #$0207,d5
BYTE4:
00013d16 0400 123a                sub.b #$3a,d0
00013d1a fff8                     illegal 
00013d1c d23a fff5                add.b (pc,$fff5) == $00013d13 [05],d1
00013d20 d23a fff2                add.b (pc,$fff2) == $00013d14 [02],d1
00013d24 d23a ffef                add.b (pc,$ffef) == $00013d15 [07],d1
00013d28 d23a ffec                add.b (pc,$ffec) == $00013d16 [04],d1
00013d2c 4e71                     nop 
DONE:
00013d2e 4e71                     nop 
00013d30 4267                     clr.w -(a7) [0000]
00013d32 4e41                     trap #$01
00013d34 0000 0000                or.b #$00,d0
00013d38 0000 0000                or.b #$00,d0
...

Didn't remember a BRAnch instruction?

My neither. That was supposed to be a JuMP.

It's getting confused trying to disassemble constants as code, so look at the target for the branch ($00013d18) and disassemble from there. Except you forgot that the Hatari debugger expects decimal unless you tell it otherwise. So you try again, typing it in as proper hexadecimal:

> d 13d18
Extra characters in decimal based number '13d18'!
Invalid address value '13d18'!
> d $13d18
START:
00013d18 123a fff8                move.b (pc,$fff8) == $00013d12 [08],d1
00013d1c d23a fff5                add.b (pc,$fff5) == $00013d13 [05],d1
00013d20 d23a fff2                add.b (pc,$fff2) == $00013d14 [02],d1
00013d24 d23a ffef                add.b (pc,$ffef) == $00013d15 [07],d1
00013d28 d23a ffec                add.b (pc,$ffec) == $00013d16 [04],d1
00013d2c 4e71                     nop 
DONE:
00013d2e 4e71                     nop 
00013d30 4267                     clr.w -(a7) [0000]
00013d32 4e41                     trap #$01
00013d34 0000 0000                or.b #$00,d0
00013d38 0000 0000                or.b #$00,d0
...
>

Twilight Zone ? (Cue creepy music.)

LoL. Optimization. It's using the PC relative modes because they take fewer bytes. We wanted to do that later, but we wanted to do that explicitly. Not yet. Not here.

This is one of the reasons I was hesitant to use vasm.

Sigh. Well, there are switches to turn optimizations off. Not really a problem.

I'd go ahead and step through the optimized code, but we want to do that in a few more minutes, with explicit code. So, for now, let's (q)uit out of the debugger and Hatari and try again:

$ vasmm68k_mot -Ftos -no-opt -o SUMCONST.PRG -L sumconst.lst sumconst.s

Here's the listing it produces with the no-opts switch:

Sections:
00: "text" (0-32)


Source: "sumconst.s"
                            	     1: 	OPT LIST,SYMTAB	; Options we want for the stand-alone assembler.
                            	     2: 	MACHINE MC68000	; because there are a lot the assembler can do.
                            	     3: 	OPT DEBUG	; We want the debugger to know our labels.
                            	     4: 	OUTPUT
                            	     5: ***********************************************************************
                            	     6: *	EVEN		; byte data doesn't have to be aligned.
00:00000000 4EF90000000C    	     7: ENTRY	JMP	START
                            	     8: *
00:00000006 08              	     9: BYTE8	DC.B	8
00:00000007 05              	    10: BYTE5	DC.B	5
00:00000008 02              	    11: BYTE2	DC.B	2
00:00000009 07              	    12: BYTE7	DC.B	7
00:0000000A 04              	    13: BYTE4	DC.B	4
                            	    14: *
                            	    15: 	EVEN		; But 68K code does have to be even aligned.
00:0000000C 123900000006    	    16: START	MOVE.B	BYTE8,D1
00:00000012 D23900000007    	    17: 	ADD.B	BYTE5,D1
00:00000018 D23900000008    	    18: 	ADD.B	BYTE2,D1
00:0000001E D23900000009    	    19: 	ADD.B	BYTE7,D1
00:00000024 D2390000000A    	    20: 	ADD.B	BYTE4,D1
00:0000002A 4E71            	    21: 	NOP
00:0000002C 4E71            	    22: DONE	NOP
                            	    23: * One way to return to the OS or other calling program
00:0000002E 4267            	    24: 	clr.w	-(sp)	; there should be enough room on the caller's stack
00:00000030 4E41            	    25: 	trap	#1			quick exit
                            	    26: 
                            	    27: 
                            	    28: 


Symbols by name:
BYTE2                           00:00000008
BYTE4                           00:0000000A
BYTE5                           00:00000007
BYTE7                           00:00000009
BYTE8                           00:00000006
DONE                            00:0000002C
ENTRY                           00:00000000
START                           00:0000000C

Symbols by value:
00000000 ENTRY
00000006 BYTE8
00000007 BYTE5
00000008 BYTE2
00000009 BYTE7
0000000A BYTE4
0000000C START
0000002C DONE  

That looks much better. Let's get it into the debugger. 

Again, 

  1. Start Hatari.
  2. When the GUI comes up, use Ctrl-Z to break out of GEM into the TOS command line shell.
  3. Change to the primer directory:
    C:\>CD PRIMER
    C:\primer>
  4. Use Alt-PAUSE to break out of TOS shell into the debugger.
  5. Set a PC breakpoint at the beginning of the TEXT segment:
    >b pc = TEXT :once
  6. (c)ontinue back to TOS shell.
  7. Invoke the executable created by the assembler:
    C:\primer>SUMCONST.PRG

Then we can

  • (d)isassemble the code (from START this time)
  • (m)emory dump (notice I'm using the count argument this time)
  • and alternate
    • (r)egister dump
    • (s)tep
  • until we hit the landing pad

as follows:

    ----------------------------------------------------------------------
    You have entered debug mode. Type c to continue emulation, h for help.
    
    CPU=$e1d7e2, VBL=1385, FrameCycles=128, HBL=0, LineCycles=128, DSP=N/A
    00e1d7e2 46c0                     move.w d0,sr
    > b pc = TEXT :once
    CPU condition breakpoint 1 with 1 condition(s) added:
    	pc = TEXT
    -> Break only once, and delete breakpoint afterwards.
    > c
    Returning to emulation...
    1. CPU breakpoint condition(s) matched 1 times.
    	pc = TEXT :once
    Removed CPU breakpoint 1:
    	pc = TEXT :once
    Reading symbols from program '/home/nova/usr/share/hatari/C:/primer/SUMCONST.PRG' symbol table...
    TOS executable, DRI / GST symbol table, reloc=0, program flags: PRIVATE (0x0)
    Program section sizes:
      text: 0x32, data: 0x0, bss: 0x0, symtab: 0x70
    Trying to load DRI symbol table at offset 0x4e...
    Offsetting BSS/DATA symbols from TEXT section.
    Skipping duplicate address & symbol name checks when autoload is enabled.
    Loaded 8 symbols (8 TEXT) from '/home/nova/usr/share/hatari/C:/primer/SUMCONST.PRG'.
    
    CPU=$13d10, VBL=2479, FrameCycles=63376, HBL=62, LineCycles=384, DSP=N/A
    00013d10 4ef9 0001 3d1c           jmp $00013d1c
    > d $13d1c
    START:
    00013d1c 1239 0001 3d16           move.b $00013d16 [08],d1
    00013d22 d239 0001 3d17           add.b $00013d17 [05],d1
    00013d28 d239 0001 3d18           add.b $00013d18 [02],d1
    00013d2e d239 0001 3d19           add.b $00013d19 [07],d1
    00013d34 d239 0001 3d1a           add.b $00013d1a [04],d1
    00013d3a 4e71                     nop 
    DONE:
    00013d3c 4e71                     nop 
    00013d3e 4267                     clr.w -(a7) [0000]
    00013d40 4e41                     trap #$01
    00013d42 0000 0000                or.b #$00,d0
    00013d46 0000 0000                or.b #$00,d0
    ...
    > m $13d10 64
    00013D10: 4e f9 00 01 3d 1c 08 05 02 07 04 00 12 39 00 01   N...=........9..
    00013D20: 3d 16 d2 39 00 01 3d 17 d2 39 00 01 3d 18 d2 39   =..9..=..9..=..9
    00013D30: 00 01 3d 19 d2 39 00 01 3d 1a 4e 71 4e 71 42 67   ..=..9..=.NqNqBg
    00013D40: 4e 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00   NA..............
    > r               
      D0 00000000   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D42   A5 00013D42   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 4ef9 (JMP) 0001 (OR) Chip latch 00000000
    00013d10 4ef9 0001 3d1c           jmp $00013d1c
    Next PC: 00013d16
    > s
    
    CPU=$13d1c, VBL=2479, FrameCycles=63388, HBL=62, LineCycles=396, DSP=N/A
    00013d1c 1239 0001 3d16           move.b $00013d16 [08],d1
    > r
      D0 00000000   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D42   A5 00013D42   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 1239 (MOVE) 0001 (OR) Chip latch 00000000
    00013d1c 1239 0001 3d16           move.b $00013d16 [08],d1
    Next PC: 00013d22
    > s
    
    CPU=$13d22, VBL=2479, FrameCycles=63404, HBL=62, LineCycles=412, DSP=N/A
    00013d22 d239 0001 3d17           add.b $00013d17 [05],d1
    > r
      D0 00000000   D1 00000008   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D42   A5 00013D42   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch d239 (ADD) 0001 (OR) Chip latch 00000000
    00013d22 d239 0001 3d17           add.b $00013d17 [05],d1
    Next PC: 00013d28
    > s
    
    CPU=$13d28, VBL=2479, FrameCycles=63420, HBL=62, LineCycles=428, DSP=N/A
    00013d28 d239 0001 3d18           add.b $00013d18 [02],d1
    > r
      D0 00000000   D1 0000000D   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D42   A5 00013D42   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch d239 (ADD) 0001 (OR) Chip latch 00000000
    00013d28 d239 0001 3d18           add.b $00013d18 [02],d1
    Next PC: 00013d2e
    > s
    
    CPU=$13d2e, VBL=2479, FrameCycles=63436, HBL=62, LineCycles=444, DSP=N/A
    00013d2e d239 0001 3d19           add.b $00013d19 [07],d1
    > r
      D0 00000000   D1 0000000F   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D42   A5 00013D42   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch d239 (ADD) 0001 (OR) Chip latch 00000000
    00013d2e d239 0001 3d19           add.b $00013d19 [07],d1
    Next PC: 00013d34
    > s
    
    CPU=$13d34, VBL=2479, FrameCycles=63452, HBL=62, LineCycles=460, DSP=N/A
    00013d34 d239 0001 3d1a           add.b $00013d1a [04],d1
    > r
      D0 00000000   D1 00000016   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D42   A5 00013D42   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch d239 (ADD) 0001 (OR) Chip latch 00000000
    00013d34 d239 0001 3d1a           add.b $00013d1a [04],d1
    Next PC: 00013d3a
    > s
    
    CPU=$13d3a, VBL=2479, FrameCycles=63468, HBL=62, LineCycles=476, DSP=N/A
    00013d3a 4e71                     nop 
    

    At this point, we can either (q)uit the whole Hatari session, or, since I have added that extra code that allows us to return to what called us, (c) and go back to the TOS shell.

    Why did I put the sum in D1 this time instead of D0? Good question. If we make a really fine point of it, I could have kept the sum in D7, instead. LoL. We have lots of registers in the 68000, and which one might correspond to B is just a matter of convention -- although there is stack order, and, in the 68020, there are 64-bit results that are put in register pairs, so ...

    But let's look at what happens when we (explicitly this time) use PC relative addressing. Here's the code:

    	OPT LIST,SYMTAB	; Options we want for the stand-alone assembler.
    	MACHINE MC68000	; because there are a lot the assembler can do.
    	OPT DEBUG	; We want labels for debugging.
    	OUTPUT
    ***********************************************************************
    *	EVEN		; byte data doesn't have to be aligned.
    ENTRY	JMP	START
    *
    BYTE8	DC.B	8
    BYTE5	DC.B	5
    BYTE2	DC.B	2
    BYTE7	DC.B	7
    BYTE4	DC.B	4
    *
    	EVEN		; But 68K code does have to be even aligned.
    START	MOVE.B	BYTE8(PC),D1
    	ADD.B	BYTE5(PC),D1
    	ADD.B	BYTE2(PC),D1
    	ADD.B	BYTE7(PC),D1
    	ADD.B	BYTE4(PC),D1
    	NOP
    DONE	NOP
    * One way to return to the OS or other calling program
    	clr.w	-(sp)	; there should be enough room on the caller's stack
    	trap	#1			quick exit
    

    and the listing file:

    Sections:
    00: "text" (0-28)
    
    
    Source: "sumconpc.s"
                                	     1: 	OPT LIST,SYMTAB	; Options we want for the stand-alone assembler.
                                	     2: 	MACHINE MC68000	; because there are a lot the assembler can do.
                                	     3: 	OPT DEBUG	; We want labels for debugging.
                                	     4: 	OUTPUT
                                	     5: ***********************************************************************
                                	     6: *	EVEN		; byte data doesn't have to be aligned.
    00:00000000 4EF90000000C    	     7: ENTRY	JMP	START
                                	     8: *
    00:00000006 08              	     9: BYTE8	DC.B	8
    00:00000007 05              	    10: BYTE5	DC.B	5
    00:00000008 02              	    11: BYTE2	DC.B	2
    00:00000009 07              	    12: BYTE7	DC.B	7
    00:0000000A 04              	    13: BYTE4	DC.B	4
                                	    14: *
                                	    15: 	EVEN		; But 68K code does have to be even aligned.
    00:0000000C 123AFFF8        	    16: START	MOVE.B	BYTE8(PC),D1
    00:00000010 D23AFFF5        	    17: 	ADD.B	BYTE5(PC),D1
    00:00000014 D23AFFF2        	    18: 	ADD.B	BYTE2(PC),D1
    00:00000018 D23AFFEF        	    19: 	ADD.B	BYTE7(PC),D1
    00:0000001C D23AFFEC        	    20: 	ADD.B	BYTE4(PC),D1
    00:00000020 4E71            	    21: 	NOP
    00:00000022 4E71            	    22: DONE	NOP
                                	    23: * One way to return to the OS or other calling program
    00:00000024 4267            	    24: 	clr.w	-(sp)	; there should be enough room on the caller's stack
    00:00000026 4E41            	    25: 	trap	#1			quick exit
    

    And I'm going to let you step through it yourself instead of showing you what it looks like here. It's basically just a different way to get at the same data, like on the 6809, but with 32-bit addresses and 16-bit offsets to deal with. And we'll actually talk about that all later.

    This has been another really long one. As we say in Japan, 「ご苦労様。」 (Go-kurō-sama.) You've worked hard, even if you just read through and didn't take time to enjoy plugging the code in to watch it run.

    Wait a minute. If you just read through and didn't step or trace through the simulations, you've really missed out on all the fun. Go back. Watch the code execute. Play with things just a little to see if you can make anything interesting happen. 

    And now we can really say, “ご苦労様。”

    The next thing we need to do is take a small detour to make sure you have tools to deal with all the hexadecimal math that has your eyes glazing over.


    (Title Page/Index)

     

    Friday, July 12, 2024

    ALPP 01-05 -- Getting a Simulator for the 68000 and Running Code on It (Hatari, vasm)

    Getting a Simulator for the 68000
    and Running Code on It
    (Hatari, vasm)

    (Title Page/Index)

     

    Again, I'm assuming you've gone through the previous chapters, bringing EXORsim up for the 6800 and 6809 and running code on it, and also bringing up my fork of EXORsim for the 6801, with code running on it as well. 

    I'll be implicitly referring here and there back to things we did in those chapters, so if you get lost, at least go back and make sure you've read and understood those and preferably got those emulators working before leaving questions here.

    Now, if someone had written an EXORmacs simulator in the same vein as Joe Allen's EXORsim, we'd be in business. I'd use that for the 68000 code here. Or even an EXORsim simulator for the MEX68KDM 68K developer module card for the EXORciser that Motorola mentioned in some of their materials.

    (I seem to remember a simulator for a Versabus or VME based computer in the SIMH project, but I'm not seeing that now. I probably should take a look at the SAGE simulator in openSIMH, but, again, that's a lot of reading documentation and building more code, and I'm not sure it would be any easier to use than Hatari.)

    There's also Easy68k or something, but it only runs on MSWindows, and I don't do Wine, and I don't recommend things I don't do.

    So, options lacking, doing this (myself) right for the 68000 would possibly involve something like writing up an instance of Musashi that would run in some sort of terminal arrangement, perhaps as an alternate history main processor board for the EXORciser if I can't find documentation for the MEX68KDM. 

    Or do something to emulate the single board MEX68KECB. 

    And I'm not sure how much of the disassembler, general debugger, interactive assembler, etc. I'd have to add, so maybe I might as well plan on writing the emulator proper, as well, instead of planning on using Musashi.

    And all of that would be more postponing this tutorial. 

    So, ...

    Hatari

    What's the difference between an emulator and a simulator?

    Some people say that emulators are done in hardware and simulators in software. But the Hatari project calls their Atari ST simulator an emulator.

    Hatari is in the Debian package repositories, and therefore in Ubuntu and many other Linux OS package repositories, as well. And there are RPMs for Cent OS and such. You can download it from the project site and work through getting all the prerequisite dependencies installed before building it yourself if you want. But that's another steep learning curve if you haven't done it before, and a fair amount of work even if you have.

    Although that's exactly what I have done in my current workstation. I installed the dependencies syetem-globally from packages, then built Hatari and installed it locally in my daily-driving user account. It keeps the side-effects local.

    So having it in packages is a really useful thing if you aren't building it yourself. Your package manager can work out the dependencies, and install them all together at once with Hatari, in just a few minutes or tens of minutes, depending on your internet connection.

    Fortunately for you who are running MSWindows, there are pre-compiled .exe executables for you in the downloads area of the website, in .zip archives.

    Go ahead and spend a few minutes looking around the Hatari site, especially the docs. Things to look for, 

    • EmuTOS
    • Keyboard mappings 
    • Disk images
    • Emulating disks in hosted directories
    • Getting Hisoft Devpac or similar software 
    • The built-in debugger

    Check to see if your package manager includes Hatari. (Cygwin for MSWindows does not, at present. Several package managers for Mac do. Most Linux OSses do. NetBSD and FreeBSD do.) 

    If it doesn't, spend some time checking the build instructions. Write down the list of dependencies and start collecting and either installing them from packages or building them. Etc. LoL. If you are running an OS for which you need to build it, I'm pretty sure you know how to do this without me explaining it. 

    If, for whatever reason, you do build it yourself, you can specify your local executable directory as the install target. In the example structure I've been talking about, that might be 

    ~/prg

    and in that case you would specify 

    /home/me/prg 

    as the target.

    Before we proceed, there is a not-so-minor issue with Hatari, in that we won't be able to do things like copying and pasting object or assembler source code into the running emulator window, the way we can with EXORsim. We'll have to edit source code files, save them in the directories Hatari is seeing as emulated disk, and assemble them with vasm or something similar.

    Speaking of directories, familiarize yourself with the directory structure your package system sets up for Hatari. In particular, as I mentioned, you want to know where to put EmuTOS so it can find it, or, more likely, you want to check where your package has installed EmuTOS. You also want to know where it will look for disk images and directories to emulate disks in. 

    If you have it installed properly, you can find a lot of answers by running

    $ hatari --help
    
    Hatari v2.4.0-devel (Dec 18 2021) - the Atari ST, STE, TT and Falcon emulator.
    
    Hatari is free software licensed under the GNU General Public License.
    
    Usage:
     hatari [options] [directory|disk image|Atari program]
    
    General options:
      --help or -h          Print this help text and exit
    ...
    

    EmuTOS

    EmuTOS is essentially a free-and-open-source replacement for TOS (in the short version of the story) -- the BIOS and OS kernel provided originally by Atari.

    You may find people telling you you need to download EmuTOS separately from Hatari, but that really isn't the case for our uses. The license for EmuTOS allows it to be packaged with Hatari and other emulators, so the tos.img that is in the package that your package manager makes for you, or is in the .zip or other archive you downloaded, should be EmuTOS. 

    That also means you don't have to extract the ROM from a real Atari ST or such to do what we want to do.

    Setup

    In fact, other than deciding where to set up the shared directory structure, it should just mostly work. Well, that and the keyboard mappings. You'll probably want to look carefully at keyboard mappings so you can get an idea where to find keys you need.

    Once it's installed (or built), running hatari from the command line without options should bring up an Atari desktop screen in emulation, like this:

     

    from which you can hit F12 to get a graphical dialog to set things up. 

    You may prefer to go that route, rather than sort through all the command-line options. Heh. You probably do want to use it. So I'll walk you through the relevant setup.

    By the way, F11 toggles full-screen mode off and on. This is useful, particularly when switching back and forth between Hatari and your host OS.

    You will usually want to use it with full screen off, because of all the things you'll be doing at the same time on the host machine. But, at least on my installation, with full-screen off, the mouse sometimes gets out of sync, and I have to toggle back to full-screen to use the mouse. However, I can pretty much always use the mouse in the setup dialog. Toggling is not usually a problem.

    Things you want to set up or check now include 

    • System -- Keep it ST mode to keep things simple.
      Blitter in ST mode, if it isn't already set. 
    • CPU -- 8 MHz can be slow, but more than 16 MHz can get weird.
      So, 16 MHz.
    • Memory -- You want at least 512K, and more than that can get weird for what we are doing.
      So, 512K.
    • Floppy disks and Hard disks -- You don't really need disk images, but, maybe you do ...

    We've got to talk about default directories for a moment. 

    When you install from your packages, it will likely set up several things it needs to keep track of under 

    /usr/local/share/hatari/

    or some such directory. This is in the file system area controlled by the operating system, and is outside your daily driving user's file system area. Handling file permissions to allow writing here can get strange. You should not want to do that. No, you really should not want to do that. So you'll want to make some adjustments. 

    Among the things it will by default save here, and look for here, are

    • the tos.img file it is using
    • the C: directory
    • keyboard mapping files 
    • disk image files

    I'm sure you can understand that we need these, and we need to know where they are.

    The tos.img file, we can leave alone, once we've noticed where it is. We won't need to touch it that much. (If we do need to, if we have a different tos.img file to use, the configuration menu lets select a different image in a different location without messing with /usr/local/share/.)

    The C: directory mapping, we will use extensively. We need to write to that directory a lot. So we need to point it somewhere within our daily-driver working directories, like (using unix/Linux syntax)

    ~/asmwork/share/hatari/C/

    which if you are working as user "me" on a LInux OS, might actually look like 

    /home/me/asmwork/share/hatari/C/

    I say might because it depends on how you set things up. I didn't set mine up exactly this way, but I'll use this as a basis to explain things. You should think a little about how you would want it, and set it up in a way that makes sense to you. 

    Your operating system gives you some sort of a home directory for the user you are logged in as, and the directory you decide to do most of your assembly language work in should reside under that. That directory would be "asmwork" in the paradigm above, or it could be "mywork/asm", or whatever you choose to call it. You'll probably want a directory under that which multiple programs you'll be working with can share, there under your assembly language working directory, and you might call it "share" -- thus, "asmwork/share" if you decide to do it that way.

    On MSWindows, you'll be wanting to work within the cygwin shell, so you'll use forward slashes instead of MS-DOS/CPM backslashes (or instead of yen mark -- ¥ -- in older Japanese language MSWindows OSses).  But looking at them or working on them in MSWindows command line shell, you will use the MSWindows slash -- "<something>\asmwork\share\hatari\C\" (or, in an older Japanese MSWindows OS, the yen mark --  "<something>¥asmwork¥share¥hatari¥C¥"). You'll need to get used to some differences between the Cygwin shell and the MSWindows shell.

    Not incidentally, I downloaded the 80 megabyte hard disk blank image that you can find on the Hatari download page and saved it in my local files, and saved a copy of it to be used as the hatari D: drive, for example, directly under 

    ~/asmwork/share/hatari/ 

    in the above directory conventions. I recommend you get that hard disk image and save it somewhere similar, also. You can then select it for your D: drive from the configuration dialog.

    So, continuing with the configuration dialog:

    • Hard disks -- write down the default for C: before you use eject and browse to set it appropriately in your own directory structure. You might want to remember where it was.
      Also, set up a D: drive with the blank image, as an IDE drive.
      When you're done with this, save the configuration once, just to be sure.
    • Floppy disks -- you can probably save yourself some error messages if you use the configuration dialog to create a couple of blank floppy images and set them up to be drives A: and B:. The setup dialog has buttons that do this for you.
    • Atari Screen -- look at what's here, in case you want to change something. But leave it at resolutions and colors the early ST models can handle, so things don't get weird.
    • Hatari Screen -- You probably want the status bar and GPU scaling.
    • Keyboard -- Remember that you can set the keyboard mapping here. In fact, go ahead and save a default configuration file in your local directories so you can look at it and play with it.
    • Load/Save config -- Note where it saves your configuration files in a hidden directory in your local directory structure, which is not under ~/asmwork/share/hatari/ in the above conventions. Quite likely, it will be under "~/.config/hatari/",

    So far, even if it isn't anything that seems all that interesting, you just need to see where things are, and, especially, move C: and save and set some keyboard mappings. 

    Go ahead and quit after saving anything you changed and want to save. It will give you one last chance to save things.

    Check again in your host OS that the C: directory is where you told it to be, for example, under the above conventions,

    ~/asmwork/share/hatari/C/

    Start Hatari again and when the desktop screen comes up, run EmuCON by selecting it from the File menu.

    Or you can just hit Ctrl-Z to run EmuCON. Either way works.

    It should put away the GUI screen and drop you into a command-line DOS (ergo, CP/M) shell. 

    Type some commands like HELP and DIR and such (You don't have to type in caps.), and see whether the keyboard needs configuration. If it does, look at the documentation and figure out what needs to be where.

    The following keyboard configuration file makes hyphen, brackets, and the caret available on my Japanese notebook keyboard, although not in optimal positions.

    -,12
    [,26
    ],27
    ^,13
    

    Some other key codes, I have to use the Fn key and the keypad to access. 

    You'll have to figure out what your keyboard needs, though, and it requires editing the keyboard configuration file as a text file in your host system, so don't hesitate to use pencil and paper if necessary to take notes. And be willing to make compromises, because they are trying to emulate the ST keyboard, not make the modern keyboard available in its entirety.

    When you have the keyboard working well enough, use EmuCON to make a working directory under the C: directory. You could do this in the host OS, as well, but we want to make sure the emulator is working and able to talk to the host OS on things like this. In the EmuCON console,do a DIR and see what the emulator thinks is there.

    C:\>DIR
      file not found

    make your working directory, maybe call it "PRIMER", and then change to it for fun:

    C:\>MD PRIMER
    C:\>DIR
    PRIMER
    C:\>CD PRIMER
    C:\primer>

    You can exit the command line shell with the EXIT command.

    Devpac

    I have been using Hisoft's Devpac for another project, and I was intending to discuss that, but when I went back to check where I got it from and such, I decided there is too much ambiguity and lack of provenance to recommend it. I found some evidence at the time that the folks at Hisoft had given explicit permission, but I can't find that evidence now.

    If you want to use it, you'll need to figure out the provenance and whether there is permission to use it for yourself. I can't help you with that.

    If you do decide to use Devpac, install it on the D: drive. It'll be easier to use that way. 

    More generally, you'll probably want to install any tools for working in the emulated Atari ST system in the emulated D: drive.

    Now, as I think I mentioned, Hatari has a built-in debugger. So we have the debugger requirement at least partially covered.

    But it doesn't do interactive assembly, and it doesn't include a separate assembler, so you'll need an assembler. I haven't written one of those for the 68000. But a guy named Volker Barthelmann and a guy name Frank Wille have worked together and made something that can help us, called vasm, and made it available for non-commercial use -- which I think covers what we are doing here.

    vasm

    I guess vasm is named for "Volker's Assembler". It's a really complicated beast, and does way more than we need, but we can use it for what we need. As I just said, they have made it available to be used for non-commercial purposes when used to target Atari ST. That's not a license that allows it to be included in your libre OSes's main/libre packages, but it should be sufficent for our purposes here. And it's not hard to build. And not really hard to run. either, once you've got it built. 

    That is, I'll help you figure out how.

    First, nose areound the website. Read the small tutorial. Open up the HTML manual and read the General entry first where it talks about permission to use and about installation. Then go to the entries on the Assembler, the (Motorola) Mot Syntax Module, the TOS output module, and the m68k CPU module, in particular, and read those. Then read the build instructions.

    Then download the latest release source to someplace like "~asmwork/vasm/" and unpack and build it.

    In brief,

    • Go to the directory that unpacking the tarball created and do a directory listing. Note all the makefiles.
    • Run make without arguments:
           $ make
      Ignore the feedback.
    • Now run
           $ make CPU=m68k SYNTAX=mot
    • Do a listing
           $ ls -lart
      and check that vasmm68k_mot has been built.
    • Link it into your local user file system's binary directory.

    Given the example directory structure I've been mentioning, that last step can be done with something like 

     ln -s /home/me/asmwork/vasm/vasm/vasm68k_mot /home/me/prg/

    Now we want our sample program that accumulates a few sums. This time we'll have to actually put it in a file instead of editing it interactively in the simulator.

    Here's the code again, with stuff that's necessary for vasm and for the Atari ST target, and a little extra code inspired by the extra we did with the 6801:

    	OPT LIST,SYMTAB	; Options we want for the stand-alone assembler.
    	MACHINE MC68000	; because there are a lot the assembler can do.
    	OPT DEBUG	; We want the debugger to know our labels.
    	OUTPUT
    ***********************************************************************
    	EVEN		; Just for good measure -- 68K needs code even aligned.
    EXAMPLE:
    	MOVEQ	#8,D0	; MOVEQ lets us ignore register width.
    	ADDQ	#5,D0	; Default register width is okay.
    	ADDQ	#2,D0	; D0 is comparable to 6800 A? Sort-of? Maybe?
    	ADDQ	#7,D0
    	ADDQ	#4,D0
    	NOP		; one landing pad
    RESTART:
    	MOVE.W	#2056,D0	; the extra example for 6801
    	ADD.W	#1285,D0
    	ADD.W	#514,D0
    	ADD.W	#1799,D0
    	ADD.W	#1028,D0
    	NOP		; two landing pad
    DRESTART:
    	MOVE.L	#134744072,D0	; 32-bit version
    	ADD.L	#84215045,D0
    	ADD.L	#33686018,D0
    	ADD.L	#117901063,D0
    	ADD.L	#67372036,D0
    	NOP			; three landing pad
    DONE:
    	NOP			; You must "quit" the debugger.
    	NOP			; Don't continue.
    
    	END	EXAMPLE
    

    In your host OS, copy that into an empty text editor document and save it in your working directory for the primer code as something like sum85274.s. Given the above structure, that would be  

    ~/asmwork/share/hatari/C/primer/sum85274.s

    Drag the corner of your terminal shell window to widen it to mostly fill the screen before you continue. It'll make it easier to shift back to the terminal when you start debugging.

    Assemble the file you just saved with vasm using the vasmm68k_mot command with parameters as follows:

    $ vasmm68k_mot -Ftos -o SUM85274.PRG -L sum85274.lst sum85274.s
    

    You can open the assembly listing file, sum85274.lst, in a text editor, to look at the results. 

    If there are no errors, start Hatari there in the primer working directory:

    $ hatari
    

    When the desktop comes up, hit Ctrl-Z to bring up EmuCON. In EmuCON, change to the primer working directory, whatever you named it.

    Then hit Alt-PAUSE to enter the debugger.

    That's the alt key, with the PAUSE function key that is usually above the ten-key pad on a long keyboard, or at the top-right corner of the notebook PC keyboard. If you are working on a notebook computer, you probably need to hold down the Fn key while you hit Alt-PAUSE.

    Sometimes, my computer seems to miss the Alt key and just pauses. If that happens, you may have to hit Alt-PAUSE again to enter the debugger.

    When you enter the debugger, the emulated Atari screen may see some pixel folding. That's okay, ignore it. 

    Move the host OS cursor over to the terminal shell window where you started Hatari, and click that window to bring it forward:

     

    At this point, you're debugging the Atari ST operating system itself, or perhaps EmuCON.

    ----------------------------------------------------------------------
    You have entered debug mode. Type c to continue emulation, h for help.
    
    CPU=$e1d7e2, VBL=790, FrameCycles=128, HBL=0, LineCycles=128, DSP=N/A
    00e1d7e2 46c0                     move.w d0,sr
    >

    Let's try the help command, just to see what help it gives us:

    > h
    
    Generic commands:
               cd (  ) : change directory
         evaluate ( e) : evaluate an expression
             help ( h) : print help
          history (hi) : show last CPU/DSP PC values & executed instructions
             info ( i) : show machine/OS information
             lock (  ) : specify information to show on entering the debugger
          logfile ( f) : set (memdump/disasm/etc) log file
            parse ( p) : get debugger commands from file
           rename (  ) : rename given file
            reset (  ) : reset emulation
       screenshot (  ) : save screenshot to given file
           setopt ( o) : set Hatari command line and debugger options
        stateload (  ) : restore emulation state
        statesave (  ) : save emulation state
            trace ( t) : select Hatari tracing settings
        variables ( v) : List builtin symbols / variables
             quit ( q) : quit emulator
    
    CPU commands:
          address ( a) : set CPU PC address breakpoints
       breakpoint ( b) : set/remove/list conditional CPU breakpoints
           disasm ( d) : disassemble from PC, or given address
          profile (  ) : profile CPU code
           cpureg ( r) : dump register values or set register to value
          memdump ( m) : dump memory
         memwrite ( w) : write bytes/words/longs to memory
          loadbin ( l) : load a file into memory
          savebin (  ) : save memory to a file
          symbols (  ) : load CPU symbols & their addresses
             step ( s) : single-step CPU
             next ( n) : step CPU through subroutine calls / to given instruction type
             cont ( c) : continue emulation / CPU single-stepping
    
    DSP commands:
       dspaddress (da) : set DSP PC address breakpoints
         dspbreak (db) : set/remove/list conditional DSP breakpoints
        dspdisasm (dd) : disassemble DSP code
       dspmemdump (dm) : dump DSP memory
       dspsymbols (  ) : load DSP symbols & their addresses
       dspprofile (dp) : profile DSP code
           dspreg (dr) : read/write DSP registers
          dspstep (ds) : single-step DSP
          dspnext (dn) : step DSP through subroutine calls / to given instruction type
          dspcont (dc) : continue emulation / DSP single-stepping
    
    If value is prefixed with '$', it's a hexadecimal, if with '#', it's
    a normal decimal, if with '%', it's a binary decimal. Prefix can
    be skipped for numbers in the default number base (currently 10).
    
    Any expression given in quotes (within ""), will be evaluated
    before given to the debugger command.  Any register and symbol
    names in the expression are replaced by their values.
    
    Note that address ranges like '$fc0000-$fc0100' should have no
    spaces between the range numbers.
    
    'help <command>' gives more help.
    >

    You can try various commands, like disassembling code (d), dumping memory (m), and looking at registers (r). But don't try setting memory or registers just yet. 

    If you do, you'll want to use the quit (q) command and start Hatari up again fresh. 

    The problem you might be wondering about is how to get the target program into memory where you can debug it. I think it might be possible to use the debugger's load command (l), but, if so, I haven't figured that out yet.

    Instead, as described in the debugger manual entry on breakpoints and variables, set a breakpoint to stop emulation after a program is loaded and before it is run with this break command: 

    b pc = TEXT :once

    Here's what it looks like typed in, with the results it displays:

    > b pc = TEXT :once
    CPU condition breakpoint 1 with 1 condition(s) added:
    	pc = TEXT
    -> Break only once, and delete breakpoint afterwards.
    >

    What that means is that it set a one-time breakpoint for the next time the PC is equal to the beginning of the TEXT segment. CP/M programs are started by starting execution at the beginning of the program's TEXT segment, so this will do what we want, if we make sure that the next program we run is the target program.

    Use the continue command (c) to let Hatari continue running,

    > c
    Returning to emulation...

     and then bring the Hatari window back in front using the task bar or whatever. EmuCON should be showing you an active prompt there. 

    At the prompt, type the name of the executable file that you just used vasmm68k_mot to create. If you used the same names as I did, above, that would be 

    C:\primer>SUM85274.PRG

     with or without the .PRG extension, really.

    Now use the task bar or whatever to get back to the console where the debugger will be showing you all sorts of things about the breakpoint, showing you the first instruction in the TEXT segment disassembled, and prompting you again:

    1. CPU breakpoint condition(s) matched 1 times.
    	pc = TEXT :once
    Removed CPU breakpoint 1:
    	pc = TEXT :once
    Reading symbols from program '/home/nova/usr/share/hatari/C:/primer/SUM85274.PRG' symbol table...
    TOS executable, DRI / GST symbol table, reloc=0, program flags: PRIVATE (0x0)
    Program section sizes:
      text: 0xc, data: 0x0, bss: 0x0, symtab: 0xe
    Trying to load DRI symbol table at offset 0x28...
    Offsetting BSS/DATA symbols from TEXT section.
    Skipping duplicate address & symbol name checks when autoload is enabled.
    Loaded 1 symbols (1 TEXT) from '/home/nova/usr/share/hatari/C:/primer/SUM85274.PRG'.
    
    CPU=$13d10, VBL=20873, FrameCycles=241160, HBL=237, LineCycles=368, DSP=N/A
    00013d10 7008                     moveq #$08,d0
    >

    Notice that disassembly of the first instruction at the end of all that. We're ready to do a MOVEQ, ready to load D0 with the value 8.

    We can do a disassembly, and the debugger will just assume, since we haven't done a disassembly during this session yet, that we want to see what the current PC is pointing out:

    > d
    (PC)
    EXAMPLE:
    00013d10 7008                     moveq #$08,d0
    00013d12 5a40                     addq.w #$05,d0
    00013d14 5440                     addq.w #$02,d0
    00013d16 5e40                     addq.w #$07,d0
    00013d18 5840                     addq.w #$04,d0
    00013d1a 4e71                     nop 
    RESTART:
    00013d1c 303c 0808                move.w #$0808,d0
    00013d20 d07c 0505                add.w #$0505,d0
    00013d24 d07c 0202                add.w #$0202,d0
    00013d28 d07c 0707                add.w #$0707,d0
    00013d2c d07c 0404                add.w #$0404,d0
    00013d30 4e71                     nop 
    DRESTART:
    00013d32 203c 0808 0808           move.l #$08080808,d0
    00013d38 d0bc 0505 0505           add.l #$05050505,d0
    00013d3e d0bc 0202 0202           add.l #$02020202,d0
    00013d44 d0bc 0707 0707           add.l #$07070707,d0
    00013d4a d0bc 0404 0404           add.l #$04040404,d0
    00013d50 4e71                     nop 
    00013d52 4e71                     nop 
    >

    Let's do a second disassembly to see if it has shown us all of the code. This time, it will pick up at where it left off:

    > d
    00013d54 0000 0000                or.b #$00,d0
    00013d58 0000 0000                or.b #$00,d0
    00013d5c 0000 0000                or.b #$00,d0
    00013d60 0000 0000                or.b #$00,d0
    00013d64 0000 0000                or.b #$00,d0
    00013d68 0000 0000                or.b #$00,d0
    00013d6c 0000 0000                or.b #$00,d0
    00013d70 0000 0000                or.b #$00,d0
    00013d74 0000 0000                or.b #$00,d0
    00013d78 0000 0000                or.b #$00,d0
    00013d7c 0000 0000                or.b #$00,d0
    00013d80 0000 0000                or.b #$00,d0
    00013d84 0000 0000                or.b #$00,d0
    00013d88 0000 0000                or.b #$00,d0
    00013d8c 0000 0000                or.b #$00,d0
    00013d90 0000 0000                or.b #$00,d0
    00013d94 0000 0000                or.b #$00,d0
    00013d98 0000 0000                or.b #$00,d0
    00013d9c 0000 0000                or.b #$00,d0
    00013da0 0000 0000                or.b #$00,d0
    00013da4 0000 0000                or.b #$00,d0
    00013da8 0000 0000                or.b #$00,d0
    00013dac 0000 0000                or.b #$00,d0
    >

    Yep, when there's nothing in memory, there's usually a lot of zeroes or a lot of garbage. And zeroes just happen to be the op-code for a byte-sized OR of immediate 0 into D0.

    Try single stepping (s):

    > s   
    
    CPU=$13d12, VBL=32348, FrameCycles=35072, HBL=34, LineCycles=528, DSP=N/A
    00013d12 5a40                     addq.w #$05,d0
    >

    Unfortunately, it doesn't show you which register(s) changed. It does show you the CPU and the next op-code, disassembled, along with a lot of display controller stuff. We want to see the registers, so, let's use the register command (r):

    > r
      D0 00000008   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D54   A5 00013D54   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 5a40 (ADD) 5440 (ADD) Chip latch 00000000
    00013d12 5a40                     addq.w #$05,d0
    Next PC: 00013d14
    >

    So, if you step (s) and then show (r) the registers, you can watch the numbers add up (in hexadecimal) in data register D0.

    > s
    
    CPU=$13d14, VBL=32348, FrameCycles=35076, HBL=34, LineCycles=532, DSP=N/A
    00013d14 5440                     addq.w #$02,d0
    > r
      D0 0000000D   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D54   A5 00013D54   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 5440 (ADD) 5e40 (ADD) Chip latch 00000000
    00013d14 5440                     addq.w #$02,d0
    Next PC: 00013d16
    > s
    
    CPU=$13d16, VBL=32348, FrameCycles=35080, HBL=34, LineCycles=536, DSP=N/A
    00013d16 5e40                     addq.w #$07,d0
    > r
      D0 0000000F   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D54   A5 00013D54   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 5e40 (ADD) 5840 (ADD) Chip latch 00000000
    00013d16 5e40                     addq.w #$07,d0
    Next PC: 00013d18
    > s
    
    CPU=$13d18, VBL=32348, FrameCycles=35084, HBL=34, LineCycles=540, DSP=N/A
    00013d18 5840                     addq.w #$04,d0
    > r
      D0 00000016   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D54   A5 00013D54   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 5840 (ADD) 4e71 (NOP) Chip latch 00000000
    00013d18 5840                     addq.w #$04,d0
    Next PC: 00013d1a
    > s
    
    CPU=$13d1a, VBL=32348, FrameCycles=35088, HBL=34, LineCycles=544, DSP=N/A
    00013d1a 4e71                     nop 
    > r
      D0 0000001A   D1 00000000   D2 00000000   D3 00000000 
      D4 00000000   D5 00000000   D6 00000000   D7 00000000 
      A0 00000000   A1 00000000   A2 00000000   A3 00000000 
      A4 00013D54   A5 00013D54   A6 00077FC6   A7 00077FF8 
    USP  00077FF8 ISP  00007E64 
    T=00 S=0 M=0 X=0 N=0 Z=0 V=0 C=0 IMASK=3 STP=0
    Prefetch 4e71 (NOP) 303c (MOVE) Chip latch 00000000
    00013d1a 4e71                     nop 
    Next PC: 00013d1c
    >

    Exciting, isn't it?

     Just don't step past the end of code!!!!!!!

    Heh. Actually, it's not a problem, as long as you don't step too far. All those 
       OR #0,D0 

    instructions don't really do much. They just really aren't very interesting.

    But once you've stepped through the end of the code, then what? 

    If you try to continue executing code that isn't there, something bad will eventually happen, right?

    Sort, of. You'll get a segment error or a bus error or some such, and EmuTOS will try to catch you and send you back to the EmuCON window or something. But we can't guarantee that Hatari is in a stable state. (It's almost guaranteed for this one, but not quite.) So, instead, once you've stepped through all the code and convinced yourself it's doing what it's doing, just use the quit command (q) again and quit the Hatari session.

    We'll look at how to get the program to safely return to the OS later, among other things

    And that should get us started for working on the 68000.

    Amiga emulators would also be interesting, but the Amiga run-time has some complexities that I don't want to deal with. Likewise the classic Macintosh systems. 

    I'm not saying don't try them. Do, if you are inclined. They're fun, but distracting. MAME, too. MAME is really distracting.

    I really wish I had time to write an open-source emulator for the MEX68KECB single board.  That would be the least distracting for this level of code.

    Just for the record, MDOS for the EXORciser is approximately what TOS (and EmuTOS) for the Atari is. If the debugger for Hatari were able to assemble code interactively, we would not need, at this level, to be saving code in files and so forth on the Hatari. 

    But we will get there before we are done. Don't worry.

    I think we can get Hatari to do the job we need.

    Next, I think I want to show you one way to separate the numbers we're adding in this example from the code itself.


    (Title Page/Index)

     

    Saturday, June 22, 2024

    ALPP 01-04 -- Getting a Simulator for the 6801 and Running Code on It

    Getting a Simulator for the 6801
    and Running Code on It

    (Title Page/Index)

     

    I'll assume that you've already gone through the steps for getting the necessary operating system environment and tools, and have got EXORsim up and running, and have tested it with the example I gave showing how to use the accumulator to accumulate a sum of a series of constants.

    Several years back, I needed (wanted?) a nice debug system for developing some 6801 code. At the time I started the project (if I recall correctly) Ciaran and his friends had not yet added MC-10 emulation to XRoar. Or maybe I didn't want to jump through the hoops of a self-hosted debugger on it. Or something.

    An option I considered was to write my own 6801 simulator (a project I had already shown myself I didn't have the discipline to take to completion) or get enough of the documentation for the M6801 USE module for the EXORciser and the MC6801 EXORciser Support System to add that module to Joe Allen's EXORsim. But that latter begged the question of where to get the documentation, and whether I could afford the persuasion rate if I could find someone who had it.

    A less ambitious option would be to write an alternative reality main CPU module for EXORsim, from a world in which Motorola had made the bare 6801 core available as a direct substitute for the 6800 -- in other words, with no built-in IO or RAM. It could be invoked as exor01, just as the 6809 version of EXORsim is invoked as exor09. That would allow me (and you) to use git to pull in Joe's updates without (too much) conflict with my  6801 tools. 

    Just for the record, the timing differences might have meant MDOS and other system-level software wouldn't run on the 6801 simulation, even if you cleared the built-in I/O devices out the memory map.

    I just wanted to run code, didn't care about timing, didn't know at the time how Joe would implement the 6809 modules, etc. So I simply made a fork of the EXORsim project (allowed by the GPL license) and added 6801 instructions (without attention to timing) to the 6800 instruction set, with a command-line switch to enable 6801 instructions. It worked for my project, and that is what I'm going to recommend you use for the 6801 here -- for now.

    Which is going to take a little extra explanation.

    Now, for the accumulator example, the 6801 code and execution will be exactly the same as for the 6800, so it might be tempting to skip it. But you'll need the explanation of how to get, compile, and use the EXORsim6801 tools, so we won't. And we can talk a little about 8-bit bytes vs. 16-bit words while we are at it.

    EXORsim6801

    There was a local code repository provider here called sourceforge.jp, and I started using them because they are local. They changed their name to Open Source Developers' Network (osdn.net) about the time SourceForge changed hands and started going a little crazy, so I started using OSDN as my main repository provider. Things have changed more since then, with some of SourceForge's original owners being able to buy it back, and all. And OSDN's team has not been able to keep it the easy-to-use place it was. And Microsoft bought Github. Etc. 

    Excuses, what-ifs, and excuses, but EXORsim6801 is in my personal chambers (workspaces) on OSDN, here:

    https://osdn.net/users/reiisi/pf/exorsim6801/wiki/FrontPage

    It takes patience to access sometimes. If you get a timeout or a gateway error, refresh it, stop it, and refresh again, and it should come up, although, if it still doesn't come up, you may need to wait an hour or three, or a day, and try again.

    I kept it in a chamber workspace because I intended to give the code back to Joe. He then told me he didn't really see the point, since it didn't reflect any real retro computing hardware or software that ever existed -- which is not unreasonable. 

    If I make a real alternate reality project out of it, I should at least get the timing right, and make it a separate executable so I can pull in his updates. But that will take time I don't have.

    You can read my summary from back then, and then go to the source code menu and select "source tree", or you can go directly to the source tree here:

    https://osdn.net/users/reiisi/pf/exorsim6801/scm/tree/master/

    On the right of the source tree page, towards the top, you'll find the git URL for cloning, and ZIP and TAR buttons for export. Hit your choice of ZIP or TAR (.tar.gz) to download, or use the git clone command to get your copy.

    You should probably want to clone it or unpack the archive in a directory called exor6801 under your assembly language working directory (as in "~/asmwork/exor6801"), or use some other clear structure to keep it separate from Joe's exorsim.

    After cloning or unpacking, change into the source code directory produced and do NOT do a "sudo make install"! 

    Just do a "make", without sudo and without install. 

    If you want to make it available without the path, when it's built, you can link it into your executable directory under a different name, such as "exorprime" or something.

    But for what we want to do for the present, we can work directly in the build directory. So, in the build directory, basically do the same as you did for the 6800, except this time you'll invoke exor with two switches:

    ./exor --6801 --mon

    Other than that, the session should look pretty much like the 6800 session:

    $ cd asmwork/exorsim6801/exorsim
    $ ./exor --mon --6801
    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 1000
    1000: START LDAA	#8	; Gotta start somewhere.
    1002:  ADDA	#5
    1004:  ADDA	#2
    1006:  ADDA	#7
    1008:  ADDA	#4
    100a:  NOP		; landing pad for breakpoint
    100b: 
    % u 1000
    1000: 86 08               LDA #$08
    1002: 8B 05               ADDA #$05
    1004: 8B 02               ADDA #$02
    1006: 8B 07               ADDA #$07
    1008: 8B 04               ADDA #$04
    100A: 01                  NOP
    100B: 00                  ???
    100C: 00                  ???
    ...
    % d 1000
    1000: 86 08 8B 05 8B 02 8B 07  8B 04 01 00 00 00 00 00 ................
    1010: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ................
    ...
    % s 1000
              0 A=00 B=00 X=0000 SP=FF8A ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
    >         1 A=08 B=00 X=0000 SP=FF8A ------          1002: 8B 05    ADDA #05                 
    
    Type 'help'
    % s
              1 A=08 B=00 X=0000 SP=FF8A ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
    >         2 A=0D B=00 X=0000 SP=FF8A ------          1004: 8B 02    ADDA #02                 
    
    Type 'help'
    % s
              2 A=0D B=00 X=0000 SP=FF8A ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
    >         3 A=0F B=00 X=0000 SP=FF8A ------          1006: 8B 07    ADDA #07                 
    
    Type 'help'
    % s
              3 A=0F B=00 X=0000 SP=FF8A ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
    >         4 A=16 B=00 X=0000 SP=FF8A H-----          1008: 8B 04    ADDA #04                 
    
    Type 'help'
    % s
              4 A=16 B=00 X=0000 SP=FF8A H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
    >         5 A=1A B=00 X=0000 SP=FF8A ------          100A: 01       NOP                      
    
    Type 'help'
    % b 100a
    Breakpoint set at 100A
    % c 1000
    
    Breakpoint!
              0 A=00 B=00 X=0000 SP=FF8A ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
              1 A=08 B=00 X=0000 SP=FF8A ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
              2 A=0D B=00 X=0000 SP=FF8A ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
              3 A=0F B=00 X=0000 SP=FF8A ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
              4 A=16 B=00 X=0000 SP=FF8A H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
              5 A=1A B=00 X=0000 SP=FF8A ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
              6 A=08 B=00 X=0000 SP=FF8A ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
              7 A=0D B=00 X=0000 SP=FF8A ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
              8 A=0F B=00 X=0000 SP=FF8A ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
              9 A=16 B=00 X=0000 SP=FF8A H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
    >        10 A=1A B=00 X=0000 SP=FF8A ------          100A: 01       NOP                      
    
    Type 'help'
    % t on
    % c 1000
             10 A=1A B=00 X=0000 SP=FF8A ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
             11 A=08 B=00 X=0000 SP=FF8A ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
             12 A=0D B=00 X=0000 SP=FF8A ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
             13 A=0F B=00 X=0000 SP=FF8A ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
             14 A=16 B=00 X=0000 SP=FF8A H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
    
    Breakpoint!
    >        15 A=1A B=00 X=0000 SP=FF8A ------          100A: 01       NOP                      
    
    Type 'help'
    %   

    This older version likes to give you traceback after a breakpoint, if tracing is off. You can ignore it or examine it, as you like.

    But that was all a bit boring since you've done it before, twice, so, before you hit control-C to break out, let's try adding a little code that does not assemble or  run on the 6800, just to be sure we actually have the 6801 emulator running. Go ahead and type this in by hand. It's not long:

    % a 100b
    100b: DSTART LDD #2056
    100e:  ADDD #1285
    1011:  ADDD #514
    1014:  ADDD #1799
    1017:  ADDD #1028
    101a:  NOP
    101b: 
    

    Hit enter at the blank line to quit assembling, and then display the bytes and disassemble it:

    % d 1000
    1000: 86 08 8B 05 8B 02 8B 07  8B 04 01 CC 08 08 C3 05 ................
    1010: 05 C3 02 02 C3 07 07 C3  04 04 01 00 00 00 00 00 ................
    1020: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ................
    ...
    % u 1000
    1000: 86 08               LDA #$08
    1002: 8B 05               ADDA #$05
    1004: 8B 02               ADDA #$02
    1006: 8B 07               ADDA #$07
    1008: 8B 04               ADDA #$04
    100A: 01                  NOP
    100B: CC 08 08            LDD #$0808
    100E: C3 05 05            ADDD #$0505
    1011: C3 02 02            ADDD #$0202
    1014: C3 07 07            ADDD #$0707
    1017: C3 04 04            ADDD #$0404
    101A: 01                  NOP
    101B: 00                  ???
    101C: 00                  ???
    

    You see that my choice of numbers to add was deliberate, right?

    Set the break point at $101A  and set trace on, then restart execution at $1000:

    % b 101a
    Breakpoint set at 101A
    % t on
    % c 1000
             39 A=1A B=1A X=0000 SP=FF8A ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
             40 A=08 B=1A X=0000 SP=FF8A ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
             41 A=0D B=1A X=0000 SP=FF8A ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
             42 A=0F B=1A X=0000 SP=FF8A ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
             43 A=16 B=1A X=0000 SP=FF8A H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
             44 A=1A B=1A X=0000 SP=FF8A ------          100A: 01       NOP                      
             45 A=1A B=1A X=0000 SP=FF8A ------ DSTART   100B: CC 08 08 LDD #$0808 EA=100C D=0808 
             46 A=08 B=08 X=0000 SP=FF8A ------          100E: C3 05 05 ADDD #$0505 EA=100F D=0505 
             47 A=0D B=0D X=0000 SP=FF8A ------          1011: C3 02 02 ADDD #$0202 EA=1012 D=0202 
             48 A=0F B=0F X=0000 SP=FF8A ------          1014: C3 07 07 ADDD #$0707 EA=1015 D=0707 
             49 A=16 B=16 X=0000 SP=FF8A ------          1017: C3 04 04 ADDD #$0404 EA=1018 D=0404 
    
    Breakpoint!
    >        50 A=1A B=1A X=0000 SP=FF8A ------          101A: 01       NOP                      
    
    Type 'help'
    % 
    

    Notice what's happening in the accumulators. 

    (This additional code, by the way, also runs on the 6809.)

    ******

    Ah. Yes. I need to mention this. 

    You may be wondering, when loading integer constants into the double accumulator on the 6801 and 6809, which accumulator gets the more significant byte? It's not apparent in this code, but, in both, A gets the more significant byte and B gets the less significant byte. 

    This can be confusing when reading early code for the 6800, because the 6800 was apparently designed under the opposite assumption. Check the stacking order of interrupts. On both the 6800 and the 6801, A gets pushed before B, which results in B being saved lower in memory, where the most significant byte should be. And much of the code written for the 6800, including the EXORciser EXBug monitor ROM, follows the same order, with B holding the more significant byte in two-byte operations, and being stored lower in memory.

    But when loading two-byte integers into D on either the 6809 or the 6801, B gets the less significant byte and A gets the more significant byte.

    The push order is fixed on the 6809, by the way.

    Trivia, but not trivia.

    ******

    This should motivate our discussion of hexadecimal, and of the limits of sizes of integers within the CPU. Play around with it, or hang on to your questions for now, either way.

    Again, there are other options, including XRoar or MAME emulating Tandy's MC-10 (which actually has a 6803, but that's just a 6801 without internal ROM). Also, for MSWindows, users, VMC10 can be found in the Color Computer Archives. 

    If you decide to use XRoar or MAME or VMC10 or such, you'll also need self-hosted tools like HumBug and MCOS, which can also be found in the Color Computer Archives. And, if I remember right, the syntax will be a little different, so you'll have to figure that out. (It's not hard once you have the basic ideas down.)

    And all that discussion should get us a little bit more ready to go after Hatari for working on the 68000.

     

    (Title Page/Index)

     

    Sunday, June 16, 2024

    ALPP 01-03 -- Running Code on the 6800 and 6809

     Running Code on the
    6800 and 6809

    (Title Page/Index)

     

    Now that you have EXORsim running on your workstation, let's look at how you can use it to run some code.

    If you shut down after working through the last post, boot back up and change directory to get back in the directory you built EXORsim in, doing something like

    $ cd asmwork/exor/exorsim

    In the directory where you built EXORsim, start it up with the --mon option.

    $ ./exor --mon
    Load facts file 'facts'
    'exbug.bin' loaded.
      EXBUG-1.1 detected
    'mdos.dsk' opened for drive 0 (double sided)
    
    OSLOAD...
    
    Hit Ctrl-C for simulator command line.  Starting simulation...
    
    >         0 A=00 B=00 X=0000 SP=00FF ------          0020: B6 E8 00 LDA E800                 
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 

    We can start with the 6800 example showing how an accumulator works. The 6800 code, again:

    START LDAA	#8	; Gotta start somewhere.
     ADDA	#5
     ADDA	#2
     ADDA	#7
     ADDA	#4
     NOP		; landing pad for breakpoint 
    

    Select it from the START label and copy it to the end of the NOP line.

    At the % prompt in the debugger, type 

    a 1000

    and enter/return. 

    You could type it in by hand, but since you've just selected and copied it, just paste it in. Use the right button on the mouse to pull up an edit menu over the session window and paste it. Hit enter again after the paste:

    % a 1000
    1000: START LDAA	#8	; Gotta start somewhere.
    1002:  ADDA	#5
    1004:  ADDA	#2
    1006:  ADDA	#7
    1008:  ADDA	#4
    100a:  NOP		; landing pad for breakpoint 
    100b: 
    % 

    What have you done?

    The "a" command is the assemble command. Joe put the ability to assemble source code into the hosted debugger. (Thanks, Joe!) So you've just assembled the source code of the example into memory starting at hexadecimal $1000.

    You can unassemble it if you want, with the "u" command:

    % u 1000
    1000: 86 08               LDA #$08
    1002: 8B 05               ADDA #$05
    1004: 8B 02               ADDA #$02
    1006: 8B 07               ADDA #$07
    1008: 8B 04               ADDA #$04
    100A: 01                  NOP
    100B: 00                  ???
    100C: 00                  ???
    ...

    Unassemble, disassemble, same thing. 

    Note that the address specified for the debugger commands is read by the debugger as hexadecimal. (Values in the assembler itself are default decimal.)

    You can display the contents of memory where you assembled it with the "d 1000" command:

    % d 1000
    1000: 86 08 8B 05 8B 02 8B 07  8B 04 01 00 00 00 00 00 ................
    1010: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ................
    ...

    Now you know why it's "u" for unassemble instead of "d" for disassemble. "d" is for display. (Or dump, if you prefer, but dump can mean other things.)

    How do you run it? One way is to use the "s" command, for step:

    % s 1000
    
              0 A=00 B=00 X=0000 SP=00FF ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
    >         1 A=08 B=00 X=0000 SP=00FF ------          1002: 8B 05    ADDA #05                 
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 

    You'll see that it went to address $1000 and stepped one op-code, showing you the next op-code. And it's nice to see the op-codes disassembled. Unassembled.

    Hit "s" all by itself and return and it steps the next one:

    % s
    
              1 A=08 B=00 X=0000 SP=00FF ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
    >         2 A=0D B=00 X=0000 SP=00FF ------          1004: 8B 02    ADDA #02                 
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
              2 A=0D B=00 X=0000 SP=00FF ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
    >         3 A=0F B=00 X=0000 SP=00FF ------          1006: 8B 07    ADDA #07                 
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
              3 A=0F B=00 X=0000 SP=00FF ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
    >         4 A=16 B=00 X=0000 SP=00FF H-----          1008: 8B 04    ADDA #04                 
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
              4 A=16 B=00 X=0000 SP=00FF H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
    >         5 A=1A B=00 X=0000 SP=00FF ------          100A: 01       NOP                      
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 
    

    And you can watch the effects -- watch the sum accumulate in the accumulator, and watch the program counter increment as it the simulator sequences through the op-codes.

    If stepping is a little slow for you, you can set a breakpoint with the "b" command, and use the "c" command for continue, until it hits the breakpoint:

    % b 100a
    Breakpoint set at 100A
    % c 1000
    
    
    Breakpoint!
              9 A=16 B=00 X=0000 SP=00FF H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
    >        10 A=1A B=00 X=0000 SP=00FF ------          100A: 01       NOP                      
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 
    

    Note that the simulator's PC has to hit the exact breakpoint to stop. That's part of the reason I use the NOP as a landing pad. It's easier to see where to set the breakpoint.

    But you wanted to see it trace through the operations, not just hum away in silence until it hit the breakpoint?

    Use the "t" command to turn trace on:

    % t on
    % c 1000
    
             10 A=1A B=00 X=0000 SP=00FF ------ START    1000: 86 08    LDA #08   EA=1001 D=08   
             11 A=08 B=00 X=0000 SP=00FF ------          1002: 8B 05    ADDA #05  EA=1003 D=05   
             12 A=0D B=00 X=0000 SP=00FF ------          1004: 8B 02    ADDA #02  EA=1005 D=02   
             13 A=0F B=00 X=0000 SP=00FF ------          1006: 8B 07    ADDA #07  EA=1007 D=07   
             14 A=16 B=00 X=0000 SP=00FF H-----          1008: 8B 04    ADDA #04  EA=1009 D=04   
    
    Breakpoint!
    >        15 A=1A B=00 X=0000 SP=00FF ------          100A: 01       NOP                      
    
    6800 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 
    

    Fortunately, the breakpoint was still set.

    And you've probably noticed by now that there's a help command. Try it now, just for grins.

    Okay, you've got the basics of the debugger in EXORsim down now, you can play around a bit. 

    Go ahead and try things. If it gets hung up, you can always hit ctrl-C, and if that doesn't work, just close the shell session window and open a new one. 

    How about the 6809?

    Here's the 6809 code for the above:

    START LDA	#8	; 6809 mnemonic: LoaD accumulator A
     ADDA	#5	; Mnemonic shared with 6800/6801.
     ADDA	#2
     ADDA	#7
     ADDA	#4 
     NOP		; landing pad for breakpoint 
    

     In EXORsim, it's not a whole lot different. The commands are the same. The main difference is the set of op-codes and their mnemonics. 

    Oh, and the command to start it running is "exor09":

    $ ./exor09 --mon
    Load facts file 'facts09'
    'exbug09.bin' loaded.
      EXBUG09-2.1 detected
    'mdos09.dsk' opened for drive 0 (double sided)
    
    OSLOAD...
    
    Hit Ctrl-C for simulator command line.  Starting simulation...
    
    >         0 A=00 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            0020: 86 10        LDA #$10                   
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 
    Everything above looks pretty much the same for the code example above, except for the 6809's extra registers, for assembling, copying and pasting, disassembling, displaying, stepping, setting breakpoints, continuing, tracing:
    % a 1000
    1000: START LDA	#8	; 6809 mnemonic: LoaD accumulator A
    1002:  ADDA	#5	; Mnemonic shared with 6800/6801.
    1004:  ADDA	#2
    1006:  ADDA	#7
    1008:  ADDA	#4 
    100a:  NOP		; landing pad for breakpoint 
    100b: 
    % u 1000
    1000: 86 08               LDA #$08
    1002: 8B 05               ADDA #$05
    1004: 8B 02               ADDA #$02
    1006: 8B 07               ADDA #$07
    1008: 8B 04               ADDA #$04
    100A: 12                  NOP 
    100B: 00 00               NEG $00
    100D: 00 00               NEG $00
    ...
    % d 1000
    1000: 86 08 8B 05 8B 02 8B 07  8B 04 12 00 00 00 00 00 ................
    1010: 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ................
    ...
    $ s 1000
    
             10 A=1A B=00 X=0000 Y=0000 U=0000 S=00FF P=00 -------- START      1000: 86 08        LDA #$08                   
    >        11 A=08 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1002: 8B 05        ADDA #$05                  
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
             11 A=08 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1002: 8B 05        ADDA #$05                  
    >        12 A=0D B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1004: 8B 02        ADDA #$02                  
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
             12 A=0D B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1004: 8B 02        ADDA #$02                  
    >        13 A=0F B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1006: 8B 07        ADDA #$07                  
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
             13 A=0F B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1006: 8B 07        ADDA #$07                  
    >        14 A=16 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --H-----            1008: 8B 04        ADDA #$04                  
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % s
    
             14 A=16 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --H-----            1008: 8B 04        ADDA #$04                  
    >        15 A=1A B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            100A: 12           NOP                        
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    %  
    % b 100a
    Breakpoint set at 100A
    % c 1000
    
    
    Breakpoint!
              4 A=16 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --H-----            1008: 8B 04        ADDA #$04                  
    >         5 A=1A B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            100A: 12           NOP                        
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % t on
    % c 1000
    
              5 A=1A B=00 X=0000 Y=0000 U=0000 S=00FF P=00 -------- START      1000: 86 08        LDA #$08                   
              6 A=08 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1002: 8B 05        ADDA #$05                  
              7 A=0D B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1004: 8B 02        ADDA #$02                  
              8 A=0F B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            1006: 8B 07        ADDA #$07                  
              9 A=16 B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --H-----            1008: 8B 04        ADDA #$04                  
    
    Breakpoint!
    >        10 A=1A B=00 X=0000 Y=0000 U=0000 S=00FF P=00 --------            100A: 12           NOP                        
    
    6809 Monitor: Ctrl-C to exit, 'c' to continue, or type 'help'
    % 

    So, give the 6809 code a try, too, looking for differences. 

    Then take a rest  before proceeding to getting a simulator for the 6801.

     

    (Title Page/Index)

     

    Saturday, June 15, 2024

    ALPP XX-XX -- Running Code on the 6800, 6801, 6809, and 68000

    This chapter got scratched. Kept me spinning my wheels for a month or two. But I want to keep it around for my own reference. 

    Running Code on the
    M6800, 6801, and 6809

    (Title Page/Index)

    So, we want to run code, and we want to see the code run step-by-step.

    If we had, for instance, Motorola's Micro Chroma 68 prototyping board, we could hand-assemble 6800 code and use the built-in debugging monitor to step through it. That is educational, and interesting, but those are hard to come by. (I theoretically may still have one in storage somewhere I can't access right now.) And hand-assembling code does take more time than using an assembler.

    Similarly, Motorola had an evaluation board for the 68000, the MEX68KECB (Educational Board Computer), with a really nice debugging monitor in the ROM that assembled and disassembled code for you (that I probably should have bought way back when). Those ought to be easier to find, if still hard to get owners to part with, but when you search the web for them, you have to wade through a lot of retro devices that reproduce, with varying degrees of reliability, the original, or even just ride on the name. Some of those retro devices are interesting, but you have to know what you're looking at. 

    If I had managed to save up enough to properly retire, I could be building a few retro projects of this sort myself, and could recommend them directly. (Sorry. That didn't happen.)

    Motorola also made a full workstation for developing hardware and software for the 6800 and related parts called EXORciser. (Yes, I think it was a cool, but unfortunate, choice of name.) You could also put in a 6809 processor, for 6809 development. 

    It was somewhat comparable to Intel's Intellec 8 systems, but reportedly more usable as a general purpose computer, comparable to the Altair 8800 and other S-100 systems. 

    And they made a full workstation for developing for the 68000, called EXORMacs. 

    But you probably won't be finding real examples of either of these to use in learning assembly language -- they are very rare now.

    (Yeah, if I had the time and resources, it'd be fun to build retro replicas of both the EXORciser and EXORMacs, too.)

    As an example of a home computer using the 6801, Tandy/Radio Shack's MC-10 (which actually uses the 6803 variant) is still sometimes seen on ebay and elsewhere, and is supported by an active enthusiast community (including a group on Facebook). Even though it's not really intended for learning assembly language, they'll help you gather up software and hardware to make it useful.

    For the 6809, the Tandy/Radio Shack Color Computer is relative easy to find, and is also actively supported by an active (active, active!) community of enthusiasts (many of whom are also in the MC-10 community) who, again, will help you gather up software and hardware necessary to use it to learn assembly language. (Several groups on Facebook, here's one. Also, there's a mailing list that can help with both the Color Computer and the MC-10.)

    The Color Computer's sister computer from the UK, the Dragon, is not easy to find, but the Dragon community is active, and generally participates in the Color Computer groups, too.

    Other options exist, of course, like the SWTPC 6800 and 6809 models, also the French cousin to the MC-10, the Matra Alice. These are rather rare now. Even rarer are the Thomson line of French 6809-based computers and quite a number of Japanese computers (Fujitsu, Hitachi, and others) that used the 6800 and 6809.

    If you look around and are careful about what you get, there are various retro designs that you can build yourself.

    As I've noted, I don't really have room for hardware. If you don't either, you'll be glad to know that software emulators (simulators) are available that run on the kinds of PCs you are likely to already own. 

    If you are running a Microsoft operating system (MSWindows), you'll be able to find several emulators with a fairly quick web search. Members of the support communities will tell you which they favor. I don't have experience with those, so I won't recommend any, but they can be found fairly easily, and are said to be good.

    Also, there are several on-line 6809 emulators, but I don't want to encourage lots of people to jump on those and load them down.

    One emulator I like that runs on my equipment is XRoar, developed primarily by the Dragon community's Ciaran Anscomb. It can currently emulate the Dragon, the Color Computer, the MC-10, and certain versions of the Alice. I like it as a simulator, it's fairly easy to get going and to maintain, and doesn't take up the room that the MAME monster takes up on your hard drive. And the important thing for me is that it can be compiled on Linux OSses.

    One downside to XRoar is that it does not include a lot of hosted debugging tools. You have to find self-hosted debugging software, such as EDTASM+ for the Color Computer, which means additional layers to wade through. (I want to help Ciaran add hosted debugging, but so far we haven't been able to connect when both of us have had the time to get me started.)

    Speaking of MAME, MAME emulation is pretty good, too. But it's big, and complicated, and I don't want to recommend it for the beginner. (I haven't even figured out how to get debugging going on MAME yet, myself.)

    As you noticed, I use a Linux OS, and I will be using simulators that run on those, in particular, Joe H. Allen's  EXORsim. EXORsim was originally just for the 6800, but Joe has recently extended it to simulate the 6809 as the main processor as well.

    There was a 6801 hosted development module (auxiliary card) for the EXORciser, but EXORsim does not simulate that. If I can find enough documentation and time, I may try adding support for it sometime. But not just now. 

    Several years back, I wanted to do something with the 6801, and I had a little time, so I added some code to EXORsim to let the main processor execute the additional 6801 instructions. The cycle-by-cycle timing is 6800 instead of 6801, and I did not add simulation for the 6801's internal devices, but it allowed me to get a version of fig-Forth optimized for the 6801 running and somewhat tested, and even running on the MC-10. So I will use that for the 6801.

    EXORsim can be compiled to run on MSWindows and on Modern Mac OS, so you may want to consider it for that, as well.

    I wish I had time to write an EXORmacs simulator, for the 68000, or even to use musashi or Moira to build a prototyping board style simulator for the 68000 -- Maybe I can do that once I've put enough money away to properly retire, if there's anything left of my mind by then. 

    That failing, for now I'm using the Atari ST emulator, Hatari, for this project. Unfortunately, that requires some compromises, compared with EXORsim, such as not being able to copy text output from the Hatari window with copy/paste. Screenshots, typing by hand, and disk files it will be.

    So you may want to get EXORsim and Hatari to make it easier to follow along with me. These are the tools I will be referring to when I show code running on the 6800, 6801, 6809, and 68000. 

    Hatari is available from repositories in many libre OSses.

    In order to get EXORsim to run, you'll probably have to build it yourself. But it's not that hard, if you have fairly standard tools installed on the computer you are using as a workstation.