Atari WozMon for ABBUC Software Contest 2023

[freetz]

Hi everyone,

 

this is my contribution for this year's ABBUC software contest:

Atari WozMon

 

Atari WozMon is an Atari 8-bit adaptation of the machine language monitor which was built into the Apple I. Since this was programmed by Steven Wozniak at that time, this software is affectionately called "WozMon" since then. Especially remarkable is that this program uses less than 256 bytes of memory and still provides the basic functions of a machine language monitor: You can use it to read or modify single values or entire memory blocks, as well as target specific memory addresses to start a program.

 

Even today such a tool is still extremely useful if you still program directly on the "real" hardware. Because instead of writing long series of POKEs to change memory locations (or not having the possibility to do so under DOS in the first place), you can write the values directly into the desired memory locations with a quick jump to Atari WozMon. If you know the hexadecimal values of assembler commands, you can even program directly in machine language while using BASIC.

 

Just changing the display list and store a small machine language routine for the display list interrupt? No problem (screenshot 4).
Quick direct access to the screen memory? Quickly done (screenshot 3).
Quickly read out a memory area? Nothing easier than that (screenshot 2).

 

After loading, Atari WozMon is stored in Page 6 where it is protected from BASIC, DOS or other programs and can be called again and again if needed.
To follow the ABBUC rules, an extra startup screen has been placed in Page 4, but this is not needed for the rest of the program. You can call the tool from BASIC with X=USR(1024) (with start screen/short manual) or X=USR(1536) (directly to the monitor) or from DOS with M (Run Address) and then 401 or 601.

 

Atari WozMon has several advantages over the original, including the use of Atari's operating system screen routines. This makes Atari WozMon fit seamlessly into the BASIC editor, so that e.g. the screen content of BASIC is preserved when Atari WozMon is called, and even after quitting, the screen is not cleared, as you can see on the screenshots.

Atari WozMon is thus a useful tool that you can simply run as AUTORUN.SYS on the DOS disk, it does not consume any BASIC memory and is always ready when you need it.

 

The functions of Atari WozMon with examples:
(All memory locations are noted in hexadecimal, letters must always be uppercase, maximum input length is 36 characters per line).

 

Reading the memory location $0600:
 

600
0600: D8

 

Reading several memory locations:
 

600 604 60B
0600: D8
0604: 01
060B: A9

A dot before the address outputs all memory locations from the last used memory location ($060B in the last example) to the memory location after the dot:

.60F
05 9D 42 03

 

Reading memory range $0600 to $060F:
 

600.60F
0600: D8 A5 06 F0 01 68 A9 9B
0608: 20 DD 06 A9 05 9D 42 03  

 

Write memory location $A800 with value $A0:
 

A800:A0
A800: 00

The previously(!) contained value is output here. A repeated readout then brings the new value:

A800
A800: A0

 

Writing of several values from memory location $A800:
 

A800:A9 03 8D 00 A9
A800: A0

Only the first (previously contained) value is output. Check the writing by reading the memory area:

A800.A807
A800: A9 03 8D 00 A9 00 00

 

Jump (JMP) to the memory address and execute the program code there:
 

A79F R

(Jumps to the DOS 2.5 start address. Recommended way instead of "X" to get from Atari WozMon back to DOS under DOS)

 

Exit Atari WozMon (and get back to BASIC if necessary):
 

X

(DOS 2.5 unfortunately executes a JMP (and no JSR), so X does not work here. To get back to DOS, a jump to the memory location

 

Screenshot 1: Start of Atari WozMon with short instructions from BASIC (start address 1024), displaying memory from $0600 to $0607:

Screenshot 2: Direct start of the AtariWozMon monitor (start address 1536), displaying memory from  $0600 to $063F:

Screenshot 3: Read screen memory vector ($58/$59, dec. 88/89), then write directly to screen memory ($9C40 and $9F60):

Screenshot 4: Change the Graphics 0 display list by setting the DLI bits, create a DLI routine starting at $400, return to BASIC, activate the DLI by POKEs:

 

 

Edited July 3, 2023 by freetz
Typo

[+MrFish]

1 hour ago, freetz said:

Page 6 where it is protected from BASIC

Protected from (probably) 99.99% of BASIC programs (not using page 6 specifically for their own purposes). If an INPUT statement retrieves more than 128 bytes, page 6 (from 1536 to 1663 -- $600 to $67F) becomes an overflow buffer.

 

The situation is much worse for all those BASIC programs storing their machine language routines in page 6.

 

[freetz]

Yes, I know, it's even worse as it's just 128 Bytes and not 128 kB ;). But I wonder whether it's possible to receive that many characters or whether the three line boundary (as it is for entering a program line in BASIC) will cut the input off after 3x40=120 characters?

While looking for free space to put the code, Mapping the Atari says that $480 to $4FF is free, but when in BASIC, I saw that $480 to $4AF was regularly used by something I could not identify. So I guess the bottom line is that there is no real safe memory area of significant size if you want to cover both BASIC and also the 16K/48K machines...

[+MrFish]

23 minutes ago, freetz said:

Yes, I know, it's even worse as it's just 128 Bytes and not 128 kB ;).

Oh, yeah... 128 KB would be really safe (if there was some other safe location of that size). haha

  

23 minutes ago, freetz said:

But I wonder whether it's possible to receive that many characters or whether the three line boundary (as it is for entering a program line in BASIC) will cut the input off after 3x40=120 characters?

I've already encountered the situation: it's when INPUTting from a file with lines in excess of 128 bytes.

 

[freetz]

Ah, ok, good to know, thanks!

[Irgendwer]

33 minutes ago, freetz said:

So I guess the bottom line is that there is no real safe memory area of significant size if you want to cover both BASIC and also the 16K/48K machines...

If you like to take the challenge, you could go for completely relocatable code and put that into a string...

[freetz]

Hmmm, I like it - but is there a way to deal with JSRs in relocatable code? Self-modifying code that uses the program counter at the beginning of the program to adjust the JSR destination addresses?

But even if that works, it would still have to be stored in some BASIC program line and thus could easily be overwritten as well (let alone NEW'ed out)...

[adam242]

I can't believe that it's 2023 and this is just now happening. Well done.

 

Atari should've built this into the 1200XL instead of the useless Fuji rainbow screen, or into the other XLs and XEs as part of the self test code.

[reifsnyderb]

18 minutes ago, adam242 said:

I can't believe that it's 2023 and this is just now happening. Well done.

 

Atari should've built this into the 1200XL instead of the useless Fuji rainbow screen, or into the other XLs and XEs as part of the self test code.

Atari appeared to be trying to make everything "user friendly".  While WozMon was cool, it was developer friendly.

[adam242]

@reifsnyderb When the ABBUC contest is over and the appropriate conversations have been had, any chance of this being included in your new OS?

[reifsnyderb]

1 minute ago, adam242 said:

@reifsnyderb When the ABBUC contest is over and the appropriate conversations have been had, any chance of this being included in your new OS?

I think it's possible.  I just checked and I think there is space for both the XL/XE OS 6.10 (6.20?) and OS-2023-C (for the 800).

[+DjayBee]

Coincidentally, ben Eater uploaded a video to YouTube over the weekend that explains WozMon's inner workings in detail.

 

There a some nifty tricks used.

 

 

[freetz]

Good to know that it's now public, I saw the video in his Patreon feed, but those links you are not supposed to share. And yes, it's awesome in which ways Woz made use of the internals of the Apple I (and how Eater is able to explain them with such ease) :)...

[+Larry]

Certainly very interesting and of historical importance, but we already have several great monitors, including "the king" (IMO) -- Omnimon.  That said, it would be great to have this one built into a regular XL/XE OS.

[freetz]

Yes, it started out out of historical interest, but I then figured that none of the existing monitors would run without hardware modifications on all Ataris and at the same time be seamlessly accessible from within BASIC. For me personally, this really adds value when coding in BASIC on a real machine – and hopefully for others, too :)...

[freetz]

To get a better impression on what you can do with Atari WozMon, I have recorded a short demo showing its capabilities. Enjoy!

 

[+slx]

That DLI trick is great. Wish we could have shown this to the C64 guys in the 1980's

[djpoptart1]

@freetz I was wondering how you did the reading of a character from the keyboard.  Would you be willing to share the code?  I have tried something in the past using a read of $02FC on my Atari 800xl, but it returns a keyboard mapping and not the ATASCII character.  I needed to do a look up table to convert, but takes an extra 256 bytes of memory.

 

Pat

[reifsnyderb]

I still have space reserved, in OS 6.x, for Atari Wozmon, if the code is released.   🙂

 

[freetz]

@reifsnyderb Sure, feel free to use whatever you like (proper credit would be nice), here's the GitHub repo:

https://github.com/fredlcore/AtariWozMon

@djpoptart1 No, $02FC does not work at all. All the necessary conversions would have blown the 256 Byte limitation. I'm using the CIO routines of the OS. That has the huge advantage that you can seamlessly switch between WozMon and BASIC without destroying the screen.

[reifsnyderb]

1 minute ago, freetz said:

@reifsnyderb Sure, feel free to use whatever you like (proper credit would be nice), here's the GitHub repo:

https://github.com/fredlcore/AtariWozMon

@djpoptart1 No, $02FC does not work at all. All the necessary conversions would have blown the 256 Byte limitation. I'm using the CIO routines of the OS. That has the huge advantage that you can seamlessly switch between WozMon and BASIC without destroying the screen.

Thanks!   🙂