COURS203.TXT

Languages:

English  • français

******************************************************************
*                                                                *
*             68000 ASSEMBLER COURSE ON ATARI ST                 *
*                                                                *
*                 by The Ferocious Rabbit (from 44E)             *
*                                                                *
*                         Second series                          *
*                                                                *
*                         Course number 3                        *
******************************************************************

Before continuing to study these courses, I think it's time for
you to study all the 68000 instructions. You should now have
enough basics to realize small programs and especially you
must have become accustomed to the system that consists in
typing only 2 or 3 lines of programs and then visualize their function with MONST.

So, take the 68000 book you normally acquired, and tour all the 
instructions with this method. Observe well the results of the 
shift operations (ASL, ASR, etc.). It's not about knowing them 
by heart but at least to know they exist to find them easily, if needed,
and especially to be able to understand what they do. The number of 
instructions is small, but each performs a very specific operation that
should be known in the finest details. It's not enough to know 
that ROR performs a rotation to the right, you must also know that the 
bit ejected on one side is put back on the other and, in addition, it 
is copied into the C bit of the SR. It should be noted also that ROR #4,D0 
is accepted but not ROR #9,D0. In that case, you have to do 2 RORs 
or MOVE.W #9,D1 then ROR D1,D0. It's this kind of little tricks that will block you later 
if you haven’t spent a few hours dissecting them!

FILE INCLUSIONS

One of the biggest problems with ASSEMBLER is related to the size of listings. If, in BASIC, one line is enough for a sometimes very complex operation, we have seen that this is not the case in ASSEMBLER. On the other hand, we also saw that writing in ASSEMBLER consists in typing the right number of machine instructions, while the BASIC, C, or PASCAL compiler manages to do a 'working' translation, which is therefore not necessarily the most economical in terms of size and/or speed.

On the other hand, our ASSEMBLER sources quickly make pages and pages where a programmer working with an 'advanced' language would only have a few dozen lines. However, there are some methods to reduce significantly the size of the listing we're working on.

Two directives will mainly serve us. Beware, these are not ASSEMBLER instructions, but orders interpreted by the ASSEMBLER. So these are, in our case, 'Devpack' instructions and not '68000' instructions.

The first one, INCBIN, allows to incorporate a binary file into 
the program. A binary file can be an image, a digit, sprites, etc... or a piece of program that has been assembled in the form of a binary file. Here is an example with an image. (listing 1 series 2)

First, we transfer the image address in A6, we skip the header to point to the colors, which are set with Xbios(6), then we search for the screen address with the Xbios(3) function and, after having skipped the color palette of our image, we transfer this image on the screen. A screen is 32000 bytes. If we transfer it long word by long word, we only have to transfer 32000 divided by 4, i.e., 8000 long words. As we are using a DBF loop that counts up to 0 included (the loop stops when the counter reaches -1), we must therefore initialize the counter to 7999. Then wait for a key press and bye-bye.

Small educational exercise. Once this program is assembled, follow it under MONST. When Xbios(3) has given the screen address, place window 3 on this address then continue to advance the program step by step to see the copy happen. From time to time press the V key to see the screen instead of MONST, you can thus follow the display 'live'!!!

Another small exercise: The ST has the particularity of having somehow 2 screens: the screen on which we work (Xbios(2)) and the one we can see (Xbios(3)). In most cases, it's the same but it is totally possible to place them at different memory locations and thus prepare a display in xbios2 while showing Xbios3. It will then be possible to quickly display Xbios2 by transferring it to Xbios3, thus, making fast animations. Try to change the program listing a bit and put MOVE.W #2,-(SP) instead of 3 to search for the screen. Debug the program and see!

But this takes us a bit far from the subject which was inclusion. To make this, we just provided a positioning label which is here IMAGE then the instruction INCBIN followed by the path to find this image. In the example it's a PI3 image, but nothing prevents you from putting a PI2 or PI1 image! We could very well have put 2 images back to back, without putting a label to spot the second. To point to it, knowing that a DEGAS image makes 32066 bytes, we would have done:

            LEA       IMAGE,A6
            ADDA.L    #32066,A6
I remind you this reads: load effective address IMAGE in A6 
add address long...

Small exercise: make a program that runs in medium resolution, switches to low, displays a low resolution image, waits for a key press then switches back to medium. Knowing how to use Xbios functions and loops, you should be able to make one routine to save the palette and another to restore it.

It is entirely possible to include very diverse files this way. However, there are several problems. First, the size of the resulting program. Indeed, our DEGAS image, due to its size, has grown our program by 32Ko! Of course, now there is the advantage of being able to prevent tinkers from coming to put their feet there! Even though a DEGAS image is always the same size, it is possible to include a compacted image (putting of course a decompression routine in our program!).

Another problem, time! Indeed, if the display itself is faster because there is no need to fetch the image from the floppy disk since this image is already in memory with the program, it's during assembly that it drags!!! It is therefore necessary to go through well-ordered work mechanisms. Set up a virtual disk (preferably resistant to Reset) copy the images into it and then start working. You will quickly understand why 520 owners have every interest to have them expanded to a minimum of one mega and why an external drive or better a hard drive becomes essential quickly!!!

After having seen the mechanism of file inclusion, we will now look at listing inclusions. It is indeed possible to take a piece of the listing, save it to a floppy disk, and ask the assembler to include it during assembly. There, too, there is a waste of time assembling but a very significant time saving when creating the program. For example, your palette saving routine: carefully made, it works well and in fact you need it in all your programs. It is therefore necessary each time to retype it and especially consume a few dozen lines with this routine. Time waste, possibility of typing error, and unnecessary extension of the listing. When you start browsing 10 or 20 pages of sources to look for a variable, you will start to understand what I'm talking about, knowing that 20 pages are just a tiny assembler source...

Let's see a concrete example, with the palette saving.

SAUVE_PALETTE
            MOVEM.L   D0-D4/A0-A4,-(SP)
            LEA       ANC_PAL,A4            point to the save location
            MOVE.W    #15,D4                16 colors

   .ICI     MOVE.W    #-1,-(SP)             color request
            MOVE.W    D4,-(SP)              color number
            MOVE.W    #7,-(SP)              Setcolor()
            TRAP      #14                   Xbios
            ADDQ.L    #6,SP
            MOVE.W    D0,(A4)+              saving the color
            DBF       D4,.ICI               and we move to the next one
            MOVEM.L   (SP)+,D0-D4/A0-A4
            RTS
ANC_PAL  DC.L      0,0,0,0,0,0,0,0
REMETS_PALETTE
            MOVEM.L   D0-D4/A0-A4,-(SP)
            LEA       ANC_PAL,A4            point to the save location
            MOVE.W    #15,D4                16 colors

   .ICI     MOVE.W    (A4)+,-(SP)           color request
            MOVE.W    D4,-(SP)              color number
            MOVE.W    #7,-(SP)              Setcolor()
            TRAP      #14                   Xbios
            ADDQ.L    #6,SP
            DBF       D4,.ICI               and we move to the next one
            MOVEM.L   (SP)+,D0-D4/A0-A4
            RTS

Here are therefore 2 routines. First of all, knowing that a call to Xbios does not save the D0-D3 and A0-A3 registers, we use D4 and A4 for the color counter and the storage address, which also explains saving on the stack at the start of both routines. The first routine saves the palette and puts it at the ANC_PAL address. We notice that this address is between the 2 routines. Indeed, several solutions are available to us. First, the most economical in size is to put this reservation for the palette in the BSS section of our program by doing ANC_PAL DS.W 16. We have already seen that the BSS section does not take up space on the floppy disk. However, we made these routines with the idea of including them, to gain in ease of programming. By placing this reservation between the routines, it becomes an integral part of the file. It's not possible to put it in DS therefore we are obliged to put it in DC. The danger would be that our program tries to read this part. Doing a BSR ANC_PAL, for example, would be fatal but we are serious enough not to do it, so no problem...

Once you have typed this small listing, save it for example under the name SAUV_PAL.S. Then modify the program of listing 1 (the one we just saw with the included image). Just after the end of the program by MOVE.W #0,-(SP), TRAP #1 (so just before including the image), put

            INCLUDE   "A:\SAUV_PAL.S"

Do not put a label on the left margin since the first label is SAUVE_PALETTE and it is in our routine. Then at the very beginning of the program, put BSR SAUVE_PALETTE and at the end just before leaving, put BSR REMET_PALETTE. Size-wise, your listing is therefore simply increased by 3 lines:

   (BSR SAUVE_PALETTE, BSR REMET_PALETTE, and INCLUDE "A:\SAUV_PAL.S")

and yet it's 24 lines that are added!!!

We are therefore in the process of creating a library. It's a very big part of the assembler programmer's job because many things often come back: initialization by saving the palette, switching to low resolution and passing to Supervisor, restoration by doing the opposite, decompression of images, etc.

Similarly, if you are in the process of creating a large program, during development, entire pages can be included decreasing the size of the listing and allowing for much easier movement.

Let's immediately see another block that should now be part of our library. Up to now, we have typed a lot of small programs without worrying about the memory space. It's time to think about it to start becoming aware of the fact that we need to program cleanly. Let's imagine that our program is in memory but at the same time there are other programs in this memory. It's clear that each one must only appropriate the memory space it needs to leave as much as possible for its neighbors. For this, we need to know that during assembly into an executable file, a header is generated. Thanks to this header, upon the launch of our program, what is called the base page will be created. Here is a description of it. If you want to get the most information on program headers or base pages, refer to the corresponding chapters in the Bible or the Developer's Book. Excellent chapter on this subject in the ATARI official documentation (document on program structure).

* Base page

Address         Description
$00      Base page start address
$04      End address of free memory
$08      Start address of the TEXT section
$0C      Size of the TEXT section
$10      Start address of the DATA section
$14      Size of the DATA section
$18      Start address of the BSS section
$1C      Size of the BSS section

We will therefore get this information and deduce the size that should be enough for our program. Knowing the location of the implantation zone of the program, we will use function 74 of the GEMDOS (Mshrink function) which allows, by giving the desired size and the end address, to shrink a memory area. Indeed, at the launch our program has taken all the available space, we must therefore shrink it. Our program also needs a stack. Instead of taking the one that is already in place, we will replace it with ours, whose size we can set at will.

* PROGRAM START ROUTINE

            MOVE.L    A7,A5                 retrieves stack pointer to take
                                            * parameters
            LEA.L     STACK,A7              imposes our stack
            MOVE.L    4(A5),A5              address of the base page from
                                            * the old stack
            MOVE.L    12(A5),D0             size of the text section
            ADD.L     20(A5),D0             + size data section
            ADD.L     28(A5),D0             + size bss section
            ADD.L     #$100,D0              + length of the base page
                                            * (256 bytes)

* Calling the MShrink() function from GEMDOS (Memory Shrink)

            MOVE.L    D0,-(SP)
            MOVE.L    A5,-(SP)
            MOVE.W    #0,-(SP)
            MOVE.W    #74,-(SP)             M_shrink()
            TRAP      #1
            LEA       12(A7),A7

After this operation, our program only uses the memory space it needs. Do not forget to define the stack in the BSS section like this:

            DS.L      256
STACK    DS.L      1

I see some of you are surprised by this reservation!!! In the examples provided with DEVPACK it says "stack go backwards", which I loosely translate as "as I go forward, the stack goes backward, how do you want me to..." A bit of seriousness. We have seen that the use of the stack is done by decrementing it:

   (move.w        #12,-(sp) for example).

So, we must reserve space BEFORE the label. For this reason, we note the label and, above, the real size reserved for the stack.

What size to choose? It's up to you! If your program is full of subroutines calling each other and saving all registers each time, you need to plan big.

Type the following program. It goes without saying that you must have typed beforehand the program start routine which is a little higher in this course. It is included here at the beginning. No branching to it. If, once assembled, you debug this program, you will see the start routine at the beginning. From now on, this routine will always be present at the beginning of our programs but will never be fully copied again, an INCLUDE is much more convenient! Note: It seems that DEVPACK sometimes gets confused when there are numerous inclusions and calls to files contained in folders. Similarly, there are problems with inclusions on drive B when it is taken as drive A in which you put the drive B disk. (on the other hand, I did not encounter any problem with my external drive).

            INCLUDE   "A:\START.S"
            MOVE.W    #$AAAA,THING
            BSR       SOMETHING
            MOVE.W    THING,D6
            MOVE.W    #0,-(SP)
            TRAP      #1
*---------------------------------------------------*
SOMETHING  MOVEM.L  D0-D7/A0-A6,-(SP)
            BSR       STUFF
            MOVEM.L   (SP)+,D0-D7/A0-A6
            RTS

STUFF      MOVEM.L   D0-D7/A0-A6,-(SP)
            MOVE.L    #$12345678,D0
            MOVEM.L   (SP)+,D0-D7/A0-A6
            RTS

            SECTION BSS

THING      DS.W      1
            DS.B      124
STACK      DS.L      1
            END

This program is of course bogus. I hope, however, that you
   have typed it scrupulously. Launch it... boom, 4 bombs!!!!!

   Let's examine it closely to understand why... The start
   is properly set up and when we debug it is executed
   without incident. We then place $AAAA in the variable BIDULE.
   Activate window 3 and point to BIDULE (just do Alternate A and type the label name in uppercase so
   here BIDULE). Move step by step, we see BIDULE
   receive AAAA. Continue advancing: we jump into TRUCMUCHE
   with the return address saved in the stack (about
   this, you can point window 3 to STACK and
   watch the data being stacked above). Then we are going
   to jump into MACHIN but there, stop!!!!!!! Follow the
   explanations carefully. Just before executing the BSR MACHIN, scroll
   window 1 down with the 'down arrow' key. Indeed,
   according to the size of the listing and the window, you should not
   see BIDULE. So scroll down 7 lines. Normally, the
   first line of the window should now be BSR MACHIN with
   the small arrow facing it indicating that this instruction is
   going to be executed. At the bottom of the window, you should see BIDULE
   with DC.W $AAAA in front since that's what we placed there.
   Below are the ORI.B#0,D0. Indeed, we are in a
   window trying to show us the disassembly of what is in the memory. At this location, there is 0 in the memory which
   corresponds to ORI.B #0,d0; this explains these instructions. But
   what do these ORI.B correspond to? Where are they located? Well, they
   are in our stack since it consists of a 124-byte block between
   BIDULE and STACK. So now scrutinize BIDULE very
   carefully and advance the program by one step. Here we are
   now on the MOVEM.L line of the subroutine MACHIN. Execute
   this line...

   Astonishment, BIDULE is overwritten, as well as the RTS of the subroutine
   MACHIN which is just above!!! And now, if we
   continue, after the second MOVEM the 68000 will not encounter
   the RTS since it has just been overwritten, and our program will
   crash! Why? Well, because we tried to stack
   128 bytes (MOVEM from trucmuche=15 registers so 15*4=60 bytes,
   the same for the MOVEM from machin, plus the return address for
   trucmuche and machin, total 128 bytes!) whereas
   we only planned a stack of 124 bytes.

   For this program to work without a problem, we must therefore put at
   minimum a stack of 128 bytes. Be very careful about this, because if
   we had put a stack of 124 bytes, the program would not have
   crashed because there would not have been overwriting of the RTS but
   there would have been overwriting of BIDULE and I am certain that you
   would have looked for a long time asking yourself "but what can
   possibly overwrite BIDULE" especially since this overwriting occurs at
   a moment when, precisely, we do not use BIDULE!!!

   Always keep in mind the principle of the memory tube,
   without forgetting that it is full of instructions, variable contents and that nothing prevents them from being overwritten!

   Another small remark about the Start. It is entirely
   possible to test D0 on return from Mshrink(). If it is
   negative, there has been an error. If you know that systematically you put the BYE_BYE label in front of the GEMDOS(0) which ends your program, you can add at the end of the start:

            TST.W     D0
            BMI       BYE_BYE

   One last clarification on inclusions. There are other
   ways to achieve such things, for example by assembling the
   pieces and then linking them with a LINKER. This solution is
   interesting when programs start to become gigantic.

   Otherwise, it's more hassle than anything else!!!! Even if
   some purists prefer linking:
   
   I edit, I assemble, I quit, I link, I launch, it crashes, I
   debug, I edit, etc...)

   I prefer, for my part, the method of "include". It allows
   possibly direct access to the source. For example,
   if your palette save routine crashes, place the cursor
   of GENST on the line INCLUDE "A:\SAUV_PAL.S" then choose
   the Insert File option in the file menu. Your routine is
   now in front of your eyes. Once this block is finalized,
   delimit it with F1 and F2 then save it with F3, and there you go!

   End of the course on inclusions! Start building your
   library and don't hesitate to make backup copies,
   and beware of viruses! On this disk, there is IMUN.PRG
   You put it in the Auto folder on your boot disk, and it
   checks all the disks you insert into the
   drive!

Back to ASM_Tutorial