The Atari ST MC68000 Assembly Language Tutorials

2002-06-14 (last edition of the initial revision)

In the last few days, I’ve had the great opportunity to get lots of introduction to the Atari scene. mOdmate of Checkpoint told me about #atariscne, and since then he’s guided me through the stuff, giving me links to good sites and generally telling me what I need to know to orient myself. I’ve met some great people that have helped me understand things and being a better coder. Also, let’s not forget the importance of Maarten Martens for converting this text file to html and banging me on the head whenever I take a wrong step. I could not write this stuff alone, lots of thanks to all of you who make this text possible. I also want to thank God, for giving me the luck and opportunity to be where I am, my mother for giving birth to me and always being there and all …​ (end of Hollywood speech)

In order to get an even better understanding of the bit planes, I’ve done an 8 pixel scroller. The thing with this is that you must be careful not to misalign the bit planes, which we didn’t have to worry about when scrolling 16 pixels per VBL. Since not to much have changed since the 16 pixel scroller, I thought I’d cover some other stuff as well.

First, I need to cover the shift command in order to be able to tell you about double buffering (there are more than one shift command, but they’ll be covered later). The shift command will shift bits either left or right, as many "slots" as you want to. The command for shifting left is lsl, meaning Logical Shift Left, and right is lsr for Logical Shift Right. If you have a number in d0 and right shift, like so:

then d0 will contain:

all bits will jump two spaces to the right, and 0’s have moved in from the left. Also note that this was the same as dividing 177 by 4 and throwing away the remainder. Left shifting will move bits to the left, and move 0’s in from the right. Right shifting one is the same as dividing by 2. Thus a lsr.l #2 is the same as divu.l #4, and a lsl.l #2 is the same as a mulu.l #4. Only thing is that a shift is soooo much faster than a mulu or divu, but more on that later. It’s very important to note how big the shift area is, if you have a data register filled with bits, but only shift a word, lsr.b, only the first 8 pixels will be affected. Like so:

Note how the upper byte of the word was completely unchanged by the shift operation, since we used a lsr.b operation.

Now we can go on with double buffering. This is an extremely important technique. The screen is painted by an electron beam that goes from upper left, and then sweeps one horizontal line, down to the bottom right, just as the screen coordinates. Now, what happens if you start to make changes to the screen where the electron beam is painting? You will experience flicker or a distorted line or any other horrible thing. In short, when you write to screen memory, you’ll most likely interrupt the electron beam in its work.

It is possible to change the area of memory that is the screen memory, any area of memory can be the screen memory actually. So for every VBL (or even often), we can change what area of memory is the screen memory. A solution begins to crystallize. We have two screen area sized areas of memory, one which is the actual screen memory (being shown on the monitor) and the other works as a buffer.

What we do is to update the buffer, while leaving the other screen alone, in this way, nothing will happen to the screen memory while the electron beam is painting. Then, just in the beginning of the next VBL, we make the buffer the screen memory and the screen memory the buffer. In this way, we will never paint to the actual screen memory. One can also call the memory that is being displayed for the physical base, and the area of memory not being displayed for the logical base. So far, we’ve gotten the address to the physical base by calling trap #2 of the XBIOS, if you call trap #3, you’ll get the logical base. Usually, both of these point to the same memory area.

Instead of getting the physical address from the Atari, we will now define our own area of memory and input that address directly into memory. There’s only one important thing to know about the screen memory; it must be on a 256 byte boundary (unless you have a STe). What this means is that the start address of the screen memory must be a multiple of 256. This can be achieved by clearing the lower byte of the address, meaning that you’ll need 256 bytes extra memory for your screen memory, so you can clear the lower byte. Why? Because clearing away the byte will clear away anything not multipliable by 256, the size of a byte.

So, how do we make a memory area the screen memory? Smack up the Hardware Register Listing, and search for something appropriate, like "screen". We see this.

Sure, ok, seems to be what we need. The low byte in $ff820d is for STe’s only, and should be cleared at all times to avoid trouble. Then the middle byte of the screen address goes into $ff8203 and the high byte goes into $ff8201. In order to get the middle and high byte of the screen address, we need to shift the address. By shifting down the eight bits constituting the byte, we can easily move out bytes from the screen address by move.b commands.

first we clear the low byte in order to put it on a 256 boundary.

now we need to move the middle byte into $ff8203

As you see, the middle byte gets shifted into the lower byte. With a move.b command the only thing we move is the lowest byte of d0. Thus, we have isolated the middle byte by shifting it into a more convenient position. Now for the last one.

And that’s it. We have now cleared the lowest byte of the screen address, and moved the middle and high bytes of it into the correct memory position. screen is now the screen memory. The compact code snippet looks like this.

Now, this doesn’t make for any double buffer at all, since we’re only using one screen. In order to achieve double buffering, we need two screen areas, and two pointers to point to each area. In each VBL, one screen is made into screen memory, and then the pointers are flipped so that the other screen is made screen memory for next VBL. This really makes what you see on the screen appear 1/50th of a second slower than what you draw.

I also thought we might mention timing as well. This is quite the issue really, as you must have understood, you can’t perform an infinite number of instructions. Important information is in two appendixes. Motorola 68000 Instruction Execution Times explains how much time it takes to do each instruction. This can vary greatly, for example, a division takes way over 100 clock cycles, and a shift takes under 10, so you see, it’s a good thing to replace your divu 's with lsl 's if possible. Also, when you can, work with byte or word size, instead of long, since this saves some time also. Clock cycle is the quantity in which "time" is measured. Each instruction takes a certain amount of clock cycles.

Pixel Timings, was extracted by me from the ST Internals text file by Jim Boulton. One interesting thing to note there is the amount of clock cycles per VBL; 160256. This is a very exact number, and if your main loop ever takes more time than that, you’re screwed (if you work with VBL main loops as we’ve done so far that is). One way to get a graphical pointer of how much time your main routine does take, is to change the background colour just at the start of the routine, then change it back in the end.

Let’s say we have a routine that takes 80000 clock cycles, our original background is black, but in the beginning of our main loop, we set it to red. What will happen is that the electron beam will paint red background, but when our 80000 clock cycles worth of instructions have taken place, the background is switched back to black, which means that for the time it takes to wait for the next VBL, the electron beam will paint black. So, in this case, the screen would be half red background and half black background. If we use this technique, we’ll see exactly how much time our main routine takes. The example program in this tutorial takes up most of the processor, which leaves little time for other stuff to be done. Granted, the scroller is completely un-optimized.

Phew, now we have covered lots of small things of big importance. Finally, now comes the 8 pixel scroller part. Just look at the source code, it’s well commented. Nah, I’m just kidding with you, of course I’ll explain. Since we now want to scroll 8 pixels, this means for starters that we need to move bytes. The first byte represents the first 8 pixels, and the second the coming 8 pixels. Then, the third word again has to do with the first 8 pixels, and the fourth word has to do with the 8 coming pixels and so on. Thus, we cannot simply barge in and do some scroll loop. We need to move every second byte.

It is tempting to read the memory top down, but this is not so, it is to be read from left to right. So index 5 for example is the second byte in the third word, and affects pixels 8 - 15. The memory without comments look like this, split into bytes for ease of reading.

So in order to scroll 8 pixels, index 0, 2, 4 and 6 will de dropped, because they represent the first 8 pixels. Then index 1, 3, 5 and 7 will be moved into index 0, 2, 4 and 6. Then index 8, 10, 12 and 14 will be moved into index 1, 3, 5 and 7. Then index 9, 11, 13 and 15 will be moved into index 8, 10, 12 and 14. This will make pixels 0-7 to drop, 8-15 to be moved into 0-7, 16-23 will be moved into 8-15 and 24-31 will move into 16-23. After these move instructions, the memory will look like this

It is of the utmost importance that you realize why this is so. If you do not, set yourself down and work it out until you get it and understand it 100%. Without understanding this, you’ll not understand bit planes, without understanding bit planes, you can’t understand how the graphics on the Atari works. Expressed in code, this will be (a0 points to screen memory)

and so on. So first, four bytes are moved just one step to the left, but then you need to go into the next 4 word area, to fetch the bytes that go into the second area of the first 4 word area and so on. This is the theory behind 8 pixel scrolling, I don’t think I can explain it better than that. This is the source code for the scroller.

Not too much has been changed since the 16 pixel scroller. In the beginning, there’s the code for setting up two screen areas. Then, in the main routine, we put one screen address in. Notice also how the font_counter is now 4 instead of 2, because we only need new font data every fourth VBL. The scroller part however is completely new, not surprising is it? It begins with loading both screen areas into a0 and a1, and then flips them for next time around. Data is moved as described above for 19 loops, this means 304 pixels are moved, the last 16 need special care though.

First 8 pixels scrolled as usual, but the last 8 must come from the font. This is also not to strange, since every second byte is moved into the second bytes of the words on the screen. Then 1 is added to the font address, to point to the second bytes in the words. However, this won’t quite do, as you may know. The step from the second byte of the first 16 pixels to the first byte of the coming 16 pixels is a bigger jump than 1, as described above.

In order to make this bigger step, I test the font_counter, to see if it’s time, and then add another extra 6 to the font, making it point to the right place. If we don’t do this extra addition, 16 pixels will be moved in from the font ok, but when pixels 16 - 24 are about to be moved, the font address will point to index 2 (meaning the first 8 pixels again) instead of index 8 into the font memory. Just scroll up to the memory example, then work through the scroll loop on a piece of paper or in your head and it will hopefully become obvious. If it doesn’t, mail me.

That, I think, was that. The big problem here is the understanding and alignment of bytes in the bit plane. What to keep in mind really is that first, take every second byte, then jump a bit to get on the next 16 pixel boundary, then continue in that way. Indexing goes like 0, 1, 8, 9, so to speak. Thus, every second time there’s a little gap. Since I didn’t do any timers this tutorial, maybe we’ll do them next time.