Goal:

One week ago everything I knew about the Atari ST could fit in this sentence: “The Atari ST was a computer.” The past week I have studied it and have built the knowledge required to start programming on it. Follow me and I’ll show you what I learned. I will show you how to write software in 68k assembly on one of the iconic computers of the 80’s.

Background info on the Atari ST:

The Atari ST was a reasonably priced computer released in 1985

It’s competitors were things like the Macintosh, Apple //GS, Amiga, 80286 IBM PC Compatibles

It ran on the Motorola 68k chipset @ 8mhz

The 68k chips have 24bit addresses which gave it access to a possible 16M of memory (max size on the Atari ST is 4M)

The Atari ST shipped with Atari TOS (The Operating System)

It could be run in 3 different resolutions: 640×400 in black and white, 640×200 in 4 colors, 300×200 in 16 colors

You had access to 2^9 different colors but a max of 16 are used at once [thanks for the correction Chris]

It came with a GUI called GEM

Setting Up The Emulator:

You didn’t think we were actually going to program on a real Atari ST did you? Who has room for that sort of stuff? Apparently not us says my wife. For this tutorial we are going to use Hatari. I didn’t shop around, but this emulator seems pretty awesome. I recommend it. If you are on Mac OS X it’s easy to install with macports (‘sudo port install hatari’) and on Ubuntu it should be in apt-get (‘sudo apt-get install hatari’). Macports gave me a valid bootable install that runs EmuTOS (a free replacement for Atari TOS), but Ubuntu gave me an install that can’t boot because it can’t use the EmuTOS image. Don’t worry about that, we are going to use the easily obtainable Atari TOS anyways. Maybe everything works with EmuTOS, I don’t know I didn’t try it.

Here is a screenshot of what you’ll be seeing right about now when you start Hatari:

Okay, right about now, if you are like me you are probably asking yourself what is up with the crappy borders around the Desktop, I know! I mean, I don’t know. The Commodore 64 had that too and the physical machine had that, we’ll be removing it, don’t worry. Here is the next steps to getting your Hatari installation souped up:

Download Atari TOS 2.06, the one I’m using is named Tos206us.img Make an empty directory on your computer to pretend to be your Atari Hard Drive In Hatari press F12 to get to the settings Go to the ROM section and choose the TOS 2.06 image Go to ‘Hatari Screen’ and select Atari Monitor Mono (trust me! we can play with color later) Go to “Hard disks” and select the directory you made under “GEMDOS Drive” Then go back to settings and select the “Reset machine” radio button and click the “OK” button

Now your Hatari should look like this:

*High-Five* now your system is setup and ready to get the dev tools going.

Setting Up The Development Tools:

For this bit we are going to use the assembler called DevPac3. I’ve heard TurboAss is good too (giggle), but I found more resources talking about DevPac3 thanks to the Demoscene. The version I’m using is DevPac 3.10 by HiSoft. Finding it shouldn’t be difficult with an internet search. If you find it as an “.st” file you are in luck, that’s a floppy image, you can skip the next section.

If you download Devpac and it comes as a directory of files: You could try to be a wiseguy and drag the files to your directory you selected as your hard-drive then run DEVPAC.PRG from there like I tried, but you’d be wrong! (maybe). My installation was giving me troubles because it wanted to be run from the floppy drive. You may get errors when starting DevPac. In this case, go into the Hatari settings (F12), then go to ‘Floppy disks’ and make a new floppy image, put it into a floppy drive, then drag your DevPac files into that floppy disk and run DEVPAC.PRG from the floppy from now on.

So, open up your disk or folder with DEVPAC.PRG and double click it to run. You should now be seeing this:

Your default settings for DevPac should be good. There is just one thing we want to make sure is set. If you go to Options -> Control… make sure that Format is set to “ST RAM” This is going to make it so that when we assemble it puts the code straight into memory so we can execute it directly. Another option that will be useful later is selecting “Atari executable” which will be necessary to make a PRG file.

Running Code:

Okay, this post is getting long so for those impatient types I’m going to give you the code to type in:

intin equ 8 ; setup some constants ptsin equ 12 colbit0 equ 24 colbit1 equ 26 colbit2 equ 28 colbit3 equ 30 lstlin equ 32 lnmask equ 34 wmode equ 36 x1 equ 38 y1 equ 40 x2 equ 42 y2 equ 44 init equ $a000 setpix equ $a001 getpix equ $a002 drwlin equ $a003 start: jsr initialize dc.w init ; call line a init move.w #1,colbit0(a0) ; setup arguments to draw line move.w #1,colbit1(a0) move.w #1,colbit2(a0) move.w #1,colbit3(a0) move.w #0,lstlin(a0) move.w #$ffff,lnmask(a0) move.w #0,wmode(a0) move.w #0,x1(a0) move.w #0,y1(a0) move.w #100,x2(a0) move.w #100,y2(a0) dc.w drwlin ;call line a draw line move.w #7,-(a7) trap #1 ;wait keypress addq.l #2,a7 jsr restore clr.l -(a7) ;call gemdos trap #1 initialize: ; go into super user mode clr.l -(a7) move.w #32,-(a7) trap #1 addq.l #6,a7 move.l d0,oldstack rts restore: ; go back into user mode move.l oldstack,-(a7) move.w #32,-(a7) trap #1 addq.l #6,a7 rts oldstack dc.l 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 intin equ 8 ; setup some constants ptsin equ 12 colbit0 equ 24 colbit1 equ 26 colbit2 equ 28 colbit3 equ 30 lstlin equ 32 lnmask equ 34 wmode equ 36 x1 equ 38 y1 equ 40 x2 equ 42 y2 equ 44 init equ $ a000 setpix equ $ a001 getpix equ $ a002 drwlin equ $ a003 start : jsr initialize dc . w init ; call line a init move . w #1,colbit0(a0) ; setup arguments to draw line move . w #1,colbit1(a0) move . w #1,colbit2(a0) move . w #1,colbit3(a0) move . w #0,lstlin(a0) move . w #$ffff,lnmask(a0) move . w #0,wmode(a0) move . w #0,x1(a0) move . w #0,y1(a0) move . w #100,x2(a0) move . w #100,y2(a0) dc . w drwlin ; call line a draw line move . w #7,-(a7) trap #1 ;wait keypress addq . l #2,a7 jsr restore clr . l - ( a7 ) ; call gemdos trap #1 initialize : ; go into super user mode clr . l - ( a7 ) move . w #32,-(a7) trap #1 addq . l #6,a7 move . l d0 , oldstack rts restore : ; go back into user mode move . l oldstack , - ( a7 ) move . w #32,-(a7) trap #1 addq . l #6,a7 rts oldstack dc . l 0

You could always just save this code to disk in your hard drive folder then load it from DevPac but then you would miss out on the satisfying clicky sounds that the Atari ST makes while you type.

Now that you have the code in memory lets assemble it! Go to Program -> Assemble, watch the fun assembling happen, if you have errors in your transcription you’ll see them here. Now assuming that went well you’ll have your assembled program in memory too, lets just run it by going to Program -> Run. And now you should see this:

Whoa! Watch out, don’t get angry! We actually did something, look in the top left-hand corner… no closer, look there is a diagonal line there! We did that! Okay, you are right I should have warned you at the beginning of the article that the program was lame. But it is understandable and digestible for a first program. Press any key to exit once you are done soaking in the wonderful line.

Explanation of the Code:

Here is a quick rundown of the code. In the first section of the code we are just creating aliases to offsets and commands. All of those constants I got from the Atari ST Internals book [see references]. Next we jump to the subroutine (jsr) initialize which sets us up for Super User mode. I didn’t actually test to see if Super User mode is required for the demo but why not go Super, we can handle it. When initialize returns (rts) we are going to call Line A init. Line A is the package of drawing calls we are using. There are other ways to draw on the Atari ST. I think these are the fastest least portable graphics calls (any greybeards to correct me?). The weird thing about that call is that it is happening with the dc command which is just putting that data directly into our code instead of using some sort of call opcode. If you check out the documentation for init you’ll see that it sets up register a0 with a struct we can edit to set parameters to other Line A calls. We do that in our next section to setup the parameters to the draw line function. Then we finally call the draw line function on line 35. Then we are going to use a GEMDOS function to wait for a key press (function 7 of the GEMDOS which is trap 1) on line 37-38. Now that we have a keypress we are just going to restore User Mode, then call the GEMDOS exit function on line 42.

Conclusions:

In some ways Atari ST development is better than the development I do today for iOS. In other ways its a bit clumsy. A dark shadow falls over me when I think about all the hours of work spent by Atari ST engineers to build something almost lost to oblivion. The silver lining is the amount of love that still exists by a select few fans of the Atari ST. I can’t help but think about the similarities between software development and Sand Mandala. Maybe I’ll get around to figuring out how to do animation next, we’ll see.

References: