Mastering Amiga Assembler

The birth of assembly language didn’t solve all of the problems that the early programmers faced. To start with, programs written in low-level languages are processor specific so they are not portable, ie not easily made to run on different processors. Another problem is that you have to express what you want to do in terms of the instructions which are available on the processor and this means working primarily with bits and bytes. Any other data structures needed have to be created by the programmer so if, for instance, the problem being solved involved text strings or floating point numbers then it is you, the programmer, who would have to decide how to represent those entities, and do the necessary programming.

High-level languages, such as BASIC and Pascal, attempt to provide a vehicle for expressing algorithms which is more human orientated and powerful. A single statement in a high-level language might correspond to operations which, when expressed in a lower-level language, would need many hundreds of code instructions. At the end of the day however the high-level language interpreter or compiler must produce such a series of low-level machine instructions in order that the program can run.

In reality, this low-level/high-level two tier classification is rather an over-simplification. Nowadays there exists a wide spectrum of languages each possessing features from both groups. Almost all current assemblers for example allow macros, reusable groups of low-level operations, to be built up and the creation of these types of units allow the programmer to tackle low-level code writing at a significantly higher level than was possible with early assemblers. Having said that, high-level languages clearly have a number of important benefits:

The key advantage offered by high-level languages is that they provide a means of expressing the steps of an algorithm at a more problem/solution orientated level. If, for example, you wish to open a file, read some data, and then close a file it might be possible to use program statements which represent these file opening, data reading, and file closing operations directly. Three statements which relate closely to the things which need to be done, as opposed to hundreds of assembler instructions which, taken in isolation, will give few obvious clues as to the work being carried out.

As the level of abstraction increases, the programmer becomes less concerned with the hardware on which the program runs and is able to work more and more at a problem-orientated level. Symbolic names take the place of memory addresses, support for different data types means that the language (as opposed to the programmer) can be left to figure out the details about the sizes of objects being used and how/where they should be stored. Similar generalised control abstraction facilities allow loops and decision tests to be used as building blocks, which again makes it easier for the programmer to tackle problems in a solution orientated, rather than a hardware orientated, way.

Now if these high-level language characteristics are so good why on earth are people still using assembly language at all? To be honest people have been predicting the demise of the assembly language programmer for years but it simply hasn’t happened - in fact interest in assembly language programming actually seems to be on the increase and it turns out that there is far more to the high-lcvel/low-level debate than first meets the eye.

It was once thought that there were only three reasons for using assembly type languages: speed, compactness and the ability to achieve the ultimate control over the system. The benefits are rather more subtle than this because there’s no doubt that an understanding of an assembly language gives the programmer an in-depth appreciation of what high-level languages must do to achieve their abstraction magic, it’s a similar situation to driving a car. If you don’t know roughly how the gears work then you might wonder why you can’t pull away in fourth gear without stalling the engine. Plenty of driving will convince you that this is indeed the case, but no matter how much you drive you’ll never actually find out why this is so. Learn a bit about the internal mechanics however and it will become obvious within a very short space of time!

Since the Amiga is a 68000 based machine it’s not hard to figure out that all Amiga languages must end up generating 68000 code - they have to because otherwise the final programs simply wouldn’t be able to run on the Amiga’s microprocessor. What then is it that actually makes code written by assembler programmers run faster than the equivalent 68000 code generated by programmers working with high-level languages? The answer is simply that the assembler programmer can make sure that their final code is super-efficient. Here’s a typical example.

As you may know, the Amiga has a vast number of pre-written routines available which are organised as a collection of units known as run-time libraries. The routines present in these libraries are accessed by a table stored in memory immediately below the base (main reference) address of the library. By using a negative offset, called a LVO (Library Vector Offset), the programmer can specify which routine is to be called. These routines are used by placing the library’s base address in one of the 68000 registers (actually register a6), using the LVO as a displacement value, and performing something called an indirect subroutine call. These terms may not mean much at the moment but the important point to grasp is that the necessary data needs to be held in the microprocessor’s internal registers before the subroutine call is made.

Now let’s consider what happens with a conventional C compiler when a high-level function call is used to execute the same library routine. The compiler starts by pushing function call parameters onto the stack, an area in memory which the microprocessor uses to store items on a last-in-first-out basis. Now, when you are calling an Amiga library function, it turns out that this is a total waste of effort because, at the end of the day and as indicated above, the Amiga run-time libraries expect the parameters to be present in the 68000 processor registers and not on the microprocessor stack. The bottom line is that before the real library function call can occur, the parameters, so carefully placed on the stack by the compiler generated code, have to be immediately copied back into suitable processor registers.

The code stubs which do this are part of the amiga.lib library and this, plus the fact that the LVO values are also needed, is the reason why C programmers usually link their code with the amiga.lib linker library in the first place. The resultant C code therefore ends up doing a lot of unnecessary work and this of course slows the program down. By placing library call parameters directly into the appropriate 68000 registers the assembly language programmer can eliminate such inefficiencies very easily indeed.

Now to be completely fair, at least as far as the above example goes, I ought to point out that some compilers (eg Lattice/SAS C) do now support register based parameter passing and can therefore also now eliminate these amiga.lib subroutine time penalties. Being equally fair as far as the assembler programmer is concerned I should mention that while register based parameter passing in C is a recently added facility such advantages have always been available to the 68000 assembler programmer!

The underlying general point I’m trying to make is this: all high-level languages have to make compromises with the code they generate and because of this there will always be many occasions where the assembly language programmer can cut corners and eliminate inefficiencies. This is the reason why the assembly language programmer will almost always be able to produce program code that runs faster than code generated by a compiler.

Assembly language then has a lot going for it. High-level language topics that programmers often find difficult to understand, such as bit-manipulation operations and the use of indirection and pointers, have natural and easy to recognise counterparts in assembly language. The overall result, believe it or not, is that knowing something about your machine at this low level of programming will not only help you get a gut feeling for what computing is all about but it can even help you to write more effective high-level code. For more information see the Appendix Mastering Amiga Guides.

The first step in writing an assembly language program is to use an editor program to prepare a source code file. This file will simply be an ASCII text file which contains the program instructions that you’ve written and you will of course be able to list and print the contents of such a file just as you would a letter or any other piece of stored text. Most commercial assemblers come with their own editor programs but, if you prefer, it is also possible to use an alternative editor or wordprocessor program. The only proviso with the latter option is that it must be possible to stop the wordprocessor from inserting additional control characters because these characters would, as likely as not, cause the assembler program to come to a grinding halt as it tries unsuccessfully to interpret them.

Once a source file is available, the next step is to get the assembler program to convert it to the appropriate 68000 instructions. On the Amiga the assembler will in many cases first have to be used to create a standardised intermediate form known as an object code file. This is not a runable program as such and there are three possible reasons for this. Firstly, although the object file will include the translated 68000 instruction-related material, the code will not itself be in the right format to be loaded by AmigaDOS. Secondly, the program will not contain an all-important piece of Amiga specific front-end code known as the startup code which is needed if the program is to run from the Workbench. Thirdly, the file may still contain references to unresolved (unknown) items, such as linker library routines or variables that have been specified as being present in other object code modules.

A third stage, known as linking, attempts to fill in the gaps created by these unresolved references. The Amiga linker, called Blink, is able to combine the startup code and the code you have written (plus any other specified object code modules or library code), to produce a program file that may then be loaded and run under the Amiga’s operating system. Having said all that I’m afraid that I must now point out that nowadays many assemblers can produce a variety of different output file formats. HiSoft’s Devpac assembler for instance, providing it is presented with a suitable source code file, can generate directly executable code without an explicit linking stage!

Libraries on the Amiga cause a few headaches for the beginner primarily because the term is used in a number of different ways. During the example of high-level language inefficiencies I spoke of the Amiga’s run-time libraries which are collections of shared routines that, by virtue of the Amiga’s operating system, can be made available to all programs which need them during the times that they are actually running.

The libraries I am talking about in the context of the above linker discussion are rather different. Linker libraries are sets of prewritten system or utility routines which will be tagged onto the code you write during the linking stage. If you use a linker library function within your program the linker, providing you correctly specify the name of the library which holds the routine, will automatically find and include the right piece of code in the finished program. I’ll be saying much more about the various Amiga library schemes later in the book.

On occasion things may not go well and you may find that as the assembler attempts to translate your source file it reports any number of errors. Whatever the cause (syntax errors, illegal instructions etc) these faults will have to be corrected and this may mean that in the early days you’ll frequently pass through the edit<→assemble cycle quite a few times before you succeed in creating a program that assembles successfully. Even having got through that stage of the proceedings you may then find that the linker reports additional errors. Mis-spelling library routine names or not specifying the correct location of library files are commonly seen linker errors. These errors must also be found and eliminated before a runable version of the program can be created.

As you doubtless already know there is no guarantee, even once a program is up and running, that it is free from errors. In fact assembly language programmers, unless they are very careful, are likely to spend far more time looking for bugs than their high-level language counterparts. Many assembly language programmers frequently use a piece of software called a debugger, which is a system tool that is able to execute a program on a step-by-step basis, in order to help them to trace program execution and identify faults. Whilst I certainly agree that debuggers can be useful on occasion I am not in favour of their use as a general fault-finding tool.

One thing you are going to need to get used to as you enter the world of assembly language is the use of additional numbering systems. Since this primarily involves binary and hexadecimal numbers some words on these two number schemes are in order.

In the decimal number system ten different symbols (the digits 0-9 inclusive) are used to represent numbers. Each digit in a number is ten times more significant than the digit to its right, and ten times less significant than the digit to its left. This ten times relationship that exists between the digits of all decimal numbers is obviously a fundamental part of the decimal numbering system. If, for example, we consider the number 375 and write a full description of what each digit means, we can see that it is just a convenient way of expressing this sum:

(3 x 100) + (7 x 10) + 5

Going one better than this and, bearing in mind that any number raised to the power zero is unity, you can express each effective digit term as a product of one digit and a power of 10 like this:

3 x 102 + 7 X 101 + 5 x 10°

For decimal numbers 10 is known as the radix, or base, of the numbering system but many other bases are possible. Computers use binary, ie base 2, numbers which consist of strings of Os and Is and again, if you think of a binary number in terms of its explicit radix = 2 representation, it’s easy to see the relationship between the binary and decimal number systems:

1011 binary = 1 x 23 + 0 x 22 + 1 x 21 + 1 x 2° 8 +0 +2 +1 =11 decimal

By writing out what the binary number means in full it becomes quite easy to see that 1011 binary is the decimal number eleven!

Computers use binary numbers internally because the two digits 0 and 1 relate directly to the possible states of bits within the memory hardware of most computer systems. Binary numbers are then intimately involved with a great many computing applications but, since they are not that easy for us humans to work with (because long strings of Os and Is are easily mis-interpreted) a related radix scheme called hexadecimal is often used as an alternative.

Hexadecimal numbers use a radix of 16 and the sixteen symbols used are the digits 0-9 plus the letters A-F. Each column in a base 16 number therefore represents some power of the base. For example the decimal number 16 itself is written as 10 hex, because:

10 hex = 1 x 161 + 0 x 16° 16 +0 =16 decimal

Similarly IF hex would be:

1F hex = 1 x 161 + 15 x 16° 16+15 = 31 decimal

The fact that the bases of the binary and hexadecimal numbering systems are power related (2 to the power of 4 equals 16) produces a special, and very useful, relationship between these two numbering systems - it allows one hexadecimal digit to represent four binary digits. Best of all the binary<→ hex conversion process is very easy to understand once you’ve learnt the table in Figure 1.1.

Binary Hex 0000 0 0001 1 0010 2 0011 3 0100 4 0101 5 0110 6 0111 7 1000 8 1001 9 1010 A 1011 B 1100 C 1101 D 1110 E mi F

Figure 1.1. Table for binary to hex conversion and vice versa.

To convert a hexadecimal number into binary form you just replace each hexadecimal digit with its group of four binary digits. To convert a binary number to its hex form you peel off (from right to left) groups of four bits and replace them with the corresponding hex digit!

So to convert CF hex to the binary equivalent you’d replace each of the two hexadecimal symbols with the binary equivalents like this:

CF hex = C F 1100 1111 = 11001111 binary

To go the other way you take groups of four bits from the binary number and replace then with the corresponding hex digits. The binary number 1 1 1 1000010101010, for example, could be translated to hexadecimal form as follows:

1111000010101010 = 1111 0000 1010 1010 F 0 A A F0AA hex

Using (and converting between) binary, hex and decimal number systems is not that difficult but it does take practice. Familiarity with hex and binary number forms is also essential for understanding how the bitwise logical operations, provided by both microprocessor instructions and high-level languages, work. Logical AND and OR instructions for instance, which I’ll assume you know about from languages such as BASIC, perform operations based on the two truth tables in Figure 1.2.

X Y X AND Y 0 0 0 1 0 0 Logical AND Operation 0 1 0 1 1 1 X Y X OR Y 0 0 0 1 0 1 Logical OR Operation 0 1 1 1 1 1

Figure 1.2. Logical AND Operation (top) and Logical OR Operation (bottom).

Being able to picture in your mind what these tables mean is a big advantage. If you AND two operands together then only the bit positions where both operands have a bit set to 1 will produce a 1 in the result. With the OR operation you’ll get a 1 in the result when either (or both) of the bits in that position in the corresponding operands are set to 1.

The bit pattern for FO hex for instance is 11110000 so ANDing any value with FO hex will force the lower four bits of the result to zero - the value FO hex is called a mask because it masks out certain bit positions. The OR operation is equally useful because it can force bit positions to take particular values.

===Last Words

The instruction sets of most processors, such as the 68000 used in the Amiga, are quite limited and there is nothing inherently complex about their operations. Each instruction carries out some elementary task, perhaps adding two values together or copying the contents of one memory location to another.

Despite this underlying simplicity there’s no doubt that tackling 68000 assembly language is not a task to be undertaken lightly. Problems will arise when you try to work out how to combine hundreds and thousands of assembly language instructions into a program which does a particular job. It is a task which is error prone and, by its very nature, time consuming. The benefits? Firstly you’ll be able to make your programs run at the ultimate speed. Secondly, you will develop a gut feeling for what computing is all about at the nuts and bolts level.

Assembly language programming on the Amiga adds another dimension - the complexity of the operating system itself. Before you can comfortably write assembler code to do a particular job it’s necessary to know enough about the operating system and its library code system call arrangements, to work out what your assembler code should be doing. Learning about these Amiga facilities alone is a massive challenge simply because there is so much to understand. There is no easy road! You’ve just got to sit down and work at it.

Don’t forget incidentally that it is often possible to combine both high-level and low-level approaches in the so called mixed code approach. Here the bulk of the code is written as normal using a high-level language, then any routines which are particularly critical are added as assembler patches. This gives the programmer the best of both worlds - essentially high-level development coupled with the absolute speed and control in the program sections where it counts. I’ll look, in some detail, at an example of this type of coding towards the end of the book.

The 68000’s internal registers are split into two basic groups, address registers and data registers, and registers of each group are numbered from 0 to 7. Data registers are therefore labelled as dO, dl, d2…​d7 (or Dl, D2…​ etc), with the corresponding address registers labelled as aO or AO and so forth. Address register a7 has a special purpose in that it serves as the microprocessor’s stack register and is set up to point to an area of memory that can be used to store information on a last-in-first-out basis (LIFO). Because of 68000 architecture restrictions the stack has to be located at an even-numbered memory address. There are in fact two different 68000 stack pointers and this stems from the fact that the processor can operate in two modes - user mode and supervisor mode. Since it is convenient for each mode to have its own stack the 68000 has been designed so that register a7 behaves like two separate registers and stores both a user mode stack pointer and a supervisor mode stack pointer. Mode related issues are transparent for the purposes of the programming which we shall be involved with in this book.

Each 68000 register can hold a four byte (32-bit) number and amongst its other facilities the processor is able to move such numbers between its internal registers, between a register and a memory location (and vice versa). The 68000 can also move external data held in memory from one location to another.

One of the most distinctive features of the 68000 is the flexibility of its registers. Although they can hold 32-bit (long word) values the processor can, for many operations, use the address registers to work with 16-bit values (words) and the data registers can in fact work with either 32-bit values, 16-bit or 8 bits. Similarly there are few restrictions on what you can, or cannot, use the contents of such registers for. If, for instance, you wish to copy the contents of a data register into an address register the 68000 lets you do it. Having said that, it is usually better to use address registers for storing and working with memory addresses and data registers for data orientated operations because each of the groups are better suited to their design-chosen purposes. When working with instructions that may involve byte, word or long word values it is often necessary for the assembly language programmer to identify the size that should be assigned to a given value. As you’ll see later the 68000 conventions are based on placing .b, .w or .1 after the instructions. The 68000, because of its internal architecture, does however have a limitation on the address values that it uses when accessing word or long word addresses because the address must be even (word aligned). Assemblers take care of much of the word-alignment problems automatically and if, for example, you set aside space for a long word variable, the assembler will usually ensure that it gets allocated an even address.

The 68000 also contains a 32-bit program counter which is a register used by the microprocessor to determine the address of the next instruction to be executed. Under normal conditions the program counter is automatically incremented as instructions are read and acted upon, hence instructions contained in memory are executed in sequence, ie one after another. An important part of microprocessor programming however revolves around a number of instructions which can alter the contents of the program counter and the result of doing this has far reaching implications. By changing the program counter address it is possible to cause the microprocessor to get its next instruction from anywhere in memory (as opposed to getting the instruction next in sequence in memory), the result of which is that the execution of the program can jump from one part of the program to another.

The fact that these jumps can be made conditional on the state of various processor flags means of course that the processor can make intelligent flow control decisions based on the data with which it is working. A program might for instance compare two numbers and, on the basis of the result, execute (or perhaps not execute) a particular set of instructions.

Another important 68000 register is the status register which is actually divided into two eight bit registers known as the system byte and the user byte. The system byte is only accessible in supervisor mode and contains a number of system related bitfields, such as interrupt masks, which we will not be concerned with.

The user byte on the other hand is vitally important because it contains flag bits whose values are set and cleared according to the results of particular instructions. Five flags are available and these provide single bit true/false type detection of the processor conditions known as carry ©, overflow (V), zero (Z), negative (N), and extend (X). The carry bit holds the carry from the most significant bit produced by bit shifting or arithmetic operations. Like many processors the 68000 inverts the carry bit after subtraction and so with subtraction the carry flag actually behaves as a borrow flag. The zero flag is set high (ie set to 1) when an operation produces a zero result. If, for example, the result of adding two numbers together produced a zero then the 68000’s zero flag would be set to 1. The negative bit, sometimes called the sign bit, always takes the value of the most significant bit of the result. It can be used to good effect when working with operands that are in a form known as signed two’s complement but is also frequently used just as a most significant bit indicator. The 68000’s overflow and extend flags are also primarily used for arithmetic applications. Not all instructions, incidentally, affect all flags as you’ll see when we start looking at typical instructions.

One of the most powerful features of the 68000 instruction set is the rich variety of addressing modes that are available. Most processor instructions work on a piece of data (called the operand) and this data has to be stored somewhere. In short, many instructions will use some real or implied source address, do something, and then transfer the result to its destination address. The processor’s addressing modes enable these source and destination addresses to be specified. With the 68000 there are eleven basic addressing schemes and, for completeness, here are the names:

Figure 2.1. Schematic model of the Motorola 68000 microprocessor.

Inherent addressing means that the instruction itself implies the location of the operand. Register addressing implies that the operand resides in one of the 68000’s internal registers. Absolute addressing means that the address of the operand is located just after the instruction in memory whereas immediate addressing implies that the operand itself is located just after the instruction in memory.

Indirect addressing is a very powerful concept and on the 68000 a variant called register indirect addressing is used. In short an address register is used to specify the address of the operand. In addition to these straightforward addressing modes it is possible to specify displacements, to auto-increment or auto-decrement an address by 1, 2, or 4 bytes (handy for stepping through lists of 1, 2 and 4 byte data items) and to write program counter relative code, which is necessary when writing truly relocatable code. It’s not advisable to explain all of these addressing modes at the present time and such descriptions are left to later chapters where various addressing schemes can be explained within the context of some real programs.

The 68000 instruction set is large and almost all sensible addressing modes can be used with any instruction. As was the case with the 68000’s addressing modes it is not a useful exercise, either now or later, to list and discuss each instruction. Such discussions, if made, would in fact fill a complete book by themselves. It is obviously necessary however to have some understanding of the general types of things the 68000 can do before we start looking at actual programs so here is a very brief overview of the type of operations supported.

This section discusses the functions performed by assemblers, starting with features that are common to all assemblers and then considering some of the capabilities of more sophisticated packages.

An assembly language program consists of a number of statements. Some statements will correspond directly to 68000 instructions, others will be assembler-orientated directives known as pseudooperations or pseudo-ops. Program lines may contain as many as four fields - a label, a mnemonic (which represents an instruction op-code), an operand or address field (which, if present, will be the data that the instruction acts on), and a comment. Here are some typical assembly code lines to illustrate the format. Don’t worry about what the instructions are doing, it’s the general layout of the program lines that is important, not the details:

* ; an example assembly language code fragment * OpenLib move.l move.l rts A A library_name,a1 IntuitionBase, dO A A get library name get library base value A Labels Mnemonics Operands Comments field

These are the pseudo-ops mentioned earlier and are used to define symbols, designate areas of memory for data storage, place fixed values in memory and so on. Directives also exist for more mundane operations such as controlling the listing and error reporting facilities of the assembler. Once again, conventions are going to vary from assembler to assembler but the detailed specifics will of course be fully documented in your assembler manuals.

Having said that, a few pseudo-ops do need to be dealt with because they will be used extensively within the book.

Most assemblers provide directives which allow specified parts of a program to be assembled, or not assembled, depending on specified conditions. For instance the single standard start-up code source file provided by Commodore includes changeable constant declarations which allow the automatic generation of a number of different start-up module versions. Programmers often include debugging code in their programs but conditionally remove the relevant sections of code in the released versions of their programs.

Assembler programs, as we’ve already seen, are not used in isolation. An editor is needed to create the program, and a linker plus any number of other program support tools will also be needed. On the Amiga it’s also necessary to have the system header files available. So, whilst all assembler packages will have some common ground, there are likely to be significant differences in terms of the overall environment offered to the programmer. This applies both in terms of the conventions used and in the overall environment integration (which affects the ease of use). To illustrate the features that a modern Amiga assembler environment will offer I’ve chosen to look at what I consider to be the best assembly language programming environment available on the Amiga at the current time, HiSoft’s Devpac 3.

HiSoft’s 68000 Devpac Amiga assembler package has been around for quite a few years and during that time a large user-base has formed. Most Devpac users will tell you that the package is popular for two main reasons. Firstly, it is a robust program which does the job that it is supposed to do. Secondly, it has proved to be a stable, well supported, product. If you are a serious user, and most Amiga assembly language programmers are, then those qualities are obviously important.

The latest version of Devpac, called Devpac 3, has a number of advantages over earlier versions. The editor has been greatly enhanced and it now offers multiple file editing with full mouse-controlled cut & paste facilities, enhanced menu selection and a new Workbench 2 style look, even when running under Workbench 1.3. Especially useful editor features include the ability to open individually scrollable multiple windows on the same file, bookmark set and locate facilities, a macro recording facility for memorising complex keypress sequences, and powerful assembler/debugger integration options.

The assembler supports the 68000-68040, 68332, 68881/2 and the 68851 memory management unit (MMU) chips. It can produce S-records (an output form used by EPROM programmers), can generate and process pre-assembled include files and can create more source-code tracking debugging info. The Devpac debugger has a flexible, user-configurable, multi-window arrangement and can handle multiple files.

Since the Devpac environment has proven to be so popular (there are around ten thousand Devpac users) I will try and explain the purpose, and the benefits, of some of the Devpac facilities. The main HiSoft tools are the editor, assembler, and the debugger.

This book is in no way restricted to Devpac users but it must be said that if you have yet to get an assembler package Devpac 3 is worthy of serious consideration. It provides some superb facilities and newcomers will get an assembler environment which will help make learning about, and using, assembly language just about as easy as it ever could be!

In the last two chapters I’ve covered some general concepts, introduced the 68000 to you and looked at issues related to the writing of assembly language programs. Now it’s time to put some of these pieces together and start looking at the writing of some simple, but nevertheless, real assembly language programs.

Data movement on the 68000 can be achieved with move instructions. A number of variants exist but the basic format is:

move.<size> source, destination

If the object size is not specified then a word size (16 bit) is assumed. To move the contents of a location which has been given the symbolic name X to the lowest 8 bits of register dO we would write:

move.b X, dO copy byte X to lowest 8 bits of do

Similarly, to move the lowest 8 bits of register dO to a location which has been labelled Y we could write:

move.b dO, Y copy lowest 8 bits of dO to Y

One way of initialising the above X and Y variables would be to use the byte form of the define constant and define storage pseudo-ops (dc.b and ds.b), like this:

X dc.b 10 allocate one byte and initialise it to 10

Y ds.b 1 allocate one byte but do NOT initialise it

If we put these fragments together we can build a program which will copy the pre-initialised 1 byte value held in location X to location Y:

The program starts with X holding the value 10 and Y being undefined. After it has been run, byte X will still contain the value 10 but byte Y will also contain 10.

Any of the data registers d0-d7 could have been used for this program and dO was an arbitrary choice.

Nowadays most assemblers initialise ds.x statements to zeros but from the point of view of consistent documentation it is best to assume that such initialisation is not done. If you really want to initialise byte Y to zero, choose the dc.b 0 pseudo-op.

The rts (return from subroutine) instruction at the end of the code is used to return control back to the Amiga’s operating system. Don’t worry about understanding what it does - such issues will be discussed in detail in the next chapter. Strictly speaking even these simple programs should terminate with register dO set to zero, achieved by using a moved #0, dO (or a clr.l 0,d0) instruction just before the rts, but for simplicity this Amiga-orientated operation has not been included in these, otherwise general, discussions.There is in fact a much easier way to achieve the above copy operation because the 68000 allows you to transfer data directly from one memory location to another, like this:

move.b X, Y copy byte X to byte Y

This means that it’s possible to eliminate the use of dO as a temporary storage register in the above program and write this simpler version:

When move is used to copy a piece of data the instruction, providing the destination is not an address register, generally affects the flags in the user-byte 68000 status register. These flags are variously called the user-byte flags, condition codes, or just the status byte flags (this book will use the latter term). With move instructions the Zero (Z) and Negative (N) flags will be set to an appropriate state whilst the Overflow (V) and Carry © flags will be cleared.

Now that you’ve seen how to move 8 bit values you’ll be pleased to know that you can move word (16 bit) and long word (32 bit) values just as easily. The following version performs a word (two byte) copy:

Since instructions assume a word size by default it is not necessary to include the .w size indicator on the move instruction. Example CH3-3.S could therefore just as easily have been written as follows:

Since two bytes are needed to store a word value, and since each byte has an individual address, you might be wondering what address the assembler assigns to the word variables. On the 68000 Amiga system words are stored in memory as shown in Figure 3.1.

Figure 3.1. 68000 storage of words in memory.

Without looking at the following solution, try to change program Example CH3-4.S to produce a long word version. Here’s the result you should have obtained:

Four bytes are needed to store a long word value and on the 68000 these items are again stored in a particular order. Just as a word can be expressed in terms of an upper and lower byte so we can consider a long word as containing an upper and lower word like this:

32 bits 16 bits 16 bits <long word value> = <upper word> <lower word>

The 68000 stores the word components of long words in the same way as it stores the byte components of ordinary (16 bit) words, ie it stores the bytes of the most significant word first, so the net result is that long words are stored in memory (Figure 3.2).

Figure 3.2. 68000 storage of long words in memory.

In transferring data from one set of locations to another, Example CH3-5.S was using absolute addressing. Remember that the X and Y labels used in the moved X, Y instruction represent numerical addresses.

Another way of writing the programs that we’ve just been looking at would be to reserve uninitialised memory space for both the X and Y variables and then explicitly initialise the X variable when the program is run. The following example uses an additional immediate addressing move instruction to load variable X with the value decimal 10. By convention immediate addressing on the 68000 is signified by placing a hash (#) sign in front of the operand:

You will see from the instruction code summaries provided in Chapter 17 that the move instruction is unable to transfer data to an address register. In actual fact a specialised form of the move instruction, called movea (move address) is available for this purpose and a number of differences which exist between move and movea need to be discussed.

Firstly, like most direct address register instructions, movea can only operate on word or long word values. Secondly, movea does not affect any of the processor’s flags. This, for address-orientated operations is actually a convenience not a limitation. Lastly, movea sign-extends any word values it is working with. This means that the uppermost bit (bit 15 of the word) will be propagated throughout the upper 16 bits of the address register. Sign extension was introduced on the 680x0 series to allow a form of absolute addressing based on word addressing to be used (as opposed to a full long word address) and you can find additional details in Chapter 17.

Although it is not a good idea to use address registers for such purposes we could write a word (16 bit) version of our original Example CH3-1.S data copying program like this:

As it happens most 68000 assemblers do allow you to use the move mnemonic when specifying an address register so program Example CH3-7.S actually could have been written as:

The difference however is that in the case of this last example the assembler will automatically insert a movea instruction for loading register aO and this means that unlike data register loading operations the address register loading operation will not affect the processor’s status flags. More subtle differences can also occur as this example clearly shows:

Here we are using a word data value which includes a 1 in the uppermost position (FFFF hex =1111 1111 1111 1111). Because the first instruction is really a movea, and because the sign bit (bit 15) of the word $FFFF is set high then the value that movea transfers to register aO is FFFFFFFF hex, and not FFFF hex. Since the program only copies the lower 16 bits of the register back to location Y this doesn’t affect the result in this case but the instruction has of course affected the upper 16 bits of the aO register in a way that the related data register version of the program would not do. Most 68000 coders soon get used to the flag and sign extension implications of address register usage, use the move mnemonic for both data and address orientated instructions, and let their assemblers decide on the correct object code instruction.

Complementing a number means turning all the Is present in the number to 0 and turning all the Os present to 1. If, for example, register dO contained the value:

do = 0000 0000 0000 0000 0000 0000 0000 0000 binary ie 0 0 0 0 0 0 0 0 hex

then the complemented value would be:

dO = 1111 1111 1111 1111 1111 1111 1111 1111 binary ie F F F F F F F F hex

You should work out for yourself that if dO = 1F01 hex then after a long word (32 bit) complement operation dO will contain EOFE hex (write out each hex digit in the binary form as above, invert all the bits, and then translate the answer back to hexadecimal form).

The 68000 instruction which performs this operation is called NOT and like many other instructions it exists in byte, word and long word forms. Here’s a short program which uses immediate addressing to load dO with the byte value OF hex, inverts it, and then stores the result in a location whose symbolic name (ie its label) is RESULT:

The 68000’s basic addition instruction uses this syntax:

add<.size> source, destination

where the result of the source + destination addition gets placed in the destination register (in common with a great many 68000 instructions that work with two operands).

So far the instructions we have looked at have allowed source and destination operands to be either in registers or memory. Not all 68000 instructions are that flexible and in fact the add instruction only allows one of its operands to be in memory. You may add the contents of a register to a memory location, or do the reverse (add the contents of a memory location to a register). What you cannot do however is add the contents of one memory location directly to the contents of another.

The limitation means that for this instruction we need to use a temporary register much as we did with our early data copying examples. Here is an example which loads register dO with a number contained in NUMBER1 and then adds that number to the contents of the memory locations represented by the label NUMBER2:

After program Example CH3-12.S has been run, the variable NUMBER2 contains the value 7.

Up until now I’ve mentioned byte, word and long word forms of variables but have not said anything about when the various forms should be used. As far as data items are concerned the unwritten rule for the assembler programmer is the same as for the programmer working in any other language, namely conserve as much memory as possible, ie don’t waste it by allocating unnecessary space. Have a look at the internal contents of the two four byte numbers used in the previous example:

byte 3 byte 2 byte 1 byte 0 NUMBER1 00000000 00000000 00000000 NUMBER2 before 00000000 00000000 00000000 NUMBER2 after 00000000 00000000 00000000 00000011 decimal 3 00000100 decimal 4 00000111 decimal 7

Both numbers and the final result fit comfortably into an eight bit byte so in all honesty we did not need to use long word size variables, bytes would have done. Here then is an improved version:

Only two bytes of variable storage space are needed instead of eight in the previous example, and the byte-orientated forms of the instructions execute more quickly as well. Programmers would therefore say that this new version of the program was more memory efficient, or just more efficient than the previous one.

Now let’s try something a little more complicated. We’ll set up some space for a long word variable called NUMBER1, initialise it using immediate addressing to some arbitrary value (I’ve used 1FFFFF hex), increment it by 1, complement the result, and then store it in a variable called RESULT. Here’s one program that does the job:

Depending on what was actually required there are many ways that a program similar to the above could have been written. It might, for instance, have been appropriate to place the original value directly in the locations assigned for the result, and do the addition and complement operations on the result locations like this:

In the above example a special form of the add instruction, addi, is being used. This allows an immediately addressed source operand (in this case 1) to be added directly to the destination operand. If you take a sneak preview of the add addressing mode details in Chapter 17 you’ll find that the normal add instruction couldn’t have been used in Example CH3-15.S anyway because to use immediate addressing the destination would need to be a data register. However, as is the case with a number of instructions, most 68000 assemblers do let you write statements such as:

add.l #1, RESULT increment value

and then automatically translate the instruction to:

addi.l #1, RESULT increment value

so program Example CH3-15.S could, after all, be written as follows:

For immediate operands within limited ranges the 68000 offers a number of quick instructions. Instead of using real immediate addressing, where the operand is placed immediately after the opcode in memory, these instructions have a data value buried into the instruction op-code itself. The moveq instruction for instance

uses a data register as the destination and allows 16 bit operands to be specified (it does however sign extend the data to long word size). To load register d2 with the value 3 for instance we could write:

moveq #3, d2 load d2 with value 3

Add and subtract quick instructions also exist and these allow immediate data in the range 1-8 to be specified.

To increment by 4 the contents of a memory location whose address has the symbolic name RESULT we might, using absolute addressing, write:

addq #4, RESULT

If we choose to load the address of RESULT into register al we could instead use the 68000’s indirect addressing scheme to specify the destination address:

move.l #RESULT,a1 load a1 with address of RESULT addq #4,(a1) add 4 to the contents of the byte 'pointed to' by register a1

where the destination operand’s (An) notation is the 68000 assembly language form for specifying an indirect address.

Another method of loading register al with the address of the RESULT variable is to use the more specialised Load Effective Address, lea, instruction and if this is done with the above fragment the code ends up looking like this:

lea RESULT, a1 load a1 with address of RESULT addq #4, (a1) add 4 to the contents of the byte 'pointed to' by register a1

The earlier loading of the address of the RESULT operand into al using an immediate addressing move instruction served us well enough but in general the lea instruction is a far more flexible alternative. Much more use will be made of the lea instruction later in the book.

Program loops enable a programmer to create a repetitive subset of instructions, ie a set of instructions that can be repeated a specified number of times. Most loops have up to four identifiable sections:

There are in fact two types of repetitive loops in common use. With post-test repetition, the control test comes after the main body of the loop. With pre-test repetition the control test comes before the main processing section.

Figure 3.3. Flowcharts of pre test and post-test loop arrangements.

The difference between these two forms, namely the location of the control test, has an important practical implication. The main body of a post-test style loop will always be executed at least once but if the conditional test used with a pre-test loop is satisfied immediately then the body fragment will never be executed. By way of comparison, BASIC’s WHILE/WEND loops are pre-test forms, but BASIC’s DO/WEIILE loops are post-test. Despite the fact that many debates have occurred concerning the merits of the two schemes, in practice both have their uses.

Post-test repetition, as far as the assembly language programmer is concerned, does tend to produce shorter code. The following fragment uses register dO as a loop counter (initialised to 10). With each pass through the loop the value in dO is decreased by 1 and following this decrement operation the control portion of the loop uses a branch on not equal to zero, bne, instruction to either branch, or not branch to the specified location. This instruction is one of a number of flow control facilities provided by the 68000 and it looks to see if the processor’s zero flag has been set. If it has not, the specified branch is taken and the net result is that the loop code is executed until such time as dO becomes zero (ie the loop is executed ten times):

moveq #10, dO LOOP do something subq #1, dO bne LOOP initialise dO as a counter unwritten main body decrease counter repeat loop if count not zero

To write this loop in pre-test form requires that we both invert the sense of the exit condition test and add an extra instruction, an unconditional branch (bra) which always forces control back up to the top of the loop:

moveq #10, dO LOOP beq L00P_END do something subq #1, dO bra LOOP L00P_END subsequent code initialise dO as a counter unwritten main body decrease counter

The branch on some condition instructions, collectively written as bcc (where cc represents the testable condition) are an example oi relative addressing. The object code created for these instructions does not include an absolute address to branch to - instead a displacement from the current value of the program counter is provided. This is the computer world’s equivalent of someone knocking on your door and asking where one of your neighbours live. You, instead of saying “they live at number 66” (an absolute address), reply by pointing the caller in the right direction saying “they live six doors further down the road”. What you’ve done is give a displacement which could have been positive (eg six doors further up the street) or negative. Relative addressing therefore specifies an address by providing the difference between the current address held in the 68000’s program counter and the address you wish to reach. A great many testable conditions are available for conditional branch instructions. Most will be covered (in context) during the course of the book but Chapter 17 provides summaries of the allowable options, should you care to review them.

In this section I want to write a program a little more involved than previous examples have been. It concerns the translation of text strings from one form to another. One way to represent a text string in memory is to store a count of the number of characters followed by the characters themselves. In an assembly language program such static (permanent) strings can be set up using dc.b directives like this:

TEXT dc.b 5,"APPLE"

and in memory this would lead to the situation shown in Figure 3.4 below.

Figure 3.4. One way of representing a string in memory.

Another convention which is also in use, and equally popular, is to use a special symbol to mark the end of the string. The C language stores strings in this way and instead of a count being used, a NULL (zero) value is placed at the end of the string. The assembly language programmer can do a similar thing like this:

Figure 3.5. The C style way of representing a string in memory.

Now let us suppose that a string has been declared in a program using the former <countxcharacters> convention and that we want to write a routine which will convert that string to the alternative form whilst copying it to some alternative locations. By loading register aO with the address of the first byte of the original string the count can be loaded into register dO using the indirect addressing scheme mentioned earlier:

lea TEXT, aO put address of string in aO move.b (aO), dO copy count to register dO

At this point we know how many characters are in the string - it’s given by the value now in register dO.

In light of the fact that we are going to copy the string , and so will need to reserve some space to store it, let’s further assume then that another declaration has been made in our program:

COPY ds.b 6 reserved for copy of string

and that we shall load the address of this buffer area into register al using another lea instruction like this:

lea COPY, a1 address of copy buffer in a1

The position we’ve now reached in our preliminary planning is that we have aO pointing to the start of the source string (its count byte) and al pointing to the destination area and we have this much of the framework of a suitable program:

lea TEXT, aO put address of string in aO move.b (aO), dO copy count to register dO lea COPY, a1 address of copy buffer in a1 copy and convert the string rts TEXT dc.b 5,"APPLE" COPY ds.b 6

Bearing in mind that the first byte of the source string should not be copied, because it is not part of the text string itself, it’s not too hard to see that if we increment the address in aO by 1 then that register will then be pointing to (ie contain the address of) the first real character of the source string. By using an addq.l instruction to increment the source pointer and by including a few appropriate notes about what we are trying to do our program framework grows into this form:

lea TEXT, aO move.b (aO), dO addq.l #1, aO lea COPY, a1 copy dO characters of the text string from source to destination put address of string in aO copy count to register dO skip to first real character address of copy buffer in a1 insert a terminal NULL character at end of string rts TEXT dc.b 5,"APPLE" COPY ds.b 6

The loop itself is surprisingly easy to code. Firstly, we use indirect addressing to copy the character. Remember the first line of the following fragment is saying copy the contents of the byte WHOSE ADDRESS IS IN REGISTER AO TO THE LOCATION WHOSE ADDRESS IS IN REGISTER Al. Secondly, we increment both the source and the destination pointers (ie registers aO and al) by 1. Thirdly, we subtract 1 from the count value held in dO.

When the value in dO reaches zero we’ll have copied all of the characters in the string and this means that we create our loop using the branch on not zero type conditional branch instruction mentioned earlier:

LOOP move.b (aO), (a1) copy character addq.1 #1, aO move to next source character addq.l #1, a1 move to next destination byte subq.b dO decrease character counter bne LOOP loop until dO is zero

Now when we add these instructions into our existing framework things start to look up:

lea TEXT, aO put address of string in aO move.b (aO), dO copy count to register dO addq.l #1, aO skip to first real character lea COPY, a1 address of copy buffer in a1 LOOP move.b (aO), (a1) copy character addq.1 #1, aO move to next source character addq.l #1, a1 move to next destination byte subq.b #1, dO decrease character counter bne LOOP loop until dO is zero insert a terminal NULL character at end of string rts TEXT dc. b 5,"APPLE" COPY ds. b 6

All that remains is for us to store a terminal NULL (zero) value at the end of the destination string, which corresponds to the terminal processing section of the control loop mentioned in the general loop discussions. Since the loop will have already incremented the al pointer this is easily done with:

move.b #0, (a1) add terminal NULL

and by adding this instruction we get a complete program:

These types of loop-orientated conversion and copying operations are used in all manner of applications and so it’s not surprising that the 68000 offers some special facilities for writing such loops efficiently.

To start with, the processor includes special indirect addressing modes which allow the pointer increment operations to be done automatically. They are called address register indirect with postincrement, and address register indirect with pre-decrement. In the first case the increment operation is done after the address is used and in the second case the decrement occurs before the address is used. The reason why this arrangement was chosen will become obvious after the next chapter but for now accept it as 68000 magic.

Both autoincrement and autodecrement modes can adjust an address by 1, 2, or 4 depending on whether bytes, words, or long words are being handled. In the case of the example I’ve been developing bytes are being transferred and the increment needed is of course 1.

The 68000 programmer specifies the indirect autoincrement mode by placing a plus sign after the usual indirect reference, for example:

move.b (a0)+, dO copy count and increment pointer

If, incidentally, we were interested in using the auto predecrement mode we’d use this type of syntax:

move.b -(aO), dO decrement pointer and copy count

In the main body of the loop outlined in Example CH3-17.S both source and destination pointers (registers aO and al) need to be incremented and with our newly discovered addressing mode this becomes simplicity itself:

LOOP move.b (a0), (a1) copy character and increment pointers

If we put these instructions in place the result is as follows:

Not only is the program shorter but the execution time will have been reduced because the autoincrement instructions run faster than the corresponding groups of move and addq instructions.

There is however another refinement that can be made because the 68000 has more special instructions which allow the control part of such loops to be written more efficiently. It is called, in its various forms, a Test Condition - Decrement and Branch instruction and is given the general mnemonic dbcc, where cc represents a particular testable condition.

The instruction itself expects a data register to be used as a loop counter together with a conditional branch type label, which internally is stored as a relative address. For example:

dbcc dO, LOOP (cc is a testable condition eg dbeq, dbne etc)

The dbcc instruction tests both the status flags and a data register but there are differences between loops written using dbcc and those written with conventional conditional branching which stem from the way that dbcc works. If the condition being tested is satisfied then control passes to the instruction which follows the dbcc. If the condition is not satisfied then the low word (the lower 16 bits) of the data register is decreased by 1 and only if the result does not equal -1 is the specified branch taken. In other cases the instruction after the dbcc instruction will be executed.

From the above description you’ll see that this instruction has two ways of exiting. Firstly, there can be the normal loop counter based exit. Secondly, there can be a premature exit caused by the specified condition becoming true. The other point that is important to understand is that the conditional part of the test actually works in the completely opposite way to the bcc type conditional branch instructions, because the branch is not taken if the condition is satisfied.

For the current example we are only interested in the loop counter part of the instruction so a dbra (which represents branch always) instruction will be used like this:

LOOP move.b (a0), (a1) copy character and increment pointers dbra dO, LOOP decrease and branch on zero

Because the loop exits when dO equals -1 we need to subtract 1 from the character count originally loaded into dO. If these changes are made we end up with this final version of a program which does the string conversion:

The net result of running program Example CH3-19.S is that, by the time the program finishes, the COPY buffer will hold a copy of the original ''APPLE" string in null terminated form.

This latest use of indirect addressing with automated increment coupled with the powerful dbra loop control instruction should begin to show something of the 68000’s power, especially as far as the various addressing schemes go. Example CH3-19.S, for simplicity, has used a static string definition but it’s not too hard to imagine writing a routine that would be able to take any string in <countxcharacters> form and convert it to <characters><NULL> form. All that needs to be done is to find some way of writing the routine in a generally useful way and working out how the source and destination string addresses can be passed to the routine.

One solution would be to simply specify that before the routine is used the source and destination addresses should be in aO and al respectively, perhaps adding a note to this effect at the start of the routine:

This piece of code could be used whenever a string had to be converted and the 68000, like most processors, provides a mechanism for allowing the re-use of code in this fashion. The code fragments themselves are even given a special name - subroutines -and, because they are so important, they get a chapter all to themselves.

The most common way of providing such a facility is to use a data structure known as a stack which allows items to be stored on a Last-In-First-Out basis. Some microprocessors have hardware-defined fixed stack areas but on the 68000 processor stacks may be implemented anywhere in memory and all that is needed is a contiguous block, ie a block of unbroken, adjacent, memory locations. Register a7 is used to hold the address of the top of the stack, and we usually talk of register a7 as pointing to the top of the stack. Prior to a new subroutine call, the stack will look like Figure 4.2.

Figure 4.2. Stack condition prior to a new subroutine call.

Before control is passed to a subroutine the processor calculates the address of the next instruction (ie the one which would have been executed if the subroutine call jump was not going to be made). As mentioned above, this address is placed on the 68000’s stack so that as the jsr instruction passes control to the subroutine this is the state of the stack (Figure 4.3) overleaf.

Figure 4.3. Stack after a new subroutine call.

68000 stacks then grow downwards in memory and since the stack pointer always points to the last data item added to the stack this means that before adding new items you must first decrease the stack pointer by a number equivalent to the byte-size of the object being stored - that way it properly points to the locations to be used next. The jsr instruction therefore decreases the stack pointer by four, stores the return address, and then places the specified jump location into the processor’s program counter. Note that it is common, when placing data items onto the stack, to talk of pushing data onto the stack.

The main body of the subroutine will execute just like any other piece of code but the last instruction of the subroutine will be a rts, return-from-subroutine, instruction. This causes the address at the top of the stack to be retrieved (popped or pulled are commonly used terms for this operation) and placed in the 68000’s program counter. The result is simple. The processor jumps to the newly specified address and this of course is the return address specified during the original subroutine call.

A further instruction, called branch-to-subroutine (mnemonic bsr), provides a relative addressing form of the subroutine call mechanism. In this case either an 8 or 16 bit displacement can be provided.

We briefly mentioned in Chapter Two that the 68000 supports the use of separate supervisor and user stacks, which allows system software running in supervisor mode to maintain its own stack area. For the programs discussed in this book, whenever we talk about the 68000 stack we are referring to the user-mode stack!

There’s a point concerning the pushing and pulling of data from the stack that is worth clarifying. When data is placed on the stack it is, like all other 68000 data movement operations, a copy of the data that is written into the stack area. Similarly when data is pulled from the stack it is a copy of the stack data that is retrieved. If, by way of example, we could see the state of the stack just after the subroutine being discussed earlier executed its rts instruction, Figure 4.4 illustrates what we would find.

Figure 4.4. Stack after the subroutine has executed a rts instruction.

Although a copy of the return address has been placed in the program counter and the stack pointer adjusted, the return address originally placed on the stack is still there. What of course happens is that the next time a subroutine call is made those locations get over-written with the new address!

The programs and code fragments that we’ve been looking at in the previous chapter are simple examples and not exactly typical of the code you’ll find in real programs. Most proper programs will need to perform a variety of tasks and many of these, because they either need to be done many times or because they concern jobs which are common to numerous programs, will be written as subroutines.

Apart from the fact that subroutines can save memory space there are other benefits. A subroutine that has been written to be generally useful will, after suitable preliminary testing, be able to be used by programmers secure in the knowledge that it is safe, ie the subroutine does what it is supposed to and is error free. In fact maximising the utility value of such routines is a good design objective because the more generally useful a piece of code is, the more the programmer will find uses for it. Similarly, maximising the use of either system supplied or self-written subroutines makes program development quicker and this re-use of tested code also reduces the chances of bugs. In fact you can almost guarantee that any bugs that do occur in your program will come from the code that you’ve written and not from the library subroutines being used.

Most of the subroutines that you’ll code in your own programs will use absolute or relative addressing simply because you will know the address of the routine at assembly time. You should be aware however that it is possible to devise extremely sophisticated subroutine access mechanisms using other 68000 addressing modes. I briefly mention the possibility of hash-access and table access calls in Chapter Five and the Amiga’s multitasking Exec Kernel uses a dynamic library system built around loadable libraries of subroutines that are accessed indirectly. The Exec library system is in fact so important that I’ve devoted a whole chapter to it (see Chapter 10)!

You will incidentally see both the terms function and subroutine in much Amiga literature. In fact all of the library subroutines are called functions and this stems mainly from the fact that the C language (upon which the Amiga and its documentation is very dependent) calls all subroutine-like procedures, functions! In other non-C areas of computing one normally reserves the term function for a subroutine that acts on some data and returns a single result. A subroutine which takes the address of a text string and returns its length would be called a function, a subroutine which sorted a set of words into alphabetical order would not! Because you will find that almost all Amiga documentation will be using the term function you’ll find that, outside of this chapter, I will be doing the same when discussing Amiga system routines.

In order to be really useful, subroutines must be written so that they are general. There is, for instance, little point in writing a subroutine that prints the message Please enter a number*. It would however be quite useful to create a subroutine that could print any text message specified by the main program. This brings us to one of the most interesting areas of subroutine use. Namely, how such information can be provided to the subroutine and how any results might be passed back. Data items that are to be passed to a subroutine are called parameters and the act of arranging to transfer these parameters to the subroutine is called parameter passing. There are two basic ways in which data can be passed to a subroutine:

This first option is both simple and fast. Since pointers to larger objects, such as strings and other blocks of data, can be passed, ie the subroutine can be passed the address of the object rather than the object itself, there is little you cannot do. Similarly the subroutine may return any results, or a pointer to those results, directly in a register.

The advantage of this option, despite the fact that it is usually slower, is that it offers more flexibility. Parameters can, for example, if they are known at assembly time, be placed in memory immediately after the subroutine call. For example:

origrts jsr SomeRoutine dc.l #data_ iteml dc.l #data item2 dc.l #data_itemN needed_rts remaining instructions

In this case the return address placed on the stack by the processor would be wrong - the 68000 wouldn’t realise that the numbers immediately following the jsr call were data rather than a valid 68000 instruction. In short the return address would need to be altered by the subroutine itself, by adding to the return address an amount equal to the number of bytes of parameters. Other approaches include the passing of a pointer to a parameter block in a similar fashion. An often simpler method is to use global variables, defined and labelled locations that can be read from any routine anywhere in the program.

None of these solutions provide sufficient generality to have found widespread favour but the next, stack-orientated, approach I want to discuss has. Although the 68000 stack was introduced during the discussions of subroutines and return addresses it is now time to point out that the 68000’s stack can be used for the storage of other data, namely bytes, words and long words. As usual, word and long word, data must be word-aligned and the 68000 stack pointer register does in fact take a special precaution to ensure this word alignment - it word-aligns all data, even single byte values. When byte data is pushed onto the stack it is stored in the high-order byte of a 16 bit word.

Stack-based parameter passing can be done by several means. The 68000’s move instruction can, for example, be used in conjunction with indirect addressing with auto decrement to push a value onto the stack like this:

move.w tab_size,-(sp) jsr ExpandTab push tab size parameter expand to spaces end of program

What must be remembered of course is that, after you have pushed the parameter onto the stack, the jsr instruction will have subsequently pushed a return address so the stack will be looking something like Figure 4.5.

Figure 4.5. The pushed parameter after the subroutine call has been made.

This means that the subroutine needs to look not just at the top of the stack but actually into it in order to see the parameter. Since the return address is four bytes long we have to use a displacement of 4 as this example shows:

ExpandTab move.w 4(sp),d0 retrieve tab size in dO rest of code do something rts

The above fragment copies into dO the two bytes of data immediately above the return address. The situation once the subroutine has returned is that the stack, pointer will, at least in the case of the current example, be left pointing to the parameter that we placed on the stack. This cannot be left because it will destroy the integrity of the stack as far as any items which have been placed on the stack earlier are concerned. The parameter is not needed and so there is little point in executing a move (sp)+,dO type pull instruction. Instead the simplest idea is to numerically adjust the stack pointer so that the item is effectively ignored:

move .w jsr addq.l end of program

The Amiga’s amiga.lib linker library routines use this type of mechanism and I’ll be looking at some real Amiga examples of this technique in Chapter 12.

Other stack-orientated instructions are available, including a very useful one called push-effective-address, which can both calculate an address using any of the 68000’s addressing schemes and push it onto the stack for you. An example which shows the use of this instruction is given in Chapter 12.

Normally it is advisable to create subroutines which do not alter the contents of any temporary registers that they may use, ie those that will not be used to return a result. The best way to do this is to preserve those registers by pushing their contents onto the stack, restoring them just before the subroutine returns.

One way of doing this is to push/pull the contents of each register singly using instructions such as:

tab_size,-(sp) ExpandTab #2, sp push tab size parameter expand to spaces clean-up stack move.l a6, -(sp) move.l a5, -(sp) move.l a4, -(sp) do something preserve a6 on stack preserve a5 on stack preserve a4 on stack move.l (sp),a4 move.l (sp),a5 move.l (sp)+,a6 restore contents of a4 restore contents of a5 restore contents of a6

but in actual fact a special multiple move instruction exists, called movem, which allows this transfer to be done more efficiently when two or more registers are involved.

Movem actually exists in two forms. The instruction used when transferring registers to memory is called, not unsurprisingly, Move-Multiple-Registers-To-Memory (mnemonic movem). It can use all of the absolute and indirect addressing modes except the autoincrement mode. This is a deliberate restriction because it forces the programmer not to use to autoincrement when placing data on the stack (that approach would cause stacks to grow upwards in memory which would contradict the 68000 stack conventions).

Its useful to look at how this instruction is designed internally. The first word contains bit patterns which identify the instruction, the transfer size, and the effective destination specification. The second word is a 16-bit mask which has been assigned to represent registers either in this fashion:

a7 a6 a5 a4 a3 a2 a1 aO d7 d6 d5 d4 d3 d2d d1 dO

or, if the automatic predecrement addressing mode has been specified, like this:

dO d1 d2 d3 d4 d5 d6 d7 aO a1 a2 a3 a4 a5 a6 a7

Registers are moved in the order bit 0, bit 1, bit 2 etc, of the mask and so the order is dO, dl, d2 etc for the normal mask and a7, a6, a5 etc, for the reversed mask (assuming that is that the appropriate mask bits for those registers have been set to 1).

The equivalent Move-Multiple-Registers-From-Memory, movem, instruction does not use this mask reversal. In fact it always uses the bit mask arrangement described first, ie:

a7 a6 a5 a4 a3 a2 a1 aO d7 d6 d5 d4 d3 d2d d1 dO

and instead it allows the autoincrement addressing mode but does not allow the predecrement form.

When multiple data items are placed onto the stack the order in which they are removed is important. Because the stack works on a Last-In-First-Out arrangement items must be removed in the reverse order to that used to originally put them on the stack. If for instance you store registers dO, dl and al (in that order) then to reinstate the registers you must first pull al, then dl and finally dO. The effect of the mask reversal scheme when using the predecrement form of the movem instruction is that this ordering reversal occurs automatically and the program doesn’t have to explicitly worry about it (the assembler generates the appropriate mask).

The easiest way to describe the use of the instruction is to show you some examples. To save on the stack the full 32 bit contents of registers dO through d7 and aO through a3 for example we would write:

movem.1 d0-d7/a0-a3, -(sp)

To restore the registers (ie pull them back off the stack) we’d use: move.l (sp)+, d0-d7/a0-a3

Similarly to preserve register dO and registers a2-a5 we use this instruction:

move.l d0/a2-a5, -(sp)

and to restore the contents:

move.l (sp)+, d0/a2-a5

These instructions have a number of uses but as far as their use in subroutines is concerned you’ll mainly see them used on entry and just before exiting (ie just before the rts instruction) like this:

SomeSubroutine movem.1 d0-d4/a0-a3, -(sp) preserve registers

When registers are preserved like this, routines which are expecting parameters to be passed on the stack need to allow for the fact that more items have been pushed onto the stack after the return address. In the above example nine 32 bit registers are preserved (dO, dl, d2, d3, d4, aO,al, a2, and a3) so a further 36 bytes have been placed on the stack. If we go back to the stack-based ExpandTab parameter passing example mentioned earlier and add

<main body of subroutine code> move.l (sp) +, d0-d4/a0-a3 rts do something! restore registers return the above register preservation code, the offset now needed to access the tab size variable would be (9x4) + 4, ie 40, and the code would then be based on this type of framework:

ExpandTab movem.l d0-d4/a0-a3, -(sp) preserve registers move.w 40(sp),d0 retrieve tab size in dO rest of code do something move.l (sp)+, d0-d4/a0-a3 restore registers rts

More sophisticated subroutine arrangements are possible and one scheme used by many 68000 based high-level language compilers (including C) is not only able to eliminate the need for the altered displacements illustrated in the previous example but provides a number of other benefits.

The idea is that as soon as a subroutine is entered we immediately preserve the contents of an address register on the stack and then copy the stack pointer into it. This then establishes that register as a fixed frame pointer which can be used to access any parameters lying above the frame pointer and return address. Having done that, it is then possible to decrease the real stack pointer (ie register a7) by some chosen value such that this amount of space is then available as temporary workspace on the stack. After this has been done the subroutine can do all its usual register preservation operations and data subsequently placed on the stack will be stored after (ie below) the temporary hole that we’ve created in the stack. If, for example, a5 was being used as the frame pointer register we’d end up with the situation shown in Figure 4.6 overleaf.

Figure 4.6. A more sophisticated stack-usage scheme.

The situation in Figure 4.6 is then that after the frame pointer has been set up (a5) + 8, in other words the contents of register a5 plus an 8 byte displacement (remember that the return address and the frame pointer are both stored on the stack at this time), identifies the start of the parameters (if any) that are present on the stack. Another benefit of this arrangement is that by using negative displacements it becomes possible to access the temporary stack workspace, which was created when we made a hole in the stack by decreasing the stack pointer. In a high-level language it is just these kinds of negative displacements that are used to create local variables, which exist only during the execution lifetime of the routine in question.

Best of all though is the fact that the real stack pointer is set to the low end of our temporary workspace so, even when any number of new items are pushed onto the stack, the frame pointer remains valid.

Figure 4.7. Creating a safe hole for temporary variables.

At the end of the subroutine any additional items placed on the stack by the routine are removed and then the stack pointer is advanced past the work area, by loading it with the contents of the frame pointer. The original frame pointer register contents are then pulled off the stack and placed in the register used as a frame pointer, so re-instating it to its original value, and a normal subroutine rts is performed. This latter instruction, as usual, removes the return address placed on the stack by the jsr (or bsr) instruction.

OK, there are some difficult things to grasp with this approach but the general outline and power of the technique should be apparent. What you might like to know however is that the 68000 provides two instructions which allow this complex set of operations to be done automatically. The instructions are called link and unlink (mnemonic is unlk) and they are used like this:

MySub link a5, -32 movem.l d0-d7/a0-a2, main body of the subroutine will use (a5) displacements to access parameters and local workspace create 32 byte work area -(sp) preserve some registers providing it is not destroyed by the sub routine itself a5 remains valid no matter what happens to the stack pointer movem.l (sp)+, d0-d7/a0-a2 restore registers unlk a5 rts

The link/unlk instructions can dynamically allocate up to 32768 bytes of stack workspace, and as you’ll see from the example the workspace displacement size needs to be given as a negative number, because the stack is growing downwards.

1 will not be using these more advanced schemes for the examples in this book but it is useful to know that they exist. You will, for instance when using a debugger (such as Devpac’s MonAm) to disassemble compiler generated code, often see link/unlk instructions being used in this way.

There are characteristics of some subroutines which, although they will not be particularly important or relevant to the assembler newcomer, are worth briefly mentioning since the terms do crop up in the Amiga official documentation from time to time.

Truly relocatable routines are routines that may be placed anywhere in memory. They are created by using relative addressing instructions so that absolute memory references are avoided. You might think that, because of the way the Amiga loads its programs and data into any convenient spare memory that is available, that all Amiga programs would need to be relocatable. This isn’t true because the Amiga uses a piece of program loading software called a relocating loader which is able to take a program containing absolute address references and modify them (ie add a loader calculated offset) so that the program runs properly at the chosen location.

Re-entrant routines are routines that may be interrupted, called by the routine which did the interrupting, and still produce the right results. This allows interrupt system code to make use of available system routines.

Recursive subroutines are routines which are able to call themselves during the course of their operations. Subroutines which preserve their registers and use only those registers and the stack for storing data will be capable of being used recursively. Needless to say they will also be re-entrant!

Subroutines on the Amiga are very important and, as mentioned earlier, the Amiga’s run-time and link-time function libraries contain a great many pre-written subroutines for you to use. It is no exaggeration to say that upwards of 80% of the assembly language code that the average Amiga assembler programmer will write will be library related and consist of calling pre-written functions to do particular jobs. To a large extent your coding efforts will just revolve around making sure that your program performs the necessary library routines in the right order and with the right types of integrity checks.

In many ways the use of pre-written routines can be alikened to using a piece of hardware like a photocopier. If you use a photocopier to make a duplicate of something you go to the machine, place the document you wish to copy inside, press a button, and then just wait for the device to do its job. As likely as not you’ll do all this without knowing any real details about what goes on inside. In a sense the copier is acting almost like a magic black box. You know what input is required (the document to be copied), what must be done to start the copying process, and you know that some results will come back, ie you’ll get a copy of the input document.

This information hiding, black box, design concept is a very powerful way of protecting a user from unnecessary complexity. For the programmer, the pre-written subroutine unit provides exactly the same type of complexity hiding capabilities and, on the Amiga at least, constitute essential program building blocks to be used in the same way as the electrical engineer might use IC chips (integrated circuits pre-designed to do a particular job) to build an electronic circuit.

There is one general point about this pathway which is important. Although the user of the function doesn’t need to know how the subroutine works, they do need to know what it does, what information must be supplied, and the significance of the results produced, this means that the user must have suitable documentation for the system routines. This of course is one of the reasons that books such as the RKM Includes & Autodocs manual, which lists function usage descriptions for all of the Amiga’s library functions, are so important.

This book is not about program design but there is no doubt that programming a machine as complex as the Amiga is almost impossible unless you adopt some kind of forward planning. That for most people means taking more than a passing interest in the techniques used for program design. I’m not going to review the many tools which are available but I am going to provide some examples of a method that I have found to be of immense value with all kinds of programming, including 68000 assembler.

It’s based on a logic design tool called the Warnier diagram and, before looking in detail at the ideas involved, 1 want to make the following point. The methods I am about to discuss aim to obtain solutions to problems that are completely independent of both the computers and the languages which might eventually be used to implement the chosen design. These latter factors may well affect the final coding stages, but they should not usually influence the overall layout of the design.

So, what is a Warnier diagram? Essentially it is a set of curly brackets, that define both particular groups of operations and the order in which they should be performed. The easiest way to show you about these diagrams is to take some examples and I’ll start by taking one which will let me explain some important diagram conventions.

Imagine we wish to produce a report, consisting of details held on a computer file on disk. The Warnier diagram of the basic problem is shown in Figure 5.1.

Figure 5.1. Essential characteristics of the simple report generator.

The bracket is read from top to bottom and describes a procedure or group of operations that has, arbitrarily, been called REPORT. The numbers which you see written underneath the various statements identify how many times the item is to be performed and, with just those two conventions, our first diagram is already illustrating some of the essential features of the problem.

Do we know anything more about the problem? Can we think of any information that could be relevant? Well, we know that computer files need to be opened before reading and closed once the read operation is complete. These details could therefore also be added to the diagram. To enable us to explain some further conventions used with Warnier diagrams let us first add a minor complication to the problem. Let us suppose that the user wishes to access a file of his (or her) own choosing and to obtain a printed report of the details on the file. The specified file may not exist, and, if this is the case, the user should be informed. These changed or altered requirements can be represented by a more detailed Warnier diagram.

Figure 5.2. Some new restrictions added to Figure 5.1.

Figure 5.2 shows, in Warnier diagram form, the requirements of the problem as it is at the moment. We are using the convention that the logical opposite of a statement is written by placing a bar over it.

FILE EXISTS means FILE DOES NOT EXIST

We are also using a ©sign to separate mutually exclusive operations (sets of operations which will not occur together). In the present example the file will either exist or it will not exist, so only one of these two operations would be performed at any one time and (0,1 time) is written underneath the statements involved. At other times the operations shown within a bracket may need to be repeated and in these cases an expression such as (1,N times) would be used.

The conventions used so far are in fact the only ones you will need for the majority of problems that you are likely to encounter. Here they are collected together for convenience:

Using these conventions we can express in English exactly what Figure 5.2 tells us: we are dealing with a certain procedure, called REPORT that starts by asking for the name of a file. If the file exists then it is opened, accessed, the details printed, and then the file is closed. If it does not exist then the operator is informed of the fact. Remember that if the file does exist then it is the group of actions (subset) shown to the right of the label FILE EXISTS that are performed.

To appreciate the elegance and speed with which these diagrams can accommodate changing requirements let us place some further restrictions on this problem. Within this hypothetical computer system are files containing sensitive data, perhaps personnel data, wages or medical records. Such data must be protected from unauthorised access and users are therefore issued with access code numbers, so that examination of sensitive files is restricted to those users with the proper authority. If unauthorised attempts to access this data are made the computer should record the fact, perhaps by making an entry into a special security file.

Let us first consider the new constraints in isolation. We need to check whether the file specified by the user is a restricted file, if it is we must ask for the user’s code number. If the code is correct then we allow access, if not we write a security record indicating an attempted illegal access.

Figure 5.3. A hierarchy is forming within the revised problem.

The diagram in Figure 5.3 shows the Warnier form of our new requirements. Notice that as we redefine the problem and add more detailed restrictions it is not necessary to rearrange the complete diagram, as one frequently needs to with flowcharts etc. All we have to do is superimpose the new details and restrictions on to the existing diagram structure. The diagram is therefore actually growing as we successively modify and redefine the known details of the problem. You’ll see later that the Warnier diagram is not only documenting and expressing the logical requirements of the problem but it is doing so in a way that will make the transition to a computer language equivalent form remarkably simple.

The ability of the Warnier diagram to display, help formulate, and to grow with the changing logical requirements of a problem, as that problem is examined, is of great importance. Once the quite simple conventions have been learnt these diagrams can be read just like the written English equivalent but, unlike the written English form, a Warnier diagram contains within its deceptively simple notation, the complete solution to the coding of the problem.

The secret of converting a Warnier diagram into a finished program lies in regarding each bracket involving more than one operation as a subroutine. There are certain exceptions to this general statement but the pseudo-BASIC sketch shown in Figure 5.4. should give you the general idea.

You will doubtless have realised that in creating a Warnier diagram we are to a large extent planning the program control structure of the piece of software being designed. Consequently conversion to 68000 code revolves essentially around program control structure issues and there are a few points which are worth making about the 68000’s instruction set and the various instructions which can be used for creating the necessary control units.

The 68000 as you know has two basic goto-like ways of transferring control. The jmp instruction which uses a full sized address, and the bra instruction which uses relative addressing based on a 16 bit displacement. In addition to this there are conditional branch instructions, which take the general form bcc and dbcc, that are able to perform relative branching when specified conditions are met or not met (branch on zero, branch on plus and so on).

The 68000 also supports two basic subroutine type instructions The branch to subroutine bsr instruction is the relative addressing form of bra which additionally places a return address on the stack allowing a terminal rts instruction to transfer control back to the instruction immediately after the one that caused the subroutine branch in the first place. The second subroutine instruction of interest is the jump to subroutine jsr form which, like jmp, uses a full sized address rather than a displacement, jsr works like a jmp instruction but like bsr it places a return address on the stack.

In the context of usage flexibility there is a very important difference between the relative branching bra type instructions and full address orientated jmp and jsr forms. The latter instructions have much more scope in terms of available addressing modes. In fact there are seven addressing forms listed as being available for the jmp and jsr instructions:

The indirect addressing modes are particularly useful for creating some of the more complex control structures. The instruction:

jsr (a5)

for instance, performs a subroutine call to a location whose address has been placed in address register a5. The 68000 also has a load effective address lea instruction which can compute and load an address register with an address computed using any of the 68000’s addressing modes. This means that even with the simple indirect subroutine call the processor can be instructed to perform an infinite number of complex subroutine call arrangements. The first instruction of the following fragment, for example, takes an address held in register a2, adds it to the value held in register d4, and then adds a program-specified fixed offset (12 hex in the example) to produce an operand address which is then loaded into register a5. The second instruction performs a subroutine jump to that calculated address:

lea $12(a2, d4.1) a5 jsr (a5)

Not only does this mean that we’ve got very flexible conventional run-time (dynamic) and static address calculation facilities but also that things like key-to-address transformation (hash based) schemes are also relatively easily built: jsr CalculateAddress calculate hash address in do

The net result of all this is simple: the 68000 itself is not likely to place any restrictions on what you can do control-wise because all manner of clever schemes can be devised. In fact once you start working at the processor level you begin to realise that the addressing modes of the 68000, coupled to its relatively symmetrical instruction set, actually tends to liberate, rather then restrict the programmer. At times I sometimes wonder whether it isn’t the high-level languages which suffer from shortcomings rather than the low-level ones although I’m sure most people would disagree.

The point again needs to be made that one of the reasons that I feel just as comfortable working with assembly languages as with high-level languages is that before I write one line of assembler code I’ll have a logical plan available which shows what must be done!

I’ve made quite a point elsewhere of talking about information hiding and black box units, subprogram/subroutine units. The ability to create isolated pieces of code which can be used without knowing how they operate makes for re-useable and easily modifiable code units. Inherent in such ideas of modular program construction come two other needs: decent parameter passing schemes as opposed to routines which use a hotchpotch of globally accessible memory locations, and the ability of a routine to create and use variables which are known only to them. Languages like C provide inbuilt mechanisms for parameter passing and use of local variables, but how can we do it from assembler?

There are a number of schemes but one, stack-based allocation, stands out as being particularly important. The idea is simple. As a subroutine is entered the stack pointer register is altered so that some temporary working space is preserved on the stack for the variables and other quantities needed by the routine, conveniently accessed by setting up a frame pointer which allows the workspace to be accessed indirectly. The 68000 has a powerful instruction pair called link/unlk which allows this whole process to be automated.

Another important technique, which we’ve already discussed, is that of preserving and re-instating processor registers during subroutine calls. At the start of the routine you preserve, by pushing onto the stack, those registers which are going to be utilised during the subroutine call. Just before the routine terminates the pushed values are pulled off the stack and used to return the processor to its original state.

For now though, with the above preliminaries out of the way, it’s time to look at some of the basic ways in which the sequence, repetition and alternation building blocks can be tackled with 68000 assembler.

As you might expect, sequence is the easy one. Sequence is implied simply by virtue of the order in which statements are written. If, for example, you need to code something like this:

j INITIALIZE REPLY STRING < COLLECT USER REPLY I INTERPRET USER REPLY

then, if all the operations were going to be handled as subroutines,you might write something along the lines of:

jsr InitializeReplyString jsr CollectResponse jsr InterpretReply

of course if one or more of the operations were simply enough, ie consisted of just a few relatively obvious instructions, then they might be coded in line.

Suppose that the above routine was using aO as a reply string pointer and that the strings were using the NULL terminator convention. To initialize a string in such a situation all that needs to be done is to set the first byte (which would be the byte represented by the address held in aO) to NULL, so the above example would just as likely be coded as:

move.b #NULL,(aO) initialize reply string to "" jsr CollectResponse jsr InterpretResponse

Similarly if you were using some system routine to collect a user string and this routine needed to have the start of the string supplied in dO you might have a fragment like this:

In such a case it’s not hard to see the sort of translation that would be needed:

move.b #NULL,(aO) initialize reply string to "" move.l aO, do system requires start address in dO jsr CollectResponse jsr InterpretResponse

Consider the following fragment:

GET CHARACTER (1, n times)

Repetitive sets, when coded, end up as loops. If we choose register dO as a loop variable then the obvious way of coding the above fragment would be along the lines of:

move.b #L00PC0UNT, dO Loop jsr GetCharacter subq. b #1 ,dO bne Loop

Of course the 68000 has an automated loop instruction dbcc which handles both the counter modification and, if needed, an extra conditional exit test. Bearing in mind that dbcc quits the loop when the counter register hits -1 (so the count must start at one less than the required value) we’d probably write the above loop like this:

Loop move.b #L00PC0UNT-1,dO jsr GetCharacter dbra dO,Loop

If the extent of the repetition is not known in advance, as in the now well-worn case of collecting keyboard characters until such time as a return key is detected, then we modify the test conditions accordingly. Supposing that in the above example the GetCharacter routine, as well as placing the collected character into a string buffer, also returned the character in question in register dO. The code fragment would then need to be something along the lines of:

Loop jsr GetCharacter cmp.b #CR,dO bne Loop

At times you might wish to show the exit conditions explicitly on your Warnier diagrams. The fragment for the above example might therefore have been written as:

It is not worth being pedantic over the form, or the notation, for such translations. If a repetitive loop requires an exit condition which is obvious to code then there is little point in cluttering up the Warnier diagram with unnecessary detail. Having said that there is, for documentation purposes at least, a case for including some note about any tests which are implied rather than explicitly diagrammed. Bracketed comments do nicely here:

The bottom line then is simple: you take your diagram detail to the point where the actions being specified become easy to code. Obviously the point where this occurs will vary according to your programming abilities and the problem being dealt with!

The above loops are post-test forms - the exit condition occurs at the end of the loop. Pre-test repetition, ie repetition of the while/wend variety, is just as easy to create. Take the following diagram fragment:

if we assume that aO holds the address of the first byte of the string being dealt with, we might code the above fragment like this:

cmp.b #NULL,(aO) is first byte a NULL? beq Here jsr ConvertToLowerCase Here

The implication here is that if the string is empty, ie contains only a terminal NULL character, then the ConvertToLowerCase routine is never executed. It’s interesting to note, but I’m not going to dwell on this, that the assembly language form actually shows the fundamental nature of the repetitive set which occurs one or more times. The above code actually represents this situation:

CHAR = NULL / CONVERT TO LOWER CASE (0,1 times) MODIFY STRING ) (1,n times) ' CHAR = NULL ^(0,1 times)

To be honest we’ve already started looking at alternation in the sense of loop termination testing. The if-else type testing needed for fragments like: / CHECK PRINTER < PRINTER CONNECTED © PRINTER CONNECTED < < (this routine will return zero flag set if printer is properly connected) print file tell user printer is not connected

can be coded using these type of schemes:

Print Here jsr CheckPrinter beq Print jsr PrinterMessage bra Here JSR PrintFile z flag indicates connection

It is possible to extend the above simple alternation schemes to cater for case alternation. This leads to a step by step evaluation of each case. For example:

LINEFEED © CARRIAGE RETURN < © TAB © BACKSPACE © OTHER CHARACTERS \ could be coded using this type of framework:

LinefeedTest cmp. b LINEFEED,dO bne CarriageReturnTest do line feed related stuff bra CaseEnd CarriageReturnTest cmp. b #CARRIAGE_RETURN,dO bne TabTest do carriage return related stuff bra CaseEnd TabTest cmp. b #TAB,dO bne BackspaceTest do tab related stuff bra CaseEnd BackspaceTest cmp. b #BACKSPACE, dO bne OtherCharactersTest do backspace related stuff bra CaseEnd OtherCharactersTest ignore or do whatever else is necessary CaseEnd…​

Whether the individual actions associated with each case get written as subroutines calls, instead of being written in line, depends to a large extent on what is involved. If you are happy that the necessary code details are easily handled then by all means place them in line. Here’s an example. Suppose that the fragment we’ve just discussed had to expand tab characters to spaces. The relevant details might have been diagrammed as:

j^(aO is the pointer to the buffer holding these input characters) LINEFEED < 0 / CARRIAGE RETURN < / © < TAB (expand tab character to spaces) (variable g_tab_count holds value one less than the equivalent spaces number) < © INSERT SPACE (1, n times) insert space in current location increment string pointer \ BACKSPACE < © OTHER CHARACTERS < \

The general type of loop for such space insertion would therefore go something like this:

InsertSpace move. b g_tab_count,d1 get conversion count move. b #SPACE,(aO) insert space addq.l #1 ,a1 move to next character subq.b #1 ,d1 decrease count bne InsertSpace Using post-increment addressing and the specialised dbcc instruction, the above loop can be written more concisely as: move.b g_tab_count,d1 get conversion count InsertSpace move.b #SPACE, (a0)+ insert space/increment aO dbra d1, InsertSpace

There would be no problem in coding those three lines directly. Most assembly language programmers would be able to fill that TAB segment so that the skeleton code framework then looked something like this:

LinefeedTest cmp. b #LINEFEED,dO bne CarriageReturnTest do line feed related stuff bra CaseEnd CarriageReturnTest cmp. b #CARRIAGE_RETURN,d0 bne TabTest do carriage return related stuff bra CaseEnd TabTest cmp. b #TAB,dO bne BackspaceTest move.b g_tab_count,d1 get conversion count InsertSpace move.b #SPACE,(a0)+ insert space/increment aO dbra d1, InsertSpace bra CaseEnd BackSpaceTest cmp. b #BACKSPACE, dO bne OtherCharactersTest do backspace related stuff bra CaseEnd OtherCharactersTest ignore or do whatever else is necessary CaseEnd…​

The key, as always, is to only code those aspects which to you seem crystal clear. If you’re having trouble figuring out what sort of code should be written for a particular piece of diagram then the chances are that you’ve not taken the diagram to a sufficient level of detail. The solution is simple - expand your diagrams until they do represent that required detail.

It must be said that, although the above approach has the advantage of being simple, there are occasions when it is inappropriate. One example which springs to mind is where a very large number of individual cases need to be catered for - if, for instance, you have a hundred different cases the above arrangement would lead (on average) to each character being tested fifty times. If you need fast case testing then the above approach is not going to help and alternative schemes need to be found. Here much depends on the particular application but if the values of the case structure entries are close together an indirection table, which provides the addresses of all of the case entries, can be used. You could, for instance, set up a table of routines like this:

INDIRECTION_TABLE: dc.1 Sub1, dc .1 Sub6 Sub1: some rts relevant code Sub2: some rts relevant code Sub3: some rts relevant code Sub4: some rts relevant code Sub5: some rts relevant code Sub6: some rts relevant code Sub7: some rts relevant code Sub8: some rts relevant code Sub2, Sub3, Sub4, Sub5, Sub7, Sub8…​ etc…​

It’s then possible to index the appropriate address locations and use an indirect subroutine call to select the appropriate piece of code:

move.l #INDIRECTI0N_TABLE,a5 base address (assume that the case data is in do so dO times 4 will be the required table offset) asl.w #2,d0 multiply by 4 move.l (a5,d0.1), aO jsr (aO)

If it were necessary to transfer control to some place other than the place after the subroutine call you could modify the above scheme by pushing your own return address onto the stack and then follow this with the equivalent jump instruction:

jjjmove.l #INDIRECTI0N_TABLE,a5 base address (again assume that the case data is in dO) asl.w #2,dO multiply by 4 move.1 #EndCase,-(a7) push return address move.l (a5,d0.1),a0 jmp (aO) (some other code or data, perhaps the indirection table itself, that shouldn’t be executed) EndCase…​ continue execution at this point.

The overall diagram<→code conversion strategy should now be pretty clear. Having described the structure of the program using a Warnier diagram (or set of such diagrams) the conversion proceeds primarily by coding the various bracket levels as subroutines, only adding suitably detailed in-line instructions when the operations being dealt with are straightforward.

The reason why this approach is so effective is simple: It’s because most (if not all) of the design issues, as far as program structure is concerned, will have been dealt with before any coding is done. Consequently you’ll never at this stage have to ask questions like "whereabouts in the overall program should this piece of code be placed?", or "what happens if this routine receives a character other than the ones it expects to receive?".

I mentioned earlier that, as far as this type of diagram use is concerned the design process is iterative. This begs the question: when do you know that a diagram is finished? The answer is that you know that a diagram is finished when you look at the lower, ie most detailed, diagram levels and think: "Hey, this isn’t so bad. All those things look easy to code!".

I certainly do not get such translations right every time, neither does anyone else, and incidentally neither will you, no matter what design techniques you choose to adopt. Fortunately you’ll know when you haven’t provided a sufficiently detailed plan - all of a sudden you’ll hit coding difficulties because you are not quite sure of what you are doing. That of course is the time to stop coding, go back to your design diagrams, and think, preferably in a language-independent way, about what you are trying to do.

I will not be emphasising the pre-code design issues elsewhere in this book and certainly am not going to force you to adopt the use of Warnier diagrams. What I do want to drive home though is this: these pre-coding design issues, as any professional programmer will tell you, really are very important. Some knowledge and experience of either Warnier diagrams or some equivalent technique will make your life as a 68000 coder considerably easier!

In-line commenting, whilst important, should still be considered essentially as an addition to, and not a replacement for, any self-documenting facilities of the language itself. Self-documenting facilities? Yes, nowadays almost all languages allow useful conventions to be adopted which can help to make the source code more intelligible and 68000 assembler is no exception.

Use understandable names for variables and symbolic constants. Adopt conventions such as prefixing global variables with the character g_ and suffixing pointer variables using _p, so that the type of variable can be implied from its name:

move.l #FALSE, g_exit_flag ;clear exit flag - user has decided not to quit

is a much preferred alternative to code which reads like this:

move.l #0, ef ;clear global exit flag user has decided not ;to quit

Don’t get carried away with such conventions. You are after all aiming to produce guidelines which can help, not build rigid restrictions which will hinder. For the most part all that’s needed is a common-sense understanding of the usefulness of in-line documentation, coupled to a consistent methodical approach. A bit of thoughtfulness in these areas will pay handsome dividends.

Before leaving the topics of languages, documentation and so forth there’s one last point to make. Whatever conventions you adopt you will need more documentation than any language alone can provide. Programmers are of course more noted for their Let’s do some coding attitudes than for any excessive desire to document their programs. But eventually failure to keep adequate notes will cost dearly, both in lessons not learnt and in lost time. The following guidelines provide a reasonable starting point although I’m sure that you are not going to be short of your own ideas:

If possible try to develop a pseudo-standard layout for all your projects. Produce development notes that, in conjunction with any design work, will show what the objectives of writing the program were, and explain the reasons behind your approach. The task of producing this documentation is not quite as onerous as it might seem. If you have a text editor program then you can keep most of the documentation on disk, which has the advantage that it is very easy to keep up to date.

Keep all of your design diagrams etc, and make notes about the problems you encounter during the development. Especially note any assumptions you make that might affect program operation if they were changed in the future. Note also which parts of the code are dependent on, eg the operating system I/O characteristics, particular control characters that might vary from system to system etc.

If the routines are small then include the documentation with source code. Remember, if a routine requires a particular format for the data that it works on, then provide some sort of indication within the routine itself so that the general ideas behind it are apparent. Use titles that indicate what operations the routines perform.

Keep some details within the source code itself telling you the name of the program, when it was written, where any additional documentation may be found and notes about other points which might be relevant. A simple scheme is usually all that is required as such that shown in Figure 6.1. below. Don’t bother about trying to understand what the code does but do notice how much use I’ve made of understandable labels, variable names and in-line comment.

Figure 6.1. A typical piece of documented code.

Since the programs that you write are part and parcel of your documentation it is worth digressing for a moment to make the following point: in the same way that a standardised documentation layout helps to provide consistency, so does a standardised program layout. But all your programs are different? Well yes, to a certain extent this is true, but there are many things about the overall structure that will often be similar and a bit of consistency in style and overall layout can go a long way!

Unless you have come to the Amiga via the world of Unix or the mainframe, most of the ideas related to multi-tasking will be new to you. Similarly there may be a lot of other issues concerning the protocols which Amiga programs need to adopt that may seem rather complex, to say the least. None of this complexity however is there just for the sake of it and by learning about and applying the rules that your programs must follow to co-exist in a safe and system controlled manner, you will save yourself much grief when you move on to the writing of larger programs.

You know already that on the Amiga many programs can be running at the same time. Imagine the chaos which would ensue if one program suddenly decided it wanted to take over control of the disk hardware whilst another program was using it. These types of contention issues, where two or more programs could conceivably be trying to use the same system resources at the same time, cannot be solved at the hardware level. On the Amiga a software system has been devised which solves this problem, thus making it possible for many different programs to share a common set of hardware resources. A key element in this scenario is the Amiga’s multi-tasking Exec software. But before discussing Exec itself, a few words about some other Amiga entities are needed.

As far as hardware access is concerned the Amiga places a software layer, based on the use of a software entity called a device, between the real hardware and the applications programs. If, for example, your program wishes to gain access to the serial port it must try to open the serial device. Providing the device is successfully opened the program then writes or reads its serial data using the serial device and not the underlying hardware.

This arrangement provides all programs with a standardised way of communicating with the Amiga’s hardware and neatly solves the potential contention issues. It doesn’t alter the fact that sometimes, because a piece of hardware is already in use, a program will not always be able to open the corresponding device, but it does mean that programs can ask and be informed about what is and what is not available for use at any given time and can therefore take some appropriate actions.

If, for instance, during the time the serial device was being exclusively used by one program, another program tried to gain access to the serial device to read and write totally unrelated data, the open serial device request would fail. This is the system’s way of telling the second program that the underlying hardware is not available for use.

In short then the Amiga’s devices provide this sort of standardised software interface between the programs which may be running and the hardware itself. See Figure 7.1.

Programs open these devices and then tell them, rather than the underlying hardware, what operations they wish to perform. \ \ \ \ \ \ Trackdisk device Audio device Serial device Parallel device Keyboard device Gameport device 1 1 Disk control hardware Audio hardware Serial port hardware Parallel port hardware Keyboard hardware Joystick and mouse ports

Figure 7.1. Beneath the device software lies the real Amiga hardware.

Because of this approach you’ll realise that, initially at least, it is the devices which the programmer needs to understand rather than the underlying hardware. There are incidentally other Amiga devices, such as the Console and Input devices, which are not directly tied to particular hardware units.

The device software barrier is not the only one which isolates an Amiga programmer from the underlying hardware because a similar situation exists with the main processor itself. On the Amiga the chances, even once you are an experienced system programmer, of getting anywhere near the 68000 microprocessor’s on-chip interrupt system are very remote unless you are prepared to take over the whole machine. Interrupts are hardware signals which cause the processor to stop what it is doing and execute a predetermined piece of code called an interrupt routine.

Why? Again, in a word, multi-tasking. This time the issues are to do with how the processor is able to appear to run more than one program at any given time. In reality a single 68000 chip can only run one program at a time, so the only way that the Amiga can multi-task is for the processor time to be physically shared amongst the various programs wishing to run. Each program in turn has to be given a bit of time to run and when this time slot is up the program has to be suspended whilst another program is activated.

This, as you might imagine, is not a trivial task. Each program must think that it has a virtual machine all to itself. Programs must have their own stacks and whenever the execution of a program is temporarily suspended, things like current microprocessor registers will need to be preserved. When the same program is again given the chance to run, all of this information must be reinstated before the program can continue running.

Such tricks are achieved with the help of some clever programming of the 68000 interrupts. Exec keeps track of the state of the multitasking game both at the end of all interrupt processing and on occasions when a particular task has indicated that it wishes to sleep, ie become inactive, for a while. A typical example of this latter situation would be a program which is waiting for a user to hit a gadget before doing anything. Such programs can call a WaitO function which results in program execution being suspended until a gadget is actually selected by the user. The benefits should be obvious - during such times the processor doesn’t have to waste time running a program which is effectively sitting idle but it can be getting on with something else.

The software which performs this task switching magic is called Exec. Every time, for example, a vertical blanking interrupt occurs the current tasks are examined and, depending on the system conditions, a decision is made as to whether to allow the current program to continue running or whether to suspend it and give another program the chance to run.

The process of deciding which task should be running, and then kicking it off (getting it going) if necessary, is called taskscheduling. If all tasks have equal priority then they are given equal shares of the processor’s time and each task, providing it is in fact ready to run, takes its turn using an I’m next for some processor time task queue arrangement, known as a round robin scheme. Because the tasks themselves have no say in whether they run or not, this time-slicing is called pre-emptive task-scheduling.

For now though we need to get back to the interrupts issues. The 68000 has three interrupt lines which are used together to provide interrupts of differing priority. It’s important, at this stage, to point out that the Amiga’s interrupt system is not purely based on the 68000 facilities - something is happening at a higher hardware level. One of the Amiga custom chips, the 4703 (known as Paula) is actually watching fifteen different sources of interrupt, both hardware and software instigated, and it’s this chip that then generates the real 68000 signals.

So, disk, serial I/O related, copper, vertical blanking, blitter, audio,software generated interrupts and a number of other interrupt sources all pass through Paula as interrupts of varying priority levels. One of Exec’s most important jobs is to housekeep, ie look after, the whole of this interrupt system. Another is to provide multi-tasking facilities for the whole machine, ie to organise and perform pre-emptive task scheduling. When you also realise that the Amiga system allows any number of applications programs to set up their own interrupt jobs and that these, when executed with Exec’s blessing, slot neatly into the existing system interrupt arrangements, you’ll conclude that we are talking serious software here. Exec deserves, and should be treated with, the utmost respect!

Now for the bottom line. Exec, in order to achieve this magic, must keep absolute control not only over the real 68000 hardware interrupt system but the whole of the interrupt subsystem. This is why you will never, for example, deal with the 68000 interrupts directly - you will deal with Exec, the software layer which will handle your needs and translate them into a form suitable for the Amiga’s complex multi-tasking environment.

The beauty of Exec is that the multi-tasking is effectively transparent so your programs will rarely need to worry about the underlying complexity. Other facilities, such as those which allow messages to be passed between various tasks, are not transparent and it important to understand them if you wish to program at the Exec level.

AmigaDOS is a multi-processing operating system designed primarily for the single user. This is different from say Unix which was designed to be a multi-user, multi-tasking, operating system.

AmigaDOS handles the disk filing system and allows many jobs (processes) to run simultaneously. Much of the magic of AmigaDOS, the Amiga’s disk operating system, is actually due to the underlying Exec facilities. In a sense AmigaDOS is built on top of the Exec and trackdisk components of this system jigsaw puzzle so, from a purely schematic viewpoint, we can show the arrangement as in Figure 7.2.

Figure 7.2. Programs interact with the hardware via AmigaDOS, Exec and system devices.

If we now superimpose this sketch onto that of Figure 7.2 shown earlier, a useful picture starts to emerge. See Figure 7.3.

Figure 7.3. Programs interact with the hardware via AmigaDOS, Exec and system devices.

Already you should realise that the Amiga programmer is, to a very large extent, isolated from the real hardware. This is true even for the low-level programmer unless, as is the case with some games programmers, they are prepared to take over the whole machine and forfeit all the advantages of multi-tasking.

Another important component of the Amiga’s software is the system’s library routine arrangement. Library routines are just generally useful routines which have been written and included as part of the operating system software.

Where the Amiga differs from that of many less sophisticated computers is in the actual arrangement which has been adopted to implement these libraries. If you wanted to use a certain system call in the good old eight bit days (of CP/M machines and computers like the Sinclair ZX81, Apple II and Commodore 64), the chances are that you would use either a function number arrangement, where you made a call to a fixed entry location but provided a value in one of the processor registers which told the operating system which service you required, or alternatively you would actually know the memory address of the system routine being called. For Amiga programmers those days are over because most of the time you will not know where the system routines are. Some may be held in ROM, some will be placed into memory as the machine starts operating, and some taken from disk as and when a program decides that they are needed! Worse than that, the routines which are loaded into memory are not assigned fixed locations, they essentially get placed in any convenient area that is available and that means that the location of the library routines can change each time a library is used.

To move into this area of Amiga programming there are two things you’ll need to know. Firstly how to find these system routines, and secondly how to use them once you have found them. These are questions which I’ll deal with in Chapter 10.

Intuition, the Amiga’s high-level graphics interface which we’ve all come to understand and love, is built on the facilities provided by the graphics and layers libraries. By working in conjunction with the input device, a slightly higher-level device that is continually being fed information from the Amiga’s keyboard and gameport devices, Intuition is kept informed about what, if anything, users are doing in the outside world.

The Amiga’s Workbench uses Intuition facilities to provide its WIMP orientated user interface. Intuition, like Exec, is essentially a mass of pre-written routines much the same as any of the other system library. Because of the way both of these components interact with other parts of the system it is however useful to show them as distinct components.

On top of everything we’ve discussed comes the applications programs themselves - the programs which you run to do useful work! As you’ll doubtless already know, the Amiga supports both WIMP orientated interactionfusing Intuition’s windows, gadgets, menus etc) and command line CLI/Shell type programs.

Programmers can interact with Intuition to achieve many high-level WIMP orientated operations, can access the hardware via the Amiga’s device mechanisms, can use a large number of pre-written library functions to simplify common programming tasks, and can allow AmigaDOS to handle the nitty gritty details of disk file management and related housekeeping jobs. In addition to this the graphics/display subsystem (which includes both hardware components, such as the copper and the blitter circuits, and software components for handling things like animated graphics) is also available to any applications program which needs it.

When we put all of this together we end up with a picture, which though far from complete, should provide a working appreciation of how the various Amiga system components fall into place.

Figure 7.4. Relationship between the main software components and the underlying hardware.

As you will now appreciate, Exec, Devices, AmigaDOS, System Libraries and Intuition itself are extremely important. Understanding these components is absolutely essential if you wish to become a serious Amiga programmer. Luckily all that is really needed initially is an overall appreciation of the system coupled with some more detailed information on areas which are likely to be immediately useful to you. It is these latter topics that I’ll deal with over the next few chapters but to finish this chapter here are a few general notes on some hardware related issues that you may already have been exposed to.

Part of the power of the Amiga is undoubtedly due to the custom chips known as Paula, Agnus and Denise. These chips, known collectively as the PAD, are capable of running in parallel with the main 68000 processor - using odd clock cycles when the 68000 is not accessing external memory. A gate mechanism controls access of the system bus and thus ensures that the RAM/ROM chips, the 68000 processor, the I/O chips, and the PAD chips are all connected to the system bus at the appropriate times.

I’ve already mentioned the relationship of the 4703 Paula chip to the interrupt subsystem. The PAD also controls twenty five direct memory access (DMA) channels which allow RAM access to be achieved without using the 68000 processor. These DMA channels are dedicated to specific uses - 6 channels are for the screen bitplane access, 8 for sprites data, 1 for the co-processor (copper), 4 for the blitter, 2 for disk DMA and 4 for audio.

DMA access is restricted to chip memory. You’ve no doubt heard the terms chip memory and fast memory and as likely as not you already know what they mean. Just in case however a few words of explanation are in order.

In actual fact there’s nothing different about particular RAM chips themselves which lead to labels like chip memory and fast memory. It is all to do with the way the gate mechanism grants access to the system bus and to the effect on certain areas of addressable memory. Here are some details. The Amiga’s Motorola 68000 16/32 bit processor has an address space of 16 megabytes and, with the Amiga’s memory map, 8 megabytes of this are available for random access memory (RAM). The reason that not all of this addressable memory is the same stems from the fact that part of the RAM address space is shared by both the 68000 processor and the Amiga’s three custom chips. It is this shared memory that is commonly referred to as chip memory.

Now I’ve already mentioned that Paula, Agnus and Denise handle a number of specific tasks involving graphics, general screen display operations, DMA etc. The blitter incidentally, the device which can move pixel data around the screen at speeds approaching one million pixels per second, is part of the Agnus chip. The important point about all of this is that, under certain conditions these powerful chips can actually lock out the main 68000 processor, an operation known as cycle-stealing. This only happens when absolutely necessary (and during these cases the custom chips are performing operations more efficiently than the 68000 could do anyway) but the end result nevertheless is that programs actually running in chip memory at such times get somewhat rudely prevented from doing so!

Some clever hardware tricks however allow the 68000 processor, even whilst locked out of chip memory space, to still access RAM memory outside of this region. This non-chip memory, called fast memory for fairly obvious reasons, is therefore an ideal place for having your runable programs. For maximum speed therefore it is worth remembering that, ideally, you want to have both chip and fast memory available - programs can therefore run in fast memory and will not be slowed down by any custom chip cycle-stealing operations!

The overview you’ve just read has been made deliberately easy going. Many things which perhaps could have been mentioned have been left out. Why? It is because to mention them would have meant that I would have to have explained them and that would have turned a hopefully easily understood general overview into a more detailed, but far more disjointed, account. Subsequent chapters will now deal with a number of 68000 system programming issues in more detail but I am hoping that now the general Amiga system framework has been outlined, at least some of the topics will be less traumatic for the newcomer than they might otherwise have been.

The Amiga has a large collection of system include (header) files available. In fact two distinct versions of these files exist, one set for C programmers and the other set for assembly language programmers. The file set which assembly language programmers use have a .i (i for include) name convention whereas the corresponding C language equivalents use .h (h for header) suffix filenames. Essentially the material which they contain serves identical purposes but, because of the differences between low-level 68K assembler and the high-level C language, there are equivalent differences in the way various definitions are created. This book is devoted to assembly language so I’ll be talking almost exclusively about the .i include files. Bear in mind that when I mention an include file such as exec/memory.i that there is a corresponding file exec/ memory.h available for those working in C.

So, what do these files contain? Basically thousands of predefined constants, template definitions for things like screens and windows, and macros all designed to make life easier for you the programmer. That said, they only make life easier if you understand them and are familiar enough with them to use them effectively.

The best way to learn how to get the maximum benefit from the Amiga include files is to look at them, use them, and think about them - slowly but surely you will learn to find your way around them and, with practice, learn to use them in the way Commodore intended. If you are new to assembler you have a golden opportunity to study them in detail. Make the most of this opportunity, the effort which has gone into them is considerable and, along with examples from the world of Unix and the mainframe, these Amiga system include files are amongst the best ever written!

Purely from the point of view of space it is not practical to list every Amiga system file. Nevertheless an example of a .i include file is going to be given in order to provide a reference point for subsequent discussions. The following file, which is the 1.3 release intuition/screens.i systems file, is reprinted courtesy of Commodore-Amiga Inc:

IFND INTUITION_SCREENS_I INTUITION_SCREENS_I SET 1 * * $Filename: intuition/screens.i $ SRelease: 1.3$ © Copyright 1987,1988 Commodore-Amiga, Inc. ** All Rights Reserved * * IFND EXEC_TYPES_I INCLUDE "exec/types.i” ENDC IFND GRAPHICS_GFX_I INCLUDE "graphics/gfx.i" ENDC IFND GRAPHICS_CLIP_I INCLUDE "graphics/clip.i“ ENDC IFND GRAPHICS_VIEW_I INCLUDE "graphics/view.i" ENDC IFND GRAPHICSRASTPORTI INCLUDE "graphics/rastport.i" ENDC IFND GRAPHICS_LAYERS_I INCLUDE "graphics/layers.i" ENDC ===Screen STRUCTURE Screen,0 APTR scNextScreen APTR scFirstWindow WORD scLeftEdge WORD sc_TopEdge WORD scWidth WORD scHeight WORD scMouseY WORD scMouseX WORD sc_Flags APTR scTitle APTR scDefaultTitle ; Bar sizes for this Screen and all Window’s in this Screen BYTE scBarHeight BYTE scBarVBorder BYTE sc_BarHBorder BYTE sc_MenuVBorder BYTE scMenuHBorder BYTE sc_WBorTop BYTE sc_WBorLeft BYTE sc_WBorRight BYTE sc_WBorBottom BYTE sc_KludgeFillOO ; This is strictly for word-alignment ; the display data structures for this Screen APTR scFont ; this screen’s default ; font STRUCT scViewPort,vpSIZEOF ; describing the Screen’s ; display linked list of screens linked list Screen’s Windows parameters of the screen parameters of the screen null-terminated Title text for Windows without ScreenTitle position relative to upper-left position relative to upper-left see definitions below STRUCT sc_RastPort,rp_SIZEOF ; describing Screen ; rendering STRUCT sc_BitMap,bm_SIZEOF ; auxiliary graphexcess ; baggage STRUCT scLayerlnfo,li_SIZEOF ; each screen gets a ; Layerlnfo ; You supply a linked-list of Gadgets for your Screen. ; This list DOES NOT include system Gadgets. You get the ; standard system Screen Gadgets by default APTR sc_FirstGadget BYTE sc_DetailPen ; for bar/border/gadget rendering BYTE sc_BlockPen ; for bar/border/gadget rendering ; the following variable(s) are maintained by Intuition ; to support the DisplayBeep() color flashing technique WORD scSaveColorO ; This layer is for the Screen and Menu bars APTR sc_BarLayer ; was “BarLayer" APTR sc_ExtData APTR sc_UserData ; general-purpose pointer to User data LABEL SCSIZEOF --FLAGS SET BY INTUITION …​…​…​…​…​…​…​…​…​…​…​. The SCREENTYPE bits are reserved for describing various Screen type available under Intuition. SCREENTYPE EQU $000F ; all the screens types available : --the definitions for the Screen Type WBENCHSCREEN EQU $0001 CUSTOMSCREEN EQU $000F SHOWTITLE EQU S0010 BEEPING EQU $0020 CUSTOMBITMAP EQU $0040 SCREENBEHIND EQU $0080 SCREENQUIET EQU $0100 STDSCREENHEIGHT EQU ■ J Ta Da! The Workbench for that special look this gets set by a call to ShowTitle() set when Screen is beeping if you are supplying your own BitMap if you want your screen to open behind already open screens if you do not want Intuition to render into your screen (gadgets, title) supply in NewScreen.Height J NewScreen initial Screen dimensions initial Screen dimensions initial Screen dimensions initial Screen dimensions initial Screen dimensions default rendering pens (for Windows too) default rendering pens (for Windows too) display "modes" for this Screen Intuition Screen Type specifier default font for Screen and Windows APTR nsDefaultTitle ; Title when Window doesn’t care APTR ns_Gadgets ; Your own initial Screen Gadgets ; if you are opening a CUSTOMSCREEN and already have a ; BitMap that you want used for your Screen, you set the ; flags CUSTOMBITMAP in the Types variable and you set ; this variable to point to your BitMap structure. The ; structure will be copied into your Screen structure, ; after which you may discard your own BitMap if you want APTR ns_CustomBitMap LABEL nsSIZEOF ENDC ; INTUITION_SCREENS_I

You’ll notice that the intuition/screens.i file starts by conditionally including a number of other files. The exec/types.i file for instance provides C language type definitions of a number of standard variable types, such as WORD, APTR and so on. These are not typedef style definitions as such - they are based on macro definitions which are as near as the 68000 assembly language programmer can get. STRUCTURE is another macro that is important because it provides the 68000 coder with high-level C type data structure facilities. The use of these and other important system macros will be dealt with in the next chapter.

A number of EQUate style definitions are also present but the bulk of the file includes two data structure definitions known as a Screen and NewScreen. To appreciate the significance of these structures it’s necessary to know a little about what they represent. STRUCTURE NewScreen,0 WORD nsLeftEdge WORD nsTopEdge WORD ns_Width WORD nsHeight WORD ns_Depth BYTE nsDetailPen BYTE nsBlockPen WORD ns_ViewModes WORD ns_Type APTR ns Font

Screen definition, in the Intuition sense, is achieved by setting up a complex data block known as a Screen structure. A quick look at the field definitions given in the RKM manuals or your compiler include files will convince you that building such screen structures from scratch is far from easy. Display memory has to be allocated, and a great many associated structures have also to be created and initialised. Fortunately you will never have to do this because Intuition itself can handle most of the setting-up procedures automatically.

To open a custom screen all you the programmer has to do is define the basic characteristics of the screen you require. This is done by initialising a much smaller structure called a NewScreen structure. Once these NewScreen details are defined it is possible to use an Intuition routine called OpenScreenQ. This function takes the parameters provided in the NewScreen structure, builds the real Intuition Screen structure needed to describe the display, and then returns a pointer to the structure it has prepared. As usual if things go wrong you’ll get a NULL-pointer returned which is, of course, the system’s way of telling you that the OpenScreenO request failed!

You’ll see from the example include file that, to the assembly language programmer, a NewScreen structure looks like this:

STRUCTURE NewScreen,0 WORD ns_LeftEdge WORD ns_TopEdge WORD ns_Width WORD ns_Height WORD ns_Depth BYTE ns_DetailPen BYTE ns_BlockPen WORD ns_ViewModes WORD ns_Type APTR nsFont APTR ns_DefaultTitle APTR ns_Gadgets APTR nsCustomBitMap LABEL ns SIZEOF initial Screen dimensions initial Screen dimensions initial Screen dimensions initial Screen dimensions initial Screen dimensions default rendering pens (for Windows too) default rendering pens (for Windows too) display "modes" for this Screen Intuition Screen Type specifier default font for Screen and Windows Title when Window doesn’t care Your own initial Screen Gadgets

From the practical viewpoint the thing that is most important to the programmer working at the Intuition level is an understanding of the fields present in the NewScreen structure. For the most comprehensive details of screen use, and all the other Intuition objects, you need to have access to the official RKM manuals. Flere however are a few details of the information held in the NewScreen structure.

ns_LeftEdge

The field represents the x position of the screen as it opens. It is provided for upward compatibility only and should be set to zero at the current time.

nsJTopEdge

This represents the y position of the screen as it opens and since most Intuition screens will open with their top edges in line with the real top edge of the display this value is usually also set to zero.

ns_Width

This field represents the width of the screen and is usually set to the nominal values of either 320 (for a low res display) or 640 (for a high res display).

ns_Height

This defines the height of the screen in scanlines. Non-interlaced PAL displays commonly use a value 256 (200 for equivalent NTSC displays).

ns_Depth

This field identifies the number of bitplanes being used for the screen.

ns_DetailPen

This identifies the colour register to be used for details such as the screen title.

ns_BlockPen

This is another colour register number which this time identifies the colour register which will be used for area fills.

ns_ViewModes

A number of flags are defined in the system headers which allow certain display attributes to be set:

HIRES selects high-resolution mode

LACE selects an interlaced display

SPRITES set this flag if you wish to use sprites

DUALPF in theory this flag tells the system that the screen will be using two separate playfields (playfield is just another term for screen background). In practice there are better ways of creating dual playfield displays. HAM this flag informs the system that you wish to use the hold and modify display mode.

EXTRAJ-1ALFBRITE informs system that an extra bitplane for extra half brite mode will be used. ns_Type This field can be set using a number of predefined flag values: CUSTOMSCREEN

SCREENBEHIND

SCREENQUIET

CUSTOMBITMAP you will always set this flag because all screens which are explicitly opened will be custom screens. if this flag is set the screen will open behind any existing screens. It is sometimes useful to do this so that any preliminary screen drawing operations can be hidden from the user. When the screen preparation is complete it can be brought to the front of the display. screens opened with this flag set do not have the usual title bar or gadget rendering. normally Intuition allocates a bitmap structure and the associated bitplane display memory. If this flag is set you are effectively telling Intuition not to bother to do this. In other words you are indicating that you will supply the appropriate bitmap structure and bitplane memory.

ns_font

This is a pointer to a TextAttr structure used to describe the default font for the screen. Set it to NULL if you wish to use the font specified in the Preferences settings.

ns_DefaultTitle

This is a pointer to a NULL terminated screen title string. Set to NULL if a title is not required.

ns_Gadgets

This field, which will be the first item in a list of user-defined screen gadgets, is unused at present. It is provided for future system expansion and should currently be set to NULL.

ns_CustomBitMap

If you have set the CUSTOMBITMAP flag in the NewScreen. Types field then you must supply a pointer to a suitably initialised BitMap structure in this field. Basically then the NewScreen structure is a template (a description) of a giant block of data containing items related to the creation of a real Intuition Screen structure. In order to use an Intuition Screen you must create one of these data blocks and, having filled it with suitable details, you will then be able to use this ready-made system routine to carry out the job of creating the screen.

Function: Description: Call Format: Registers: Arguments: Return Value: OpenScreenO Open a custom Intuition Screen screen_p=OpenScreen(new_screen_p); DO AO new_screen_p - pointer to initialised NewScreen structure screen_p - pointer to an Intuition Screen structure. If the screen could not be opened a NULL pointer is returned. Custom screens, which are what the screens which we have been discussing are called in the official system literature, have to be explicitly closed before the program terminates and a CloseScreenO call is available for this purpose.

Function: Description: Call Format: Registers: Arguments: Return Value: Close Screenf) Close an Intuition Screen CloseScreen(screen_p); AO screen_p - pointer to an existing Screen structure None

It should be apparent from the above discussion that an Amiga programmer is provided with an immense amount of system support. Equally apparent should be the fact that it is virtually impossible to program the Amiga without having access to details of the library functions, flag definitions, structure templates and so on, that the Amiga programmer is expected to use. This being so, it’s time that some very important books were mentioned.

Throughout this book you’ll find references to the Addison Wesley Amiga Technical reference manuals. Why? It is because they constitute the official Amiga programming documentation and, whether you’ve obtained them yet or not, it is worthwhile knowing a bit about their contents. The manuals have recently been updated to include additional material relevant to Workbench 2 and the following notes will give you a summary-style rundown on what you can expect to find in the current versions.

This volume deals with Intuition (the Amiga’s high level programming interface) and cover the use of screens, windows, gadgets, menus etc, from the programmers viewpoint. There are plenty of examples (mainly in C) to help the newcomer and the material is, in general, relatively straightforward to understand - so the reader has a moderately easy introduction to what is undoubtedly a most complex computer system.

Hidden beneath the Amiga’s Intuition interface lie some very complex software components. One such component which both merits, and gets, special attention is the multi-tasking Exec system. Topics covered include the use of Exec functions, library organisation, message passing, interrupts, and Exec’s I/O techniques. These are dealt with in detail and because they require a grasp of some difficult concepts this stuff is hard work even for experienced programmers.

This is also the volume where you can get authoritative details of the Amiga’s superb graphics facilities. As well as general introductions you’ll find accounts of such things as the Amiga’s display modes, image formation, viewport creation etc, and very detailed accounts of sprite handling, Bobs, and the use of the system’s animation facilities.

This manual provides separate chapters to each of the all-important Amiga devices, namely the audio, clipboard, console, gameport, input, keyboard, narrator, parallel, printer, SCSI, serial, timer and trackdisk devices. There’s a chapter on the low-level hardware control functions and on the the Interchange File Format (IFF). The IFF material provides useful introductory notes, the EA IFF 85 document, and the details of Form specifications. The graphics, music/sound-sampling, and all the other IFF areas are well covered as are many third party registered Form definitions. There is a good selection of code examples together with a reasonable level of tutorial style help.

After a brief introduction this volume dives straight in with a look at the Amiga’s co-processor unit, its instruction set, and its use. This sets the scene for a discussion of the playfield hardware and its relationship to the Amiga’s display facilities. The Amiga’s sprite hardware, audio hardware, and the now famous blitter chip all get a similar detailed treatment with the last two chapters being used to describe the remaining aspects of the Amiga’s system control and interface hardware.

If you like (or need) to get your hands dirty, ie have to understand and program the Amiga at a low level, or if you want to understand how to achieve things like vertical and horizontal smooth scrolling, then the hardware manual is the place to look.

This volume, as the title suggests, is more about user interface issues than coding. The volume provides basic advice on Intuition style and consistency together with notes on Workbench, Shell, AREXX, the clipboard IFF data sharing scheme and related issues.

You’ll find additional details of these and a number of other important Amiga reference books in the bibliography.

With assembly languages, as with any other computer languages, you frequently find that similar sequences of instructions crop up again and again. Now with sequences that are identical one solution is of course to write the instructions as a subroutine rather than waste space by having the same instructions duplicated in various places throughout the program. The subroutine approach reduces program size and has a number of benefits as far as program structure is concerned but there are still times when inserting duplicate sections of code is necessary, eg to eliminate the time in calling the subroutine. Often subroutines are inappropriate simply because the various sequences of instructions are only similar and not completely identical.

Macros provide a powerful solution to this dilemma because they allow the programmer to assign symbolic names to sets of instruction sequences and, whenever the name is encountered, the assembler automatically expands it to produce the original set of instructions. This facility is not restricted to predefined, absolutely fixed, instruction sequences. Macros which contain parameter placeholder markers can be created so that, when the macro is used, parameters provided with each particular instance are inserted into the code that is generated. This makes it possible for the macro programmer to generate a variety of code fragments from each macro definition.

Motorola style macro definitions start with a label followed by the MACRO keyword and end with the ENDM keyword. Lower case macro and endm are also accepted but to my mind the upper case versions mark the macro segment more clearly. The basic macro format therefore takes this type of form:

my_macro_name MACRO <main body of macro code> ENDM

Parameters are specified using the backslash (\) character followed by any alphanumeric character and as an example this macro code:

LIBCALL MACRO move.l a6,-(sp) move.l \2,a6 jsr \1(a6) move.l (sp)+,a6 ENDM

would, if used in conjunction with the following line of a program:

LIBCALL _LVODisplayBeep, _IntuitionBase generate this sequence of instructions: move.l a6,-(sp) move.l _IntuitionBase,a6 jsr _LV0DisplayBeep(a6) move.l (sp)+,a6

There is incidentally a reserved assembler symbol, NARG, which takes as its value the count of the number of parameters passed. When used in conjunction with the assembler directives IFGT (if greater than) and FAIL it becomes possible to add parameter count error checking to a macro. The above example could for instance be written as:

LIBCALL MACRO IFGT NARG-2 FAIL ;too many arguments ENDC move.l a6,-(sp) move.l \2,a6 jsr \1(a6) move.l (sp)+,a6 ENDM

This particular macro, which I look at again in Chapter 10, is actually already present in the system’s exec/libraries.i include file (under the name LINKL1B) and is used to generate library access code.

Macros resemble subroutines in the sense that they provide a shorthand reference to a frequently used set of instructions. It should be obvious from the above discussion however that macros are not subroutines. The code for a subroutine will occur only once within a program, and program execution branches to the subroutine. On the other hand, each time a macro is used the assembler will insert a copy of the appropriate instructions (with any parameter-specified alterations).

The advantages of the macro are numerous: shorter source programs, the ability to take advantage of pieces of tried and tested code, easier code changes and so on. In short, macros allow assembly language programming to be done at a significantly higher level than was previously possible and they are in fact an essential part of Amiga assembly language programming.

A great many pre-defined macros have in fact been made available to the programmer in the system header files. It is not possible to discuss all of them but a number of them are discussed later. Because of its importance in some of the code that we’ll look at in later chapters, one system macro does however deserve special mention.

I mentioned in Chapter Eight that the Amiga’s C header files contain, amongst other things, a mass of pre-defined structure definitions which relate to system objects such as screens and windows and that the assembly language .i include files contain similar structure definitions.

Now 68000 assembly language certainly doesn’t support the use of C style structures directly, but a macro has been developed which lets the assembly language programmer work with the next best thing. It is called STRUCTURE and it is, arguably, one of the most important system macros available. On the Amiga its use will flavour almost all the assembly language code you write making it cleaner, more comprehensible, and easier to maintain.

Firstly however a bit of C code for comparison. Suppose we were defining a C structure called ColourRange which stored details about minimum and maximum colour values, a flag to indicate whether values were increasing or decreasing, the amount of the increase, and the current RGB values. Using C we might decide to use something like this:

struct { UBYTE Minimum; UBYTE Maximum; UBYTE UpDownFlag; UBYTE Adjustment; ULONG Red; ULONG Green; ULONG Blue; }ColourRange;

What the include file’s STRUCTURE macro allows us to do is to write similar definitions in assembler. Here’s the above ColourRange STRUCTURE equivalent:

STRUCTURE ColourRange,0 UBYTE Minimum UBYTE Maximum UBYTE UpDownFlag UBYTE Adjustment ULONG Red ULONG Green ULONG Blue LABEL ColourRangeSIZEOF

The values UBYTE and ULONG are themselves macros which have been designed to calculate the sizes of C variable types. UBYTE (unsigned byte) for example actually equates to the value 1.

STRUCTURE then, is a macro that calculates the offsets for the member labels which you’ve used in your definition. In the above example the result would be these offsets. Minimum would equate to 0, Maximum to 1, UpDownFlag to 2, Adjustment to 3, Red to 4, Green to 8 and Blue to 12. The definition includes a preliminary offset and a further terminal macro called LABEL which is normally used to generate a S1ZEOF label. The benefit of generating a size value is that it becomes possible to reserve space for one type of structure within another structure definition.

The include files, as mentioned above, provide macros which calculate the sizes of all the usual C types, BYTE, UBYTE, BOOL, WORD, LONG etc, so the net effect is that if, for example, you use ULONG in the STRUCTURE definition, the macro will arrange to add 4 (because a ULONG variable is 4 bytes long) to the offset counter after the current assignment has been made.

The benefits? Firstly, the code is a lot more readable. Secondly, if at some stage you make changes to the defined structure you don’t have to worry about the offsets in your existing code - because the macro calculates the new displacements for you. Thirdly it lets you work, as far as the structures go, with almost highlevel language ease. The best way to illustrate the advantages of this macro approach is to give you a system orientated example and the one I’ve chosen concerns an Intuition communications facility.

If you had to cope with everything that Intuition took an interest in you, as a programmer, would have your work cut out. Fortunately programs can be selective about the type of events they wish to receive. If, for instance, a program needs to know when disks are inserted or removed it asks Intuition to send it a message about these events as, and when, they occur. If the program doesn’t need to worry about disk insertion and removal then it just does not ask for those types of messages to be sent in the first place.

One of the ways in which Intuition can be coaxed into sending information to a program is via Intuition’s Direct Communications Message Port system, affectionately called the IDCMP. This is built upon the Exec message system arrangement and provides a two way communication process which allows your program to both receive and transmit messages. IntuiMessages then, carry information to and from a window’s IDCMP ports and are based on this type of system defined message structure:

STRUCTURE IntuiMessage,0 STRUCT im_ExecMessage,MN_SIZE LONG im_Class WORD im_Code WORD im_Qualifier APTR im_IAddress WORD im_MouseX WORD im_MouseY LONG im_Seconds LONG im Micros APTR im_IDCMPWindow APTR imSpecialLink LABEL im_SIZEOF

The easiest way to gain access to an IDCMP is to specify one or more of the IDCMP flags when you open a window. If Intuition sees that you’ve done this it will automatically create a pair of message ports for that window. One port, the WindowPort, is used by Intuition, the other is referred to as the UserPort and is for the program’s use. Intuition arranges for signal bits to be allocated to the message ports and it is by looking at these signal bits that we can tell when messages have arrived.

In order to use IntuiMessages you need to be able to extract information from the structure. Here’s the purpose of the various fields:

The im_ExecMessage field contains message characteristics, such as the length of the message’s body data, which are needed by the Exec. You are unlikely to want this information and you certainly should not interfere with it.

im_Class is a variable whose bits correspond directly with the equivalent IDCMP flags. You will usually check the contents of this variable against particular flag definitions so that you know what type of message you have received.

The im_address of the object to which the message refers is provided in the imJAddress field. Whenever you have to find out about the current state of Intuition objects, eg whether a Gadget is on or off, you’ll use this address to locate the object’s structure.

The im_Code and im_qualifier fields depend very much on the type of message, eg if the keyboard device is providing raw keyboard data then the im_code field will contain the untranslated character and the im_qualifier field will tell you whether the Shift or Ctrl keys were also pressed.

Each message is stamped with mouse co-ordinates and the system time. im_MouseX and im_MouseY are the co-ordinates of the mouse at the time given by the im_Seconds and im_Micros fields. The other two fields in the structure are imJDCMPWindow, which is a pointer to the relevant Window structure, and im_SpecialLink which is used only by the system.

An Exec library is basically just a collection of routines which are accessed via a jump table. This is a table which provides offset values (6 bytes long) which are used to calculate the address of the function. The base address returned by the OpenLibraryO call is actually the address of the start of a library structure and this data structure is sandwiched between the jump table and other library specific data. The net result is that, once set up in memory, the library looks like Figure 10.1.

Figure 10.1. Library structure in memory.

The first four function jump entries OPEN, CLOSE, EXPUNGE and RESERVED must always be present. OPEN is an entry point called when the library is opened and is the routine responsible for incrementing the count of the number of users of a particular library. CLOSE is a corresponding routine which decreases the user count and, when the count gets to zero (ie the last library user indicates that the library is no longer needed) it may instigate an EXPUNGE operation which in more familiar terms simply means that the library is prepared for removal. The RESERVED vector is currently unused but is present as a gateway for system expansion.

The jump table entries are each six bytes long and so indirect addressing can be used along with negative displacements to identify any given function entry. These offsets, called library vector offsets (LVOs), mean that the programmer can associate with each library a set of LVOs like as shown in Figure 10.2.

t (High Memory) Library Specific Data base address—►Library Node Structure LVO - 6 OPEN LVO -12 CLOSE LVO -18 EXPUNGE LVO -24 RESERVED LVO -30 1st user function LVO -36 2nd user function (Low Memory) I

Figure 10.2. Library offset vectors.

I’ve already mentioned that the first stage in using a library is to open it by using the Exec OpenLibraryO function. You may now be wondering how it is possible to open the Exec library in the first place. The simple answer is that you do not need to because the Exec library never has to be opened. Exec’s base address, known as SysBase, is also permanently available. It is stored in memory location 4 (known as AbsExecBase) during system start up and so the Exec library is alive and kicking from the word go. AbsExecBase incidentally is the only absolute memory location present in the Amiga memory map (apart from things like the 68000 processor’s exception vectors).

By convention we place the base address of the library in register a6, and then make an indirect subroutine call using the appropriate library vector offset (LVO) value to specify the routine to be executed. I’ve already mentioned that in the case of the Exec library the base address is already available and so this can be loaded directly from AbsExecBase.

The bare bones code for an OpenLibraryO Exec call might therefore look like this:

move.l _AbsExecBase, a6 get the base address of Exec library jsr _LV00penLibrary(a6) make the indirect subroutine call

In practice you will probably want to preserve the original contents of the a6 register and, as we’ve seen earlier, the easiest way of doing this is to push the contents onto the stack beforehand: move.l a6, -(sp) move.l _AbsExecBase, a6 jsr _LV00penLibrary(a6) move.l (sp)+, a6

preserve original contents of a6 get the base address of Exec library make the indirect subroutine call restore a6 to original value

You might incidentally be forgiven for thinking that any register could be used to perform the indirect subroutine call. This is most definitely not the case in general and there is a strict system convention which says that a6 must always be loaded with the base address. Why? It’s because many library functions will call other library functions in order to carry out their work. When this is done the function doing the nested library call must also follow the system conventions and provide a library base address and by convention it will expect it to be present in register a6. Exceptions to the a6 rule do exist but to be honest it is safer if you forget about any special cases and regard the a6 rule as absolute!

You’ll notice in the above code fragment that AbsExecBase and the LVO value have underscore prefixes. This stems from an internal C language convention and the underscore used in all assembly language forms has been introduced simply to provide compatibility between C and assembler header files and code.

LVO offset values can be acquired in a number of ways. Firstly you could link your code with amiga.lib (which contains all of the LVO definitions).This would require that you tell your assembler that you are expecting the LVO reference to be resolved at link time so, somewhere near the beginning of your code you would need to include the statement:

XREF _LV00penLibrary

XREF is an assembler pseudo-op which tells the assembler that a value for the reference in question is going to be supplied at a later stage, ie at link time. Note, if you forget to use an XREF declaration the assembler will try to resolve the reference, fail, and then flag the use of that reference as an error.

Another approach is to include a header file of the LVO definitions in your program and the advantage here is that it is then possible to avoid linking with amiga.lib. This can firstly save time and secondly, if an include file containing the system start-up code is used, you can (by asking the assembler to create directly executable code) even eliminate the linking stage altogether.

Alternatively you could look up the numerical LVO value using a table of function offsets and use the values directly. You will find an abbreviated set of tables in Appendix B and from the Exec entries you’ll see that the LVO value for the Exec OpenLibraryO function is -552, ie -0228 hex. The assembly language programmer is therefore quite at liberty to define the displacement in this fashion:

move.l _AbsExecBase, a6 get the base address of Exec library jsr -552(a6) make the indirect subroutine call

The trouble with this latter approach however is that you will lose the inherent documentation that the LVO references provide. Let’s face it, the number -552 doesn’t, unless you’ve memorised all of the LVO tables, exactly tell you what library call is being made. The reference _LVOOpenLibrary is much more meaningful and in practice things can even be improved further.

The header file exec/libraries.i includes a piece of generalised macro code, called LINKLIB, that performs the task of preserving a6, loading a specified library pointer into a6, performing the indirect subroutine call using a specified offset, and then reinstating the original contents of a6 afterwards. The full details, which include argument count checking, can be obtained from the header file itself but in essence the job which is carried out is this:

move.l a6, -(sp) preserve original contents of a6 move.l <LibraryPointer>, a6 get the base address of library j sr <_LVORoutineName>(a6) make the indirect subroutine call move.l (sp)+, a6 restore a6 to original value

The bottom line therefore is that by including the exec/libraries.i file you can generate the appropriate library call code by writing:

LINKLIB LVOOpenLibrary, AbsExecBase

This is the officially offered macro but many programmers, for reasons of improved readability, prefer to use a modified macro which adds the _LVO prefix automatically.

It’s certainly not a good idea to modify the existing system macro (such changes lead to much confusion if other programmers have to read your code), but there’s nothing to stop you creating an extended macro which tags on the extra _LVO characters to the function name. Here’s one which will do the job.

CALLSYS MACRO LINKLIB _LV0\1,\2 ENDM

If you include this macro in your code you’ll then be able to create the appropriate library opening code using this simplified scheme:

CALLSYS OpenLibrary, AbsExecBase

To simplify things further it is equally possible to bury the library base references inside the macros. Devpac users, for instance, are provided with files that include both explicit LVO offsets and library specific calling macros. In the case of the above example the Devpac programmer, by including the Devpac specific execjib.i file, can just write:

CALLEXEC OpenLibrary

You can find full details of the Amiga’s extensive library routines and listings of the include files in the Includes & Autodocs volume of the Addison Wesley RKM manuals. Here are brief details of the some of the most useful libraries together with their standard base names:

diskfont.library library base name: DiskfontBase

This library contains routines for building and disposing of font detail arrays and for loading fonts from disk.

dos.library library base name: DOSBase

This contains all of the AmigaDOS file and disk I/O and process handling support routines.

exec.library library base name: SysBase

Routines for task control, list manipulation, I/O handling, messages and ports, interrupt and memory management.

graphics.library library base name: GfxBase

This is the library that provides support for Views, Viewports, RastPorts, BitMaps, GELS and all of the associated graphics and animation primitives. Included in this library are routines for controlling the Blitter and Copper chips.

intuition.library library base name: IntuitionBase

This library makes the complex WIMP graphics and WIMP control programming a piece of cake. These Intuition routines are built upon facilities provided by the graphics, layers and exec libraries and provide support for screens, windows, menus, gadgets, requesters, IDCMP communications ports and much more!

layers.library library base name: LayersBase

This library is not directly used that often by most programmers. It handles some quite difficult areas including the management of window refreshing, buffering of obscured areas, manipulation of damage lists, locking and unlocking of layers for handling contention problems etc. The layers library is of course used heavily by Intuition itself!

translator.library library base name: TransBase

Contains the TranslateQ function which can convert English text into phonetic strings.

maths libraries

A number of maths libraries for single and double precision operations are also available. Both Motorola fast (single precision) format and IEEE double precision formats are supported. Here are their names and library base names:

mathffp.library mathieeedoubbas.library

mathieeedoubtrans.library library base name: MathBase library base name: MathleeeDoubBasBase library base name: MathleeeDoubTransBase mathtrans.library library base name: MathTransBase

A number of other libraries are also available and under Version 2.0 of the system software further libraries have been added. Few of these are likely to be of much interest (or use) during your early assembler programming days but, if you are curious and would like comprehensive details, you should consult the official documentation.

Having dealt in some detail with the library arrangements and their usage conventions it is time to look at some example code. Example CH10-1 which follows uses the Exec OpenLibraryO function to open the intuition library:

Here are a few additional notes, sectioned off to correspond to the main divisions within the program, to help you find your way around the code. Firstly, some includes:

exec_libraries.i needed because it contains the system LINKLIB macro exec_types.i has been included because it contains definitions needed by exec_libraries.i exec_lib.i contains LVO values for the Exec functions

The CALLSYS macro was explained earlier in the text.

The following example is identical to the previous one except for two small changes. Firstly, I’ve set up the _SysBase variable. Secondly, once the intuition library is open it gets used! The duplication is deliberate and, since most of the following code will be familiar, all you’ll need to worry about are three additional lines of code. Here’s the code:

What changes have been made? Well, to start with I’ve defined the _SysBase variable and loaded the exec library base into it:

move.l _AbsExecBase,_SysBase store Exec library base

and I’ve added these two lines of code:

move.l #0,a0 flash ALL screens

CALLSYS DisplayBeep,_IntuitionBase

The following description of the DisplayBeepO routine should make it clear why aO needs to be loaded with a zero value before calling the function:

Function: Description: Call Format: Registers: Arguments: DisplayBeepO Cause a screen to flash DisplayBeep (screen_address); aO screen address - address of an Intuition Screen Return Value: None Notes: If a NULL screen address is supplied Intuition will flash all screens including those of the Workbench and other programs!

You’ll notice that the format for calling the intuition library function is no different from the original Exec calls that were used to open the intuition library itself. Admittedly we’ve got a different library base and a different LVO reference, but the mechanism is exactly the same as before!

One other change has been made - I have added the following EQUate definition:

_LV0DisplayBeep EQU -96

By now you probably know the reason well enough but I’ll work through the explanation once more for good measure. To use an intuition library, such as DisplayBeepO, we need to know the LVO value for the function. In this particular case I simply looked up the numerical value and created my own definition. This is a common solution if you are using an assembler which can create directly executable, as opposed to linkable, code.

Devpac, for instance, which can produce both executable and linkable code, provides include files which contain these values. In fact if the Devpac user included the intuition/intuitionjib.i file (which contains the _LVODisplayBeep offset) they would not need to add the EQUate line shown above to the example program.

At the risk of driving many of you nuts, I’m going to re-use the second example to show the changes which allow the _AbsExecBase,_LVOOpenLibrary, _LVODisplayBeep, and _LVOCloseLibrary references to be resolved at link time rather than at assembly time.

The conventional way for the assembler programmer to indicate that the above references are external would be to use XREF statements like this:

XREF _AbsExecBase XREF _LV00penLibrary XREF LVODisplayBeep XREF LVOCloseLibrary

Now this is all very well but having removed the _LVO prefixes from the bulk of the previous code it would be a pity to have to reintroduce them just to provide suitable XREF statements. There is in fact a system macro called EXTERN_L1B (defined in the exec/types.i file) that will add the _LVO suffix automatically. This allows us to write the last three _LVO references as:

EXTERN_LIB OpenLibrary EXTERN_LIB DisplayBeep EXTERN_LIB CloseLibrary

The following program uses these EXTERN.LIB macro statements (along with the single XREF _AbsExecBase declaration) to tell the assembler which values will not be known until the resultant object code has been linked with other files. Notice incidentally that inclusion of the execjib.i is no longer necessary because the Exec offset values are themselves also available from amiga.lib:

Despite the fact that most start-up code will, for CLI/Shell programs, open the DOS library and set up the standard I/O handles (known conventionally as _stdin and _stdout) it is useful to see exactly what has to be done. It’s not a difficult job and basically all a program needs to do is open the DOS library, and then make calls to two DOS functions known as InputQ and Output!). Opening the DOS library is no different to opening any other run-time library and so the code required will follow the general outline of that indicated in Chapter 10. Here are some brief details of the two DOS calls that are needed once the library is open:

Function: Description: Call Format: Registers: Arguments: Return Value: InpntO Identify a program’s initial input file handle file_handle = Input() dO None file_handle - the programs initial input file handle.

Function: Description: Call Format: Registers: Arguments: Return Value: OutputO Identify a program’s initial output file handle file_handle = Output() dO None file_handle - the programs initial output file handle.

The library opening code, which should already be familiar, takes this form: move. 1 AbsExecBase, SysBase lea dos_name,a1 moveq #0, dO CALLSYS OpenLibrary, SysBase move.l d0,_D0SBase set up SysBase variable library name start in a1 any version will do macro (see text for details) store returned value

In a real program we would of course need to check that the returned library base was valid and the easiest way to do that is to check the zero flag after the library base (which comes back in register dO) has been moved to the _DOSBase variable. If the library open was successful we can then use InputO and OutputO to identify the I/O handles. For example, we can collect the output handle like this: CALLSYS Output,_D0SBase get default output handle move.l dO,_stdout store output handle

Again in a complete program it is necessary to check the returned dO value.

Writing text messages back at the CLI/Shell is obviously a useful thing for a program to be able to do. Luckily it is an easy task because once a file handle is available there is a general DOS function, called WriteO, which can be used to do the job.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: WriteO Write data to a file length_written = Write(file, buffer_p, datajength) DO D1 D2 D3 file - file handle buffer_p - pointer to buffer holding the data datajength - length of the data length_written - number of bytes actually written A length_written value of-1 will indicate an error.

The above WriteO function is not incidentally just for writing text messages. It is a general function used to write bytes of data to any DOS file. Having said that, if you use _stdout as the file handle and the user hasn’t redirected the output using DOS’s > operator, then DOS will indeed write the data back at the CLI/Shell window.

You’ll see from the above description of WriteO that the function needs to know how much data is being written. This means that to use WriteO to send text messages to the CLI/Shell window you’ll need to know how long each text string is. Static program text is usually set up using define byte (dc.b) assembler directives like this:

message dc.b ‘test text'

One way to work out the number of characters is to actually count them and in the above example this is easy enough to do. With larger pieces of text this approach obviously becomes tedious and error prone and there is in fact a far better way of doing the job -you place an additional label at the end of the text and then use the EQUate directive to set it to a value based on the current assembler location counter value minus the start of the original string, like this:

message dc.b 'test text' messageSIZEOF EQU ‘-message

The result is that the assembler automatically sets the second label to the size of the preceding string. 1 adopt a convention whereby the sizes of all message strings are represented by a label formed by taking the original string label and adding _SIZEOF to it. Why? It’s because it is then possible to create a macro that, given the string label, can form the size label automatically. Since WriteO uses registers dl-d3 it is useful to preserve those registers on the stack before loading them with the data needed by the DOS call. The following macro does this, sets up dl-d3 as indicated earlier (note how my _SIZEOF convention is used to put a string size in dO), makes the DOS call, and then finally reinstates the contents of registers d 1 -d3:

WRITEDOS MACRO movem.1 d1-d3,-(sp) preserve registers d1-d3 move.1 \ 2, d 1 DOS output file handle move.1 #\1,d2 start of message move.1 #\1_SIZE0F,d3 size of message CALLSYS Write,DOSBase DOS call to write message movem.1 ENDM (sp)+,d1-d3 restore registers d1-d3

With this macro available the assembler programmer can create the necessary code by writing this type of statement:

WRITEDOS <text_label>,<dos_handle>

In the above text message example the line needed is:

WRITEDOS message, _stdout

which gets expanded to this type of code:

movem.1 d1-d3,-(sp) preserve registers d1-d3 move.1 _stdout,d1 DOS output file handle move.1 #message,d2 start of message move.1 #message_SIZEOF, d3 size of message CALLSYS Write,DOSBase DOS call to write message movem. 1 (sp)+,d1-d3 restore registers d1-d3

Obviously the CALLSYS macro gets expanded in a similar fashion with CALLSYS itself causing the _LVO prefix to be added to the Write label and generating a further reference to the system LINKLIB macro.

movem.l d1-d3,-(sp) preserve registers d1-d3 move.l _stdout,d1 DOS output file handle move.1 #message,d2 start of message move.l #message_SIZEOF,d3 size of message L1NKLIB _LVOWrite,_DOSBase DOS call to write message movem.l (sp)+,d1-d3 restore registers d1-d3

LINKLIB is of course also expanded so the final code produced by the assembler looks like this:

movem.l d1-d3,-(sp) preserve registers d1-d3 move.l _stdout,d1 DOS output file handle move.l #message,d2 start of message move.l #message_SIZE0F,d3 size of message move.l a6, -(sp) preserve contents of a6 move.l DOSBase, a6 base address of library jsr _LV0Write(a6) indirect subroutine call move.l (sp),a6 restore a6 movem.l (sp),d1-d3 restore registers d1-d3

Be quite clear of the advantages of this macro orientated approach. Three generally useful macros have allowed us to create all of the above code by simply writing:

WRITEDOS message, _stdout

Already the macros are doing a good job of hiding the somewhat messy details of the function calls. In effect they are allowing us to write 68000 assembler code at a much higher level than would otherwise have been possible!

If we take our macro definitions, define space for some variables, and include the appropriate header files it’s possible to create a short program which puts all of the ideas we’ve been talking about together. The following example opens the DOS library, sets up _stdout, and then prints a message on the screen:

The format of the library calls should be familiar from earlier chapters and you should note that not only have any calls that could fail been checked but that the program takes the appropriate actions if things go wrong. If, for example, the OutputO function fails then the program branches directly to the section which closes the DOS library. In other words it does not attempt to output a message.

You’ll notice that space for the programs variables, _stdout,_SysBase etc, have been created using the assembler’s define storage (ds.l) directives and on seeing the directive:

_stdout ds.l 1

the assembler will set aside four bytes of uninitialised memory. When long word (or word) values are specified the assembler will ensure that the location is word-aligned (to prevent addressing errors when the program is run). What happens at the assembly stage of course is that, on seeing such a directive, the assembler simple adds 4 (or 5 if the location needs padding) to its location counter.

You may, incidentally, be wondering why a clr.l dO instruction occurs just before the end of the program. It’s because although Amiga programs terminate via a simple return from subroutine (rts) instruction AmigaDOS, by convention, expects to see either a zero or an AmigaDOS error code in register dO. Nothing serious will happen of you don’t do this but given the system rules it is best to stick to them!.

The next program extends the ideas we’ve been discussing to the printing of several text strings:

I mentioned earlier that when a CLI/Shell program starts, the registers aO and dO contain the start address of the command line and its length. The following example starts by collecting this info and storing it in two variables (which I’ve called cli_args_p and cli_args_size). Having done that, it continues as per the earlier example by printing some text using DOS’s WriteO function. The difference however in this program is that it is not a static text string that is being printed - we print the arguments supplied on the command line when the program was started. The main purpose of the example is to illustrate how user supplied arguments can be collected but, by way of a simple loop illustration, I’ve actually arranged to print the command line as many times as there are characters, removing the last character each time a line is printed. If, for example, the user types ThisIsMyTest the program will respond by displaying:

ThisIsMyTest ThisIsMyTes ThisIsMyTe ThisIsMyT ThisIsMy ThisIsM Thisls ThisI This Thi Th T

Here’s the code that shows how it is done:

Note: Because the WRITEDOS macro is not designed to handle messages whose lengths are not defined by a _SIZEOF label, the DOS WriteO function call had to be set up manually!

One alternative to using the DOS based WriteO function directly can be found in the amiga.lib linker library. There is a high-level routine called printfO, styled on the C function of the same name (see Appendix A for details) which allows you to both print and specify the format of text and numbers (decimal and hexadecimal).

Linker libraries, as explained earlier, are a collection of routines and data that can be used by your program. When using routines which are external to the source code that you are actually writing it is necessary to tell the assembler that some of the routine references that it will find in the program will not actually be found in the source itself, but the reference will be resolved (ie the routine in question will be found) later, namely at the time the program is linked.

To do this we use the assembler’s XREF pseudo-op. So to declare the printO function, which to the assembler programmer is the reference to a routine called _printf, we use this statement:

XREF printf

Having created a program with such a definition we ask the assembler to create linkable code. By convention the assembler will usually create a file with a ‘.o’ filename extension to signify an object code module. Once the object code module is available it can be linked.

If the source file is called ExampleCH12-4.s then the assembler will create an object code file called ExampleCH12-4.o, and to link this with the amiga.lib library you would use this sort of command line:

blink ExampleCH12-4.o to ExampleCH12-4 library amiga.lib

It may be necessary, depending on your assembler/tool environment to add filepaths to tell blink where the files and libraries are. If, for example, your program files are in Ram and the amiga.lib library is in a dfO: directory called LIB then you would use a blink command line which looked like this:

blink ram:ExampleCH12-4.o to ram:ExampleCHI2-4 library dfO’.LIB/amiga. lib

Either way the result, at the end of the day, is that blink will take the specified object code file, add the necessary library code, and produce a runable (executable) program.

As far as the source code is concerned however there is a little more to using the printfO routine than just telling the linker where it is. The amiga.lib printfO function has its own special needs and amongst them comes access to a valid stdout handle - in other words printfO will need to know where the output should be sent. In fact, unless the linker can see the _stdout label in your program, the link operation will fail.

This is where another assembler pseudo-op, called XDEF, comes in handy. XDEF ensures that labels are visible to the linker and to make _stdout available in this fashion we’d write:

XDEF _stdout

Many of the routines present in amiga.lib expect to have access to library bases and so these also frequently need to be XDEF’s. To make the DOS library base, known conventionally as _DOSBase, externally visible, we would therefore use this statement:

XDEF DOSBase

Unfortunately there is a big difference between the Amiga’s runtime libraries, such as the exec and DOS libraries, and the amiga.lib linker library as far as both use and the way that the library routines expect to be given their data. The parameter passing conventions of the run-time library routines, as we have already seen, are register based - the data required for the routines are placed into appropriate 68000 registers prior to using the function.

The amiga.lib routines have been written to use a C style convention whereby any data that must be passed to the function is passed on the stack. For obvious reasons this approach is called stack-based parameter passing and the snag, as far as the newcomer to assembler programming is concerned, is that it is necessary to know how to do this before the routines can be used.

Luckily the basic outline is reasonably simple. Place any required parameters onto the 68000’s stack, perform a normal jsr (or perhaps bsr) type subroutine call, then adjust the stack pointer so that it points to the position specified before the parameters were pushed onto it. in effect this latter adjustment serves the same purpose as pulling the parameters off the stack, but the single numerical adjustment is quicker.

From C, the printfO function takes this form:

printf(format_string, arg1, arg2,…​. argN);

and (as you’ll see in Appendix A) text strings are specified by pointers representing the addresses of their first bytes. To print a single text string you would therefore use this type of call: printf(format_string, text_string);

The format string can incidentally be quite complex but for our immediate purposes all you need to be aware of is the fact that the format string for printing a single text string followed by a line-feed is:

dc.b '%s ',LF, NULL

This tells the printfO function to expect a string pointer. The terminal NULL incidentally is, as mentioned before, a C-style way of indicating the end of the string.

C function call conventions result in parameters being pushed onto the stack in a right to left order. For the printfO function call illustrated above, this means that the part of the stack that we are interested in ends up looking like Figure 12.1.

Figure 12.1. The Stack for the print(f) function call.

This situation is exactly what our program must provide before we can use the amiga.lib printfO function. To achieve it we therefore need to push firstly the address of the text string, and then secondly the address of the format string, onto the stack. There is in fact a special instruction for pushing the address of a specified operand onto the stack - it is called a push effective address (pea) instruction and for pushing the address of a labelled memory location it can be used like this:

pea text_string pea format_string

The pea instruction can be used with any 68000 addressing mode and the result is always that the address of the specified operand (not the operand itself) will be pushed onto the stack. The complete amiga.lib C style printfO function call therefore follows this type of use pattern:

pea textstring push text string address pea format_string push format string address j sr _printf make the amiga.lib call addq. 1 #8,sp adjust stack

Notice that, as mentioned earlier, it is not necessary to pull the text and format string pointers from the stack - instead we use a addq.l #8 instruction to add 8 (the numerical equivalent of two long words) to the stack pointer. This effectively adjusts the stack pointer register so that it has the same value as it had before we pushed our parameters onto the stack.

Anyway, that’s enough of such things for the moment. Now that these preliminary explanations are out of the way here is some runable example code that will illustrate the ideas I’ve been discussing:

The amiga.lib library’s printfO routine is often useful as a debugging aid because it can be used to dump the contents of specified registers back at the CLI/Shell window. The following program, ExampleCHl2-5.s, is almost identical to the previous one except that it uses printfO to print the contents of a numerical variable - namely, the contents of _SysBase, ie the base address of the exec library:

Depending on what a program needs to do it may open any number of libraries simultaneously. When lots of these system orientated operations are being done it is however necessary to be careful about the order in w’hich particular operations are done, and in fact whether certain things are done at all! As far as opening/closing and other system allocate/deallocate issues are concerned, the safest rule of thumb is to always arrange to close things down in the reverse order to that used during program start-up.

Even with small programs, such as those we are discussing in this chapter, some care is needed. The next example deals with the opening of two libraries and I’ve used a number of test and conditional branch instructions to create the type of control structure in Figure 12.2.

Figure 12.2. Control structure utilising test and conditional branch instructions.

The example itself, since I’ve chosen to use the amiga.lib printfO function, is another that will require you (assuming that your assembler gives you a choice) to create linkable, as opposed to directly executable code. Most of the detail should be familiar from earlier examples and, as you’ll see from the source code, nothing much happens once the libraries are open - in fact all we do is just close them again. There is however a purpose behind this apparent madness and, as you’ll see later, it concerns shortcomings in the continued use of the do it or branch over it philosophy. For the moment though here is the program that the above pseudo-code sketch in Figure 12.2. represents:

Obviously in real, ie larger, Amiga programs many more things need to be done and to illustrate what I consider to be a rather important shortcoming of a lot of assembler code the next program adds a few more things to do to the framework used by the example CH12-5.S program just given. The mathtrans library, which is a library used to provide pre-written transcendental maths functions such as sin, cos, exp and so on is opened. Strictly speaking the normal mathffp library does not need to be open in order to use the mathtrans library because when the mathtrans library does need to use mathffp facilities it will open the mathffp library itself. If however you wish to use mathffp and mathtrans facilities together you should explicitly open both libraries for your own use. In the examples which follow I’ve opened both libraries just to illustrate how it’s done and secondly to give a little flexibility should you wish to use these programs to experiment, with either mathffp functions or additional mathtrans functions.

During the course of the program two new amiga.lib functions are used which allow string representations of numbers, ie numbers stored as the equivalent ASCII strings, to be converted to Motorola fast floating point (ffp) form and back again. These ffp number representations are long word (ie 32 bit) arrangements which have been designed to represent floating point numbers in a way that simplifies many mathematical operations. They consist of a 24 bit mantissa (shown as Ms in the following sketch), an exponent sign bit (S), and a seven bit exponent (E) arranged like this:

bit 31 24 23 16 15 8 7 0 MMMMMMMM MMMMMMMM MMMMMMMM SEEEEEEE

The decimal range allowed is very roughly from plus or minus one times ten to the power plus or minus 19, ie:

( + /-) 10” <→ 10”

For full details of the ffp format you can consult the official Motorola literature but for now our only concern with the ffp format is that to use the mathtrans library’s SPExpO exponential function on a number it is necessary to have the number, in ffp form!

The amiga.lib library contains two functions which can convert a string of characters representing a number into ffp form and back again. As with the amiga.lib printfO both afp() and fpa() use stackbased parameter passing so to convert the string form of a number into ffp form it is necessary to push the start address of the string onto the stack and then make the afpO call (ie do a jsr _afp) in the same way that the printfO call was handled:

pea number push pointer jsr _afp an amiga.lib routine addq.l #4,sp adjust stack

The apf() routine delivers a result in dO and this is quite useful because the run-time mathtrans library routine SPExpO, the routine which I’ll be using to calculate the exponential of the supplied number, expects the number in register dO. Remember the run-time libraries take their parameters in registers. As with all run-time library functions our CALLSYS macro can be used so the source code for the exponential call will just be:

CALLSYS SPExp,_MathTransBase values sent/returned in dO

Now there is a snag with the exponential function, which is why I’ve used it as an example. Even though a supplied number is within the fast floating point allowed number range there is no guarantee that the result of raising e to the power of that number will be. Basically this means that SPExpO could fail and the function autodocs tell us that if this does occur the routine will return with the 68000 processor’s overflow (V) flag set!

I’ll not be doing this in the example which follows but obviously this potential for failure cannot ordinarily be ignored. For the moment though, for reasons of simplicity, I will forget about it and instead will convert the result back to ASCII string form using the amiga.lib fpa() function. After the above SPExpO call the ffp result will be in register dO so conversion just involves pushing the address of the buffer, where the ASCII converted result is going to be stored, onto the stack, then pushing the contents of dO, making the jsr call, and adjusting the stack like this:

pea result push result pointer move. 1 dO,-(sp) push ffp value j sr _f pa convert back to ASCII addq. 1 #8, sp adjust stack

Having converted our ffp number to an equivalent ASCII string we can then use the amiga.lib printO function to deliver the result back at the CLl/Shell window like this:

pea result push sum string pointer pea format_string push format string address j sr _printf use amiga.lib printf() addq. 1 #8, sp shortcut way to adjust stack

The only thing we now need to discuss is where we will get our original number from. I’ve chosen to collect it from the CLI/Shell command line and, for example purposes, I’ve decided that instead of just using it via the originally supplied aO pointer, we shall copy it to a buffer area. As you now know, when a CLI/Shell program starts register dO contains a count of the number of characters that follow the program’s name on the command line. If the user does not supply any parameters then dO will be 1 and the single character will in fact be the command line’s terminal linefeed.

It’s therefore quite easy to check whether the user has supplied a number or not by using this immediate addressing form of a cmpi instruction at the start of the program:

cmpi #1,dO

If this comparison sets the zero flag then dO equals 1 and the user hasn’t supplied any other characters. If this was the case there would be little point in the program continuing because there is no number to convert. 1 mentioned earlier that a buffer would be allocated to store the number and, since I’ll be using a static declaration (based on a ds.b declaration), this could lead to problems. Why? It’s because if a user typed in a number with more characters than I had allowed for then the operation which copied data into the buffer would fill the buffer and then write over any number of succeeding bytes (destroying their contents). On the Amiga this could even mean that memory belonging to another program is destroyed!

It should then be very obvious that we mustn’t allow this to happen and so, if the user has indeed supplied some data, we’ll need to check its length to see that it will fit into the buffer. A cmpi comparison instruction, followed by a branch on greater than (bgt) conditional branch will do the job nicely and in the next example you’ll see this type of test:

cmpi #number_SIZEOF,dO bgt EXIT line too long so quit!

You’ll notice that I’ve used the same SIZEOF naming convention on the buffer as I did with text strings in earlier programs and providing the command line has data which fits the buffer we are, at last, able to safely copy the command line data. The following fragment uses the 68000’s powerful indirect addressing with autoincrement addressing scheme in conjunction with an automated decrease and branch always (dbra) instruction. In the following fragment the address of the number buffer is loaded into register al and the count present in dO, after having 2 subtracted so that the terminal command line line-feed is ignored, is used as the loop control register. Remember that all automated dbcc type instructions exit when the countdown value reaches -1 and so to copy X characters you’d need to set the loop control register to X-l. In this example I want to disregard the last character hence I set it to dO-2 rather than dO-1! After the command line data has been copied we have to place a terminal NULL character at the end of the string because the documentation tells us that this is what the amiga.lib string <→ ffp conversion routines expect. Now that the explanations are out of the way, here is the loop which performs the command line copy operation:

lea subq LOOP move.b dbra move.b number,a1 #2, dO (a0),(a1) dO,LOOP #NULL,(a1) destination pointer disregard terminator copy string NULL terminate string

and if we put that together with the preliminary command line existence and size checks we get this sort of framework:

cmpi beq cmpi bgt lea subq LOOP move.b dbra move.b #1,d0 check for data? EXIT no data so quit! #number_SIZEOF, dO EXIT number,a1 #2, dO (a0),(a1) do,LOOP #NULL,(a1) line too long so quit! destination pointer disregard terminaton copy string NULL terminate string

and when this is added to a program based on the library opening/closing and usage scheme used in earlier programs we finally end up with our program, ExampleCHl 2-7.s, which when given a number on the command line in this fashion:

program name <some number>

will print the exponential of the number.

On disk the program has been called ExampleCH12-7 and so if, for example, the user types:

ExampleCH12-7 1.001243 the program will print the value e je 2.72!

What I’d like you to do as you study the following source code is to pay attention to the increasing number of conditional branches that are needed to make sure that pieces of code get executed, or not executed, as required:

You’ll see from the previous listing that the example CH12-7 program has a number of identifiable jobs to do, namely:

Quite a number of these jobs can fail because of libraries not opening and this is especially true of the mathtrans library because this is one of the run-time libraries that resides on disk. A lot of checks have been made within example CH12-7 but more are needed because, as mentioned, it is possible that the user will provide a number, such as 99.18, whose exponential is too great to be expressed in ffp form. In this latter case the SPExpO routine would fail and although this would not cause any system damage the result, if used, would be meaningless!

Now to be honest it is possible to add more checks and continue program development along the lines that we have been doing, adding more branches to cater for the various control flow possibilities as they are required. The trouble is though that this type of development gets increasingly difficult as programs get larger. The solutions are three-fold. Firstly, it helps to isolate particular, well defined, jobs as subroutines. Secondly, it helps if you can work with the types of high-level 1F-THEN_ELSE, DO-WHILE, and CASE type control structures that high-level languages offer. Thirdly, it turns out that it also helps to be able to adopt the same type of nested subroutine schemes that were mentioned in Chapter 5 being able, for example, to use code equivalent to this BASIC style construct:

IF (x) THEN GOSUB XXXX ELSE GOSUB YYYY

Unfortunately the 68000 itself does not provide conditional subroutine calls, ie instructions which only perform a subroutine call when certain flag conditions are met. Having said that, all is not lost because it is possible to create them quite easily. To see how it’s done it is necessary to understand what happens when a jump to subroutine type (jsr or bsr) instruction is executed. When we reach a part in a program represented for example by:

jsr SomeRoutine HERE: next instruction /\/\/\/\/ SomeRoutine instructions /\/\/\/\/ rts end of subroutine

On encountering the jsr instruction the processor will push the address of the NEXT instruction (labelled HERE in this example) onto the stack. Having done that, control passes to the subroutine that I’ve called SomeRoutine. When this routine terminates the rts instruction tells the processor to pull an address from the stack and place it in the 68000’s program counter register. When this happens with the above example the address labelled HERE gets jammed into the program counter and the processor immediately continues execution from that point, which is of course the instruction immediately after the original subroutine call.

This little scenario tells us exactly what we need to do to create our own conditional subroutine calls. We must:

This is actually a piece of code which tries to open the mathtrans library and, depending on whether the open library call is successful, a subroutine call to TRANS_OPEN may, or may not, be generated. It works like this. Firstly a push effective address (pea) instruction is used to place a return address (MATHS_OPENl) on the stack. The next instruction is a normal subroutine call designed so that success/failure is indicated by the setting, or clearing, of the 68000’s zero flag. As this information is received the beq specified branch is either taken or ignored. The result is that the TRANS_OPEN subroutine call is only taken if the OpenTrans routine was successful! When the routine labelled TRANS_OPEN terminates, via a rts instruction, the MATHS_OPENl label address is pulled from the stack and execution therefore continues from the MATHS_OPENl (jsr CloseMaths) position.

Now at first reading this might seem like a rather convoluted way of doing this, but it turns out to be very powerful because it allows us to program control structures in a way which is similar to a high-level language. The benefits are that if you are able to sketch out a program structure using pseudo-code, Warnier diagrams or some similar high-level design technique, then the nested conditional control structure approach will let you mirror that high-level design sketch very easily indeed. In Figure 12.3. and 12.4. there are a couple of the diagrams which I used to sketch out the basic needs of the last program.

Figure 12.3. tells us that we must only try to get stdout if the DOS opened successfully and that we only need open the maths library if a valid stdout handle is available (couldn’t print results otherwise). More detail can be given for the bracket labelled Maths open OK and of course my interest at this point revolved around adding those overflow issues that were ignored in the previous program. Figure 12.4. is an expansion of the relevant part of the Figure 12.3.

The reason I’ve given these design sketches, and I ought to mention that I’ve not by any means provided full details of the design pathway, is to let you compare the bracket subsets with the nested subroutines that are present in the 68000 code of Example 12.8. You’ll see from the code which follows that I have coded most of the diagram brackets as subroutines using my conditional subroutine call creation approach. I’ve also adopted a convention whereby different faults are represented by error numbers. When an error occurs an appropriate number gets stored in a special location (which I’ve called error_flag) and at the end of the program this value is used to print a message.

You’ll notice some other changes in the code explanations of which follow. 1 have now isolated the library opening and closing code into separate subroutines and, in the case of the library opening routines I use the zero flag as a success/failure indicator. No checks are made on the close library routines and there is a good reason for this - in this next example, and indeed in all of the examples that I’ve dealt with, you’ll find that the library closing code is only ever executed if the library was successfully opened in the first place. Fience, the library closing routines will never fail and so do not need to be checked!

Figure 12.3. Warnier sketch of some of the things which program CHI 2-7 has to do.

Figure 12.4. These constraints show what should really be done if a number causes an overflow.

As a last aside, before providing the complete source, 1 need to mention the routine which prints error messages. Again I’ve isolated the code into a subroutine but I’ve used a table-orientated trick, based on the 68000’s very useful indexed indirect addressing with displacement addressing scheme, which allows me to print appropriate text strings even though the program’s internal error handling is done via error numbers.

This is how it works. Within the program a number of error type EQUates are defined:

NOERRORS EQU 0 NO_ARGUMENTS EQU 1 LONG_ARGUMENTS EQU 2 N0_MATHS EQU 3 N0_TRANS EQU 4 OVERFLOW EQU 5

At the end of the program a list of text strings corresponding to those errors are also defined:

errorO dc.b 'no errors',NULL errorl dc.b 'no value supplied',NULL error2 dc.b ‘command string too long',NULL error3 dc.b ‘could not open maths library 1,NULL error4 dc.b 'could not open mathtrans library',NULL error5 dc.b 'result produced an overflow',NULL

In addition to this a table is set up containing a dc.l directive that specifies those string addresses like this:

error_table dc.l errorO,errorl,error2,error3,error4,errors

The error message routine has to convert the numbers 0,1,2 etc, into the appropriate error messages and here’s how it can be done. I clear register dO and copy the error number to it. Shifting this value two places to the left effectively multiplies the value in dO by four (try writing out some examples if you don’t believe it) and this results in dO holding offsets of either 0, 4, 8, 12, 16 or 20. If you think about the address of the error_table label and the four byte values which the assembler will generate references for, you’ll see that error_table + 0, error_table + 4,error_table + 8, error_table + 12, error_table + 16 and error_table + 20, will in fact give the addresses of the six table entries and these locations hold the addresses of the error message text strings.

What is needed, given the base address that we’ve called error_table, is some way of adding the offset that we’ve calculated (by shifting the error number) to the base address and using that value as the address from which we get an operand. This is exactly what the 68000’s indexed indirect addressing with displacement allows us to do because it lets us create an address by adding an index value, which may be stored in an address or data register, and a fixed displacement, to a base address stored in another address register. Using this addressing mode allows us, given N an error number, to retrieve the address of the corresponding N’th string.In fact the instruction:

move.l 0(a0, dO•1), -(sp)

allows us to retrieve it and push it onto the stack so it is just what is needed for the amiga.lib printfO call. Here then is the complete error message printing subroutine:

ErrorMsg clr.l dO could contain garbage! move.b error_flag,dO get error number lsl.l ro Q. O multiply by 4 move.1 #error_table, aO load table base address move. 1 0(aO,dO.1),-(sp) push table entry contents pea string_format push format string jsr _printf print error message add.l #8,sp adjust stack rts

and to finish this chapter here’s the complete source code that illustrates, within the context of a runable program, the conditional subroutine call approach that I’ve been talking about:

I’ve covered quite a bit of ground in this chapter but by now some things should be becoming clear. For a start you should now be appreciating the usefulness of understandable variable names, macro facilities and the adoption of standardised code layouts (plus lots of remarks). You should also now be clear about the use of, and the differences between, the register based parameter passing methods used by the Amiga’s run-time libraries, and the stack-based conventions used by amiga.lib. Along the way we’ve introduced CLl/Shell parameter collection, string copying, table access, error handling and hierarchical based nested subroutine coding techniques.

What should also now have been firmly driven home is the fact that a great many jobs which have to be done in an Amiga assembly language program are done by system library calls and this is, of course, why I have devoted a lot of time and space to these library related issues in the first place!

The message system used on the Amiga is, at the grass roots level, an Exec facility. Information can be sent from one task to another by creating a data packet known as a Message structure and then transmitting it (sending it) to its destination. Messages pass between tasks using another Exec defined structure called a MsgPort, more commonly called a message port or just a port. Ports are basically software entities whose job, amongst other things, is to act as a receiving station for messages. Before a program can receive a message it must have allocated and initialised a suitable message port. Here’s the definition of the system’s MP (message port) structure in terms of the STRUCTURE macro:

STRUCTURE MP,LN_SIZE size equivalent to an Exec Node UBYTE MP_FLAGS UBYTE MP_SIGBIT signal bit number APTR MP_SIGTASK task to be signalled STRUCT MP_MSGLIST,LH_SIZE linked list of messages LABEL MP SIZE

LN_SIZE reserves space equivalent to the size of a standard Exec Node structure and MP_MSGLIST represents an Exec list structure used to create a linked list of messages associated with the port. As new messages arrive they are added to the end of the list. As messages are read they are taken from the front (head) of the list. The MP_FLAGS field is used to indicate various message arrival actions and the MP_SIGTASK field identifies the task to be signalled as messages arrive. Bear in mind that the macro only calculates equivalent offsets but it is useful during these structure related discussions to talk about the fields that such offsets represent when the structure has been allocated and set up.

Messages themselves are based on an extensible length structure with the Exec defined fields being supplemented by additional user defined data. The structure has a system label MN and here’s the basic layout:

STRUCTURE APTR UWORD LABEL MN, LN_SIZE MN_REPLYPORT MN_LENGTH MN SIZE

size equivalent to an Exec Node message reply port message length

The Node space at the front of the resulting structure is used for port linkage. The MN_REPLYPORT field indicates which port the reply will be sent to (see discussion which follows), and the MN_LENGTH field indicates the total length of the message. The real message data is always provided as an extension, usually by defining a new structure in terms of a message plus other data as can be seen in the case of the IntuiMessage definition repeated below:

STRUCTURE IntuiMessage,0 STRUCT im_ExecMessage,MN_SIZE -*■ — basic message structure LONG im_Class subsequent fields are WORD im_Code the extensions that WORD im_Qualifier provide the real data APTR im_IAddress 1 WORD im_MouseX \ WORD im_MouseY LONG im_Seconds LONG im_Micros APTR im_IDCMPWindow APTR im_SpecialLink LABEL im SIZEOF

If, for example, you wished to create messages which just stored mouse coordinates you might define your own structure like this:

STRUCTURE MouseMessage,0 STRUCT mm_ExecMessage,MN_SIZE UWORD mm_MouseX UWORD mm_MouseY LABEL mm_SIZE0F

That explains what messages are in terms of physical blocks of memory, now let’s look at how these structures are used. If program A sends program B a message, it does so by using an Exec system call known as PutMsgO. This adds the message into a linked list of messages w’hich are tied to program B’s port structure. The important point about this process is that the message is not copied. In other words it is the memory block associated with program A’s message which is linked into the list of messages present at program B’s message port. Technically this is known as queuing by reference and its main advantage is that the very substantial overhead of creating local copies of each and every message floating around the Amiga system is avoided. In a sense then, when program A allocates, initialises and then sends program B some message, what program A is really doing is giving program B a license to use part of its memory space.

Now this is all very well but the scheme presents a number of potential difficulties. Let’s go over the program A —> program B message passing scenario once more to see what problems can occur.

Program A wants to send program B a message so it allocates some memory for a message, fills in the appropriate details and then sends the message to program B using Exec’s PutMsgO function. Program A will need to know the address of program B’s message port at this time but system calls are available for finding such information.

By the time program A’s PutMsgO call has completed we’ve developed a quite dangerous situation because program A has allocated some message memory and at some stage program A is going to have to deallocate it, ie return it to the system free memory pool. But, once the PutMsgO function has sent the message the backward and forward pointing Node fields of the memory block containing the message will have been altered so that the message is linked into program B’s messages list. If program A terminated, or decided for any other reason to deallocate its message unit, serious problems would arise. In short, program B’s message list would become corrupt and the system would no doubt guru shortly afterwards!

What is needed is a convention which eliminates this type of problem. The method that Exec has adopted is as follows. Program A, in sending a message to program B, is effectively granting a temporary license to program B to use part of its memory space (that relating to the message). Once this license has been granted, program A should not interfere with the message until it is safe to do so. How does program A know when its message can be reused or discarded? Usually program B will send the message back to program A using Exec’s ReplyMsgO function. This function links (with a suitable reply ID marker) program A’s message into program A’s message port. When program A reads this, it knows that program B has finished using its message and that it is then free to reuse that memory space as it sees fit.

From the above description you’ll realise that in most cases both of the communicating programs will need their own message ports -even when, as in the above example, the passage of real information is only going one way.

Here are the descriptions of Exec’s PutMsgO and ReplyMsgO functions mentioned above.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: Function: Description: Call Format: Registers: Arguments: Return Value: Notes: PutMsgO Send a message to a message port PutM3g(port_p, message_p); aO al port_p - pointer to a message port message_p - pointer to a message None This function can signal tasks and cause software interrupts to occur. The action is dependent on the flags set in the MP_FLAGS field of the destination port (see RKM manuals for further details). ReplyMsgO Send a message back to its reply port Reply Msg(message_p); al messagej? - pointer to a message None This function is a bit like PutMsgO in that it links the message into a message port. To indicate that it is a reply however this function places the NT_REPLYMSG flag into the message’s ln_Type field. More details can be found in the RKM system manuals. Another function that is related to the above is the Exec GetMsgO function.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: GetMsgO Collect first message queued at message port message_p=GetMsg(port _p); dO aO port_p - pointer to a message port message_p - pointer to a message This function does not wait. If a message is not available it will return with a NULL value.

GetMsgO unlinks the first message from the port and after it has been used the associated message is essentially free floating, ie it is not pointer-link tied into the message chain of the port it came from. Now, if we add these details to the steps which occur as two programs communicate, we end up with this scheme:

Program A Program B

1: Allocates memory for message 2: Fills in details 3: Sends Message using PutMsg() 4: Collects message using GetMsg() 5: Extracts data from message 6: Sends back message using ReplyMsg() 7: Receives reply using GetMsg() 8: Reuses/deallocates message

In Chapter 15 we are going to be communicating with Intuition and in terms of the above scenario Intuition is going to be program A and our applications examples, which will be carrying out actions 4, 5 and 6 above, are going to represent the actions of program B.

It’s all very well saying that one program collects the message that another program sends but that still doesn’t tell us how one program knows that another program has sent it a message. As might be expected, Exec also solves this problem very elegantly by adopting an inter-task signalling system.

For each task Exec allocates 32 bits for use as signal bits. Sixteen are used by Exec itself and 16 are available for use by the task in question. In most cases you will rarely need to worry about how these bits are allocated because both Intuition calls and amiga.lib calls such as CreatePortO handle the nitty gritty details for you (you can find the details in the RKM manuals).

What you will need to do however is to work out what signal bit is being used because there is an Exec function called Wait() available which allows you to put your program to sleep until specific signals are received.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: WaitO Wait for one or more signals signals=Wait (signal_mask); dO dO signal_mask - 32 bit mask of signals to wait for signals which caused the WaitO to be satisfied

This is generally useful because it allows signals from different sources to be combined.

The important point with WaitO is that it uses a 32 bit mask value, not the 8 bit signal bit number as stored in the MsgPort structure. The difference between the two representations is easily seen by looking at an example:

bit 16 This is the mask ki arrangement needed t if MP_SIGBIT = 16 00000000 00000001 00000000 00000000

To convert the MP_SIGBIT value to a mask we simply leftshift the number 1 an appropriate number of times, namely MP_SIGBIT times and you’ll see an example of this type of mask creation in Chapter 15.

Now, how does all this Exec stuff fit into the job we want to do, namely communicating with Intuition? Well, as mentioned earlier the easiest way to gain access to an IDCMP is to specify one or more of the IDCMP flags when you open a window. If Intuition sees that you’ve done this it will automatically create a pair of message ports for that window. One port, the Window Port, is used by Intuition. The other, referred to as the User Port, is for the program’s use and the Intuition programmer needs to know the address of this port in order to collect messages from it. Fortunately this is simply a matter of looking into the Window structure and picking up the appropriate pointer.

Suppose that you have a system close gadget present in a window display and that you want this gadget to control the closedown operations that the program must perform. The window will have originally been opened by setting up a NewWindow structure with the CLOSEWINDOW flag set in the IDCMP flags field and so Intuition will provide the program with this class of messages. Take what is said about windows and flags at face value for the moment and concentrate only on the ideas concerning the message passing aspects.

I’ve already mentioned Exec’s WaitO function which allows a program to sleep until a message from any one of a number of specified ports wakes it up. Often though you’ll only have one port to look at and there is in fact a simpler function, called WaitPortO, available for use.

WaitPoitO Suspend program execution until port becomes nonempty message_p=WaitPort(port_p); dO aO port_p - a pointer to a message port message_p - a pointer to first message at the port When this call returns it means that one or more messages have arrived at the port. In most cases it is not necessary to collect the WaitPortO return value because a separate function, called GetMsgO, can subsequently be used to both identify and remove the message from the message port. Parts of the RKM official documentation seem to suggest that this function can return without a valid message address!

Waiting for messages to arrive may sound like a complicated process, and underneath the surface it is reasonably complex, but for the Intuition user all that is needed in order to wait for an IntuiMessage is a line of code which looks like this:

CALLSYS WaitPort,_SysBase

When the code generated by this macro is executed the program goes to sleep, ie becomes inactive, until an event occurs which results in a message being sent to the window’s UserPort. When this situation occurs the program needs to do several things:

My concern at the moment is to explain how to write the parts of a program which can handle the arrival of these messages and there is something which needs to be emphasised at this point: The signal that a message has arrived (which terminates the program’s sleeping state) actually means that one or more messages have arrived. This being so, any loop arrangements used must be able to handle, or at least reply to, each and every message that comes along and it’s this topic which provides the subject matter for the rest of this chapter.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes:

To finish this chapter I want to create a subroutine that will monitor an 1DCMP message stream and tell me when the user has hit a window’s Close Window gadget. Essentially this means writing a WaitForExitMessageO routine and a good first step is to think about what the program is going to have to do.

Firstly we’ll need to put the program to sleep until a message arrives. When the program comes to life again it must collect the message/s that caused the wake up signal. In the following fragment I simply assume that this can be done, that the routine will be able to determine that a CLOSEWINDOW message has been received, and that on finding such a message it will set an exit Pag. Codewise I just insert a jsr GetMessage reference having made a mental note to write the code later on.

I was able to sketch the above ideas quite easily using a sort of 68000 pseudocode, ie 68000 code plus comments for the details about things 1 wasn’t completely sure about yet. Here’s the result:

Clear exit flag WaitForExitMessage Set registers up for a WaitPort() call CALLSYS WaitPort,_SysBase jsr GetMessage Examine the exit flag to see if it has been set bne WaitForExitMessage rts

The routine needs to be able to check the exit flag to see if the user is ready to quit. My choice was to use register d2 as an exit flag because, being one of the designated non-scratch registers this meant that I was not going to have to worry about the system destroying its contents during the execution of a library function. Note: According to the Amiga’s system documentation, the contents of registers aO/al and dO/dl must be regarded as lost after a function call unless otherwise stated.

As far as the collecting of a message is concerned we’ll need to try to get the message and, having checked that it really did exist, look to see if it is a CLOSEWINDOW class intuimessage. If it is, the exit flag must be set. If it isn’t, the exit flag is left alone (ie kept clear). What 1 must ensure however is that 1 reply to all messages that are received. This can be done using Exec’s ReplyMsgO function and since a wake up signal can mean that one or more messages have arrived at the port I’ve also got to loop repeatedly until all messages have been handled. Again it’s not too difficult to produce a 68000 style sketch of the code and, bearing in mind that indirect addressing with displacement can be used to extract class data from the intuimessage (see Chapter Nine) this was the general framework that I chose:

GetMessage Set registers up for a GetMsg() call move.l #TRUE,d2 user hit close gadget GetMessagel Set registers up for a ReplyMsg() call CALLSYS ReplyMsg,_SysBase

Now comes the good news: If you put the above two fragments together, you’ll see that the foundations are in place for a routine which does exactly what we require. Having said that, a certain amount of tidying up is clearly needed and of course there are a few details still to be filled in concerning the setting up of the system library calls.

The WaitPortO needs to be provided with a port address in aO but I’ve decided that the main program will be expected to supply this parameter in register a2 because it will be needed throughout the routine and I wanted it in a nonscratch register. The function autodocs tell us that ReplyMsgO needs message pointers in register al. These pointers will of course be supplied to the subroutine internally as the GetMsgO function is used but obviously I’ll need to make sure that results are in the right register!

Additionally I’ve chosen to preserve all the registers that are going to be used and, bearing in mind our previous message passing scenarios, it is not too hard to produce the following code suggestion:

CALLSYS GetMsg,_SysBase get the message Check to see if the message existed beq GetMessageExit did it exist? Get message pointer in register a1 cmpi.l #CL0SEWIND0W,imClass(a1) bne GetMessagel bra GetMessageExit rts GetMessage check for more messages d2 holds exit flag clr.l WaitForExitMessage2 move.l CALLSYS jsr cmpi.l bne movem.l rts GetMessage move.l CALLSYS tst.l beq move.l cmpi.l bne move.l GetMessagel CALLSYS bra GetMessageExit rts dO-d2/aO-a2,(sp) preserve registers d2 clear exit flag a2,a0 port address WaitPort,_SysBase GetMessage #TRUE,d2 exit flag set? WaitForExitMessage2 (sp)+,d0-d2/a0-a2 restore registers logical end of routine a2,a0 get port address in aO GetMsg,_SysBase get the message dO GetMessageExit did it exist? d0,a1 copy pointer to a1 #CL0SEWIND0W,im_Class(a1) GetMessagel #TRUE,d2 user hit close gadget ReplyMsg,_SysBase GetMessage check for more messages d2 holds exit flag

You’ll also see that within the GetMessage subroutine 1 move the returned GetMsgO value (which comes back in dO) to register al. This serves two purposes. Firstly, it allows me to use al as the base for structure accessing using indirect addressing with displacement. Secondly, register al is automatically set up for the ReplyMsgO call (function needs the message address in al). Remember that when moving to an address register the move instruction is actually a movea instruction which does not set the status flags - because of this a tst.l instruction is needed before the status byte flags truly represent the state of the value which the GetMsgO function returns in dO.

If we add a bit of internal documentation to the above code it’s possible to produce a quite useful IDCMP orientated subroutine. Here’s the final result:

We’ve now produced a typical utility routine which may be used by a programmer without them knowing any more than these details.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: WaitForExitMsgO Wait until user sends CLOSEWINDOW message to port WaitForExitMsg(port_p); a2 port_p - pointer to a window’s IDCMP user port None This routine can be used with any Intuition window that has been provided with a close gadget and which generates CLOSEWINDOW messages.

The routine is actually a very simple form of an IDCMP event handler and although it ignores all messages except those of class CLOSEWINDOW it can actually be expanded quite easily. To a certain extent however the sophistication, or otherwise, of the routine is neither here nor there - what is important is that we’ve encapsulated quite a complex set of operations in a black box type routine that can then be used without knowing how it works and this is quite a good example of the benefits of the information hiding approach that I discussed earlier in the book.

Before we can write an IDCMP example program we need to know how to open a window, and this of course means that some more preliminary Intuition material needs to be provided.

Amiga programs may open one or more windows in a screen and the method of doing this has much in common with the opening of screens themselves, some details of which were given in Chapter 8, and is based on the creation of a fairly complex structure known as a Window structure. Intuition provides help in this area by allowing windows structures to be created from a much simpler NewWindow structure. A program has therefore only to provide the bare minimum of window detail in this structure before using a call to the OpenWindowQ Intuition routine which handles the more complicated setting up details. Again the important thing at the Intuition level is to know a little about the fields present in the NewWindow structure. Before looking at this structure it is useful to know a little about the Intuition window attributes which are under the control of the programmer.

Intuition provides a number of different window types. Borderless windows, as the name suggests, are drawn without the default edging, although they can be given edges if title bars or system gadgets have been specified. To get a borderless window you set the BORDERLESS flag in the NewWindow structure. GimmeZeroZero windows contain extra bitplanes which hold the window title, system gadgets and borders and these allow the program to draw freely over the inner surface of the window without trashing the graphics drawn by the system. Backdrop windows are opened behind normal windows and no amount of depth arranging will ever send a non-backdrop window behind a backdrop one. Perhaps surprisingly these windows are very useful and many programs open screen-sized borderless backdrop windows as a means of creating a full screen size display area which has Intuition window communications facilities. Another window type you’ll read about in the Intuition manuals is the SuperBitMap window, which is used to display portions of a user supplied bitmap display.

Whether Workbench or custom screens are used all windows opening in a particular screen will inherit from that screen the definition of the colour palette to be used and the horizontal/vertical pixel resolution.

Two types of window gadgets are supported: User defined gadgets and system gadgets. System gadgets include the drag bar which allows users to move a window around, two depth arrangement gadgets which let users move windows in front of or behind other windows, and a sizing gadget which allows the user to close a window. Most of the movement/size window operations which the user may perform will be handled transparently by Intuition although there are occasions where Intuition might supply, or be asked to supply, a message to indicate some particular user action.

One special case, which is relevant to the code that we have developed so far in this chapter, is the closing of a window. Intuition will never close a window automatically - instead when the user hits the close gadget Intuition sends the program a message telling it what has been done and then leaves the actual shutdown operations to the program itself!

Intuition offers a number of different window redrawing schemes. With Simple Refresh Intuition leaves most of the redrawing of overlapped areas to the program itself. Smart Refresh buffers offscreen portions and general window status to provide faster refresh operations, at the expense of using more memory. There’s also a method called SuperBitMap redrawing and this maintains a completely separate window bitmap, as opposed to keeping the window contents as part of the screen display data. The benefit here is that the applications program never has to worry about redrawing window information because the window display is always available for use by Intuitions redrawing operations.

Right, we’ve dealt with some of the options which Intuition provides. Now let’s look at the details of the NewWindow structure used to pass window specifications to Intuition. Here’s the structure itself:

STRUCTURE NewWindow,0 WORD nwLeftEdge WORD nw_TopEdge WORD nwWidth WORD nw_Height BYTE nwDetailPen BYTE nw_BlockPen LONG nwIDCMPFlags LONG nwFlags APTR nw_FirstGadget APTR nwCheckMark APTR nwTitle APTR nwScreen APTR nwBitMap WORD nw_MinWidth WORD nw_MinHeight WORD nwMaxWidth WORD nwMaxHeight WORD nw_ Type; LABEL nwSIZE

The header files predefine a great many flags which are used to specify the various options. Here are the field details and allowed flag definitions:

IDCMP flags title text for window

nw_LeftEdge

The initial x position of the window’s top left corner.

nw_RightEdge

The initial y position of the window’s top left corner.

nw_DetailPen

Similar function to the equivalent NewScreen field but if set to -1 the window will actually use the pens specified in the associated screen structure.

nw_BlockPen

Ditto DetailPen.

nw_IDCMPFlags

These, as already mentioned, are concerned with the specification of Intuition communications.

nw_Flags

These window flags fall into four categories:

System gadgets: You use these flags tell Intuition which system gadgets are needed in the window:

WINDOWSIZING Asks for a sizing gadget

WINDOWDEPTH Asks for depth arrangement gadgets

WINDOWCLOSE Asks for close gadget

WINDOWDRAG Asks for a drag bar

Window type: Use these flags to specify additional window characteristics:

BACKDROP

BORDERLESS

GIMMEZEROZERO

Refresh method: You must set one of these flags:

SIMPLEREFRESH SMARTREFRESH SUPER BITMAP

Message flags:

REPORTMOUSE This flag tells Intuition that the window should

ACTIVATE

NOCAREREFRESH Tells Intuition not to bother sending window refresh messages RMBTRAP Used to trap potential menu operations and instead just deliver right-mouse-button messages

nwFirstGadget

APointer to the start of a linked list of user defined gadgets. nwCheckMark Pointer to an image to be used when menu items are checkmarked. Setting this field to NULL causes Intuition to use the default tick checkmark. nw_Title Pointer to window title text. nw_Screen If you have opened the window in a custom screen then this pointer should point to the screen’s associated Screen structure. nw_BitMap If using SUPER_BITMAP refresh, this field must point to a BitMap structure. nwMinWidth nw_MinHeight nw_MaxWidth nw_MaxHeight nw_Type Minimum width of window Minimum height of window Maximum width of window Maximum height of window Set to either WBENCHSCREEN or CUSTOMSCREEN

Once a NewWindow structure has been set up it is possible to use these Intuition functions to do all the hard work.

Function: Description: Call Format: Registers: Arguments: Return Value:

Function: Description: Call Format: Registers: Arguments: Return Value: OponWindowO Open an Intuition Window window_p=OpenWindow(new_window_p); dO aO new_window_p - pointer to initialised NewWindow structure window_p - pointer to an Intuition Window structure. If the window could not be opened a NULL pointer is returned. CloseWindowO Close an Intuition Window CloseWindo w(window_p); aO window_p - pointer to an existing Window structure None

By now you should have learn’t quite a bit about opening and closing libraries and getting data to and from structures using indirect addressing with displacement. Now that we’ve covered some message handling and window topics it’s possible to create a program that ties all these ideas together. The following program uses this basic plan:

Open the Intuition library Set up a NewWindow structure Open a window with close and drag gadgets Get user port address from real window structure Call the 'WaitForExitMessageO routine Close window Close library

As far as this book goes the use of messages and ports is limited to fairly straightforward examples. Things however are not always this straightforward in the messages/ports world but the flexibility and versatility of the underlying Exec options usually allows most difficulties to be tackled one way or the other. Here are two tips that may prove useful at a later stage.

Messages are queued in FIFO order regardless of importance and this can sometimes mean that a message of relatively minor importance (an INTU1TICK message for instance) could be sitting, waiting for collection, whilst a far more important message concerning a requester, window movement or a window redrawing operation, was hidden behind it. Usually the delays in handling compound message streams can be kept low but on occasion it might be necessary to open a second, separate, port just for handling messages of importance.

Another area where message passing comes in useful is in minimising interrupt code time. Suppose you have a fairly long winded job which you’d like carried out when a certain interrupt signal occurs. To avoid overburdening the interrupt system you might decide to set up a separate task to handle the actual processing and just use the interrupt code to send a message to that task effectively telling it to start processing.

if you’ve suddenly found that things have got technically tough during this chapter don’t worry too much - this material has a proven track record for causing brain damage amongst programmers and it is almost certain to be hard going if you are encountering it for the first time. To start with just try and develop a general appreciation of what is going on.

The IntuiText structure looks like this:

STRUCTURE IntuiText,0 UBYTE it_FrontPen front pen colour for drawing UBYTE it_BackPen back pen colour for drawing UBYTE it_DrawMode Intuition 'drawmode' UBYTE it_KludgeF11100 for word alignment WORD it_LeftEdge WORD it_TopEdge APTR it_ITextFont font to be used APTR it_IText pointer to null terminated text APTR it_NextText next IntuiText structure LABEL it SIZEOF

As can be seen from the above description, the IntuiText structure allows the position, drawing mode, colour and font style of the text to be specified. Here are some more details of the associated structure fields:

it_FrontPen and it_BackPen are colour register numbers.

it_DrawMode may be set to one of four flag values.

RPJAM1 Front pen is used for rendering the text string.

RPJAM2 Front pen is used for rendering the text string and the back pen is used for the background.

RP_COMPLEMENT String is drawn in the complement of the background colour.

RPJNVERSID With this flag set, the background is filled with the front pen colour.

it_LeftEdge/it_TopEdge specify the position (as pixel offsets) of the start of the string relative to the top-left of the display.

it_TextFont can be used to specify a font. If this field is set to NULL then the default font will be used.

it_IText is a pointer to the text string itself. The normal C style convention is followed, ie the string should be null terminated.

it_NextText is a pointer field which allows IntuiText structures to be linked together. It is very useful because it allows whole chains of such structures to be displayed using just one PrintlTextO call. The field should be set to NULL for IntuiText structures which are the last (or the only) structure in such a chain.

Using an IntuiText structure is easy. Set up the IntuiText definition, and then make a call to the PrintITextO function described below.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: PrintlTaxtO This is Intuition’s high-level text printing routine PrintIText(rastport_p, itext_p, left_offset, top_o£Eset); aO al dO dl rastport_p - pointer to a RastPort itext_p - pointer to an IntuiText structure lefLoflset - a general left offset which will be used with all of the linked IntuiText structures of a particular PrintITextO call, topoffset - a general top offset which will be used with all of the linked IntuiText structures of a particular PrintITextO call. None If an IntuiText font field is NULL then this function will use the RastPort’s font. If this is undefined then the default system font will be used. A RastPort incidentally is just another name for a drawing area. Screen and window RastPort pointers are, as you will see from the example code given later, easily obtained from the corresponding Screen or Window structures. It is convenient to have displacement offsets in the PrintITextO call itself because this allows a global offset to be applied to a whole chain of IntuiText structures. You may have a group of twenty or thirty separate text items on display but, if you so desire, will be able to reposition the whole group (keeping their relative positions the same) just by altering the PrintITextO global offsets.

There are a variety of options available for creating these units. You may use a general ds.b directive to provide space and then have the program set up the various fields using indirect addressing with displacement, much as was done with the NewWindow structure in the last chapter. Another possibility is to use the same initialisation approach but dynamically allocate the required memory, using the Exec memory allocation functions.

A more common method however is to set up static initialisation blocks using dc.x statements and this allows you to document the fields as well. In the example given later in this chapter you see this type of scheme used:

intuitextl dc .b 3jO,RP_JAM2,0 pens, drawmode and fill byte dc .w 60,20 XY origin dc.l NULL default font dc. 1 ITextTextl text pointer dc.l intuitext2 next IntuiText structure ITextTextl dc. b 'The border around this was drawn using DrawBorder()',0 cnop 0, 2 intuitext2 dc. b 3,0,RP_JAM2,0 pens, drawmode and fill byte dc .w 40,40 XY origin dc.l NULL default font dc. 1 ITextText2 text pointer dc.l intuitext3 next IntuiText structure ITextText2 dc. b 'and all of the text written using PrintITextf) function',0 cnop 0, 2 intuitext3 dc.b 3,0,RP_JAM2,0 pens, drawmode and fill byte dc. w 20,60 XY origin dc. 1 NULL default font dc. 1 ITextText3 text pointer dc. 1 NULL no next structure ITextText3 dc.b 'To quit just hit the CLOSE gadget at the top left of the window',0

Here I’ve linked three IntuiText structures together and this allows them to be printed with a single PrintlTextQ call. Notice also that the cnop directive is being used to ensure that each structure starts at an even address. If you forget this you’ll get addressing error Gurus.

Intuition’s arrangements for drawing graphics into multiple-bitplane screens and windows are, in terms of the underlying ideas, extremely complex. Intuition provides pre-written routines, based on a structure known as an Image structure, which simplifies the job of displaying graphics data. The Intuition Image structure itself is easy to understand. Here’s the layout:

STRUCTURE Image,0 SHORT ig LeftEdge WORD igTopEdge SHORT ig_Width WORD igHeight WORD igDepth APTR ig_ImageData pointer to real image data BYTE igPlanePick BYTE igPlaneOnOff APTR ig_NextImage pointer to next image structure LABEL igSIZEOF

ig_LeftEdge and ig_TopEdge are offsets from the top left of the display element. The ig_Width and ig_Height fields indicate the size of the image and ig_Depth tells the system how many bitplanes are in use. ig_PlanePick identifies the planes in the real display which have been picked to receive the defined image data, and ig_PlaneOnOff tells the system what to do with those planes that are not picked. ig_NextImage is a pointer which, in a similar fashion to the bd_NextBorder and it_NextText fields of the Border and IntuiText structures, allows any number of Image structures to be linked together and displayed with a single call to the Intuition DrawImageQ routine.

Function: Description: Call Format: Registers: Arguments: Return Value: DrawImageO This is Intuition’s high-level Image drawing routine DrawImage(rastport_p, image_p, left_oflset, top_offset); aO al dO dl rastport_p - pointer to a RastPort image_p - pointer to an Image structure left_offset - a general left offset which will be used with all of the linked Image structures of a particular DrawImageO call. top_offset - a general top offset which will be used with all of the linked Image structures of a particular DrawImageO call. None Notes: Again it is convenient to have displacement offsets in the DrawImageO call itself because this allows a global offset to be applied to a whole chain of Image structures. You may have a group of a couple of dozen separate images on display but, if you so desire, will be able to reposition the whole group (keeping their relative positions the same) just by altering the global offsets.

On the face of it this function call arrangement makes the display of graphics images very easy indeed. In practice things are not quite that simple because although using the Image structures and the DrawImageO function is easy enough, creating the associated Image data is not. In fact sitting down and working out from first principles exactly how to create the Image data for a particular object (whether it be a boat, a plane or some fancy backdrop display) turns out to be an absolutely monstrous task.

The good news is that you as a programmer will never have to do this because nowadays tools are available which make the task of creating complex graphic objects a piece of cake. Two things have helped produce this situation. Firstly, the existence of clear interprogram graphics definition guidelines (part of the now famous IFF standard) encouraged the creation of programs that can read and write graphics data using a common data-file format. Secondly, programs such as Electronic Art’s Deluxe Paint have provided an easy means of creating IFF picture files without requiring the programmer to be involved with the underlying complexities of bitplane data generation. More help has appeared and tools (such as Power Windows) that can convert IFF brushes into the equivalent Image data are nowadays readily available.

An example bit-by-bit plan for a small graphics object is provided in the Intuition sections of the Addison Wesley Libraries RKM manual. I’m not going to duplicate this material because, as I’ve already mentioned, you are unlikely to ever have to use this approach. The relationships between displays, bitplanes, Images etc, are dealt with very thoroughly in the RKM manuals and when you get to the point where you start to need in-depth information then the RKM manuals are without doubt the best place to look.

As already mentioned, the task of creating and using graphics in your Amiga programs has been considerably eased by the development of some sophisticated graphics-support tools. First and foremost we should mention Electronic Art’s Deluxe Paint.

No Amiga programming book would be complete without a mention of this classic Amiga drawing program. Deluxe Paint is powerful, robust, and best of all it can store as IFF files both complete pictures and small, user definable, graphic sections (brushes).

By switching on Deluxe Paint’s X/Y co-ordinate display a user can easily create objects of a given size. If some graphic images 50 pixels by 20 pixels are needed then a suitable background area can be marked out, the images can be drawn, and the brush facility can then be used to save that particular area of the display.

So, how do you get a Deluxe Paint drawing into your program? As you probably know Deluxe Paint stores picture data using IFF format files. These can be used in two basic ways. Firstly, it is possible for a program to read in an IFF file and convert it into a suitable (Amiga displayable) form directly. The advantages of this particular approach are that you only need to read the picture into memory just prior to displaying it, so it becomes very easy to change the graphics without re-compiling the program (you just swap one IFF file for another). Secondly, you can take the IFF file and convert it to an Intuition Image structure. Having done that the Image structure and the associated Image data can be read into the source code of the program and displayed using one of the Intuition support functions, namely the DrawImageO function. This system call takes four parameters: the address of the RastPort (drawing area), the address of the Image structure to be displayed, and the X and Y screen co-ordinates for the point identifying the top left of the Image.

How do you get from an IFF file to an Intuition Image structure? There are two ways. Firstly, there are a number of brush to image public domain utilities which can do this type of translation. Secondly, some commercial offerings are available which include facilities for this type of translation - here the Inovatronic’s Power Windows is probably the most sophisticated. Power Windows is far more than just a brush image converter program (that is just an incidental extra), it is an object orientated Amiga front-end design package. The examples of Image creation given in the next chapter were actually converted using Power Windows.

The following notes provide a brief tutorial introduction to the use of Intuition’s gadgets, an important and useful group of Intuition objects.My objective is not to document all aspects of Intuition object use (that information could fill a book by itself), it is to illustrate how some of the more important ones interact not only with each other but with the general Amiga’s program<→Intuition communication system. This, as we already know, is built upon Exec’s message handling facilities.

I’ll assume that you know, whether it be roughly or exactly, what a gadget is in Amiga-speak. Intuition provides a number of gadget types: Boolean gadgets for collecting yes/no, true/false type information, string and integer gadgets for collecting text and numbers. A more complex slider orientated unit, called a proportional gadget, is also supported and this enables positional information to be collected from the user.

Gadgets, from the users viewpoint, provide a convenient mouse-orientated way of inputting data. If as a programmer you had to devise a similar WIMP orientated icon system, define and program mouse movement and gadget selection procedures, and build a suitable gadget communications system you would rightly complain (it would be a massive task). Of course the Amiga programmer doesn’t have to do this - Intuition has provided building blocks which simplify the construction of such WIMP orientated programs. All you the programmer need do is find out how to use these building blocks.

At the highest level Intuition recognises two main gadget classes: system gadgets and custom gadgets. Since system gadgets are easily dealt with I’ll tackle these first.

This is where the fun really starts because, other than the fact that these entities must be linked to a window (rather than a screen), there are almost no restrictions on their use.

Creating a custom gadget entails setting up a suitable, Intuition understandable, definition of the unit you require. Such a definition will contain a great many items including, for example, position and gadget size info, gadget type details, and highlighting information so that Intuition knows what should be done when the gadget is selected by the user. It may also contain pointers to other units including Border, Image and IntuiText structures which specify graphics objects that should be associated with the gadget. You can of course also tell Intuition what sort of information you need to be kept informed about.

Needless to say this gadget definition involves another structure definition called, not surprisingly, a Gadget structure:

STRUCTURE Gadget,0 APTR gg_NextGadget pointer to next gadget in list WORD gg_LeftEdge next four variables describe the WORD ggTopEdge location/dimensions of the select box WORD gg_Width WORD gg_Height WORD ggFlags; highlighting/positioning/state flags WORD gg_Activation WORD gg_GadgetType APTR gg_GadgetRender APTR gg_SelectRender APTR gg_GadgetText LONG gg_MutualExclude APTR gg_SpecialInfo WORD gg_GadgetID APTR ggUserData LABEL gg_SIZE0F flags determine gadget behaviour identifies the gadget type pointer to 'unselected' Image pointer to 'selected' Image pointer to gadget text if any user-defined ID field pointer to user data

gg_NextGadget is a field which allows gadgets to be linked together. The programmer creates a suitable list of gadgets and then places a pointer to the first gadget (the head of the gadget chain) into the nw_FirstGadget field of the NewWindow structure. When Intuition opens the window it will read through the gadget list and both implement and monitor all of the gadgets you’ve asked for.

gg_LeftEdge, gg_TopEdge, gg_Width and gg_Height identify the position and dimensions of the gadget’s select box. The gg_Flags field is used to specify a number of gadget attributes based on Intuition defined flag values. Five commonly needed definitions are. GADGF1COMP which selects highlighting by complementing all of the bits within the gadgets select box.

GADGHBOX which highlights by drawing a box around the gadgets select box.

GADGHIMAGE which tells Intuition that alternate graphics will be used.

GADGIMAGE which tells Intuition that Images, rather than Borders, are being used in the gg_GadgetRender/gg_SelectRender fields.

SELECTED which enables you to preselect the state of a toggle-selected gadget.

but flags are also available for specifying positional data as container edge offsets rather than absolute container positions and for specifying that gadget sizes should vary with the relative height and width of the window. The RKM manuals are the place to look for complete details. Intuition also defines a set of Activation flags including the following: TOGGLESELECT which tells Intuition that a Boolean gadget should change (toggle) from on to off (and vice versa) each time it is selected. GADG1MMED1ATE which forces Intuition to send a GADGETDOWN IDCMP message as soon as a gadget is selected by a user.

Again many flags are available and as always it is to the RKM manuals that you should look for the most comprehensive information.

gg_GadgetType tells intuition what type of gadget is being dealt with. Allowable values include the BOOLGADGET, STRGADGET and PROPGADGET flags used respectively to indicate a Boolean, string or proportional gadget.

The gg_GadgetRender field, if non-NULL, indicates that there are borders or images associated with the gadget. If a border is being used then the field will point to a border structure. If the field is used to point to an Image structure then it is necessary to tell Intuition that this is so by setting the GADGIMAGE flag in the Flags field.

gg_SelectRender allows alternate imagery to be used when Intuition highlights the gadget. To use it, put a pointer to the Border or Image structure to be used in this field and set the GADGHIMAGE flag in the gg_Flags field.

gg_GadgetText if non-NULL should point to an IntuiText structure which describes the text to be associated with the gadget.

gg_MutualExclude is a part-implemented, but reserved, field. You’ll find details about the use of a BOOLEXTEND activation flag in the RKM Libraries manual.

gg_SpecialInfo is a field used to add additional structures to things like proportional gadgets.

gg_GadgetlD and gg_UserData are fields available for the applications program to use. They are ignored by Intuition itself.

Custom gadgets can be placed anywhere in a window and the list of gadgets associated with any one window can be modified whilst the window remains open. New gadgets can be added, gadgets can be deleted or prevented from functioning and you will find a great many useful Intuition support functions documented in the RKM Includes & Autodocs manual.

It is worth mentioning at this point that even during use, various items in a Gadget structure may be altered. Flags can be changed, message requirements may be altered and so on. In order to do this safely however certain rules should be adhered to, the most important being that you should remove a gadget from the window’s gadget list before you edit any characteristics that Intuition may be monitoring. Once the necessary changes have been made the gadget can be added back into the gadget list.

For example, one of the gadget flags that is monitored and adjusted by Intuition is the SELECTED flag. Sixteen bits are used in the gadget structure for such flags and the bit corresponding to 0080hex (C equivalent 0x0080) is the one that Intuition uses to tell whether the gadget is on or off. The intuition.i header file makes the appropriate definition of SELECTED and so to, safely, turn a gadget on or off this is the procedure which should be followed: remove the gadget from the list, adjust the SELECTED bit, add the gadget back into the list and finally up-date the gadget display.

Building NewScreen and NewWindow definitions, designing gadgets and working out suitable dimensions and characteristics etc, is not that difficult but it can be both time consuming and prone to error. Many programmers find it useful to use a WIMP interface code generator to create most (if not all) of these types of definitions and one particular program, called Power Windows, is well established and therefore clearly worth mentioning.

Essentially Power Windows provides the programmer with a tool for creating and editing screens, windows, gadgets and menus using an object orientated approach.

It’s a flexible program, screen definition is straightforward and both standard and custom screens are supported. You can set the colour palette directly or can incorporate a palette from any convenient IFF file. Windows are equally easily created and, once present on the display, can be moved around and resized using normal mouse operations. Adding gadgets to a window is just a matter of selecting the Add A Gadget menu option, adjusting the gadget’s size and then moving it to the desired position. Menu generation is equally simple and although not often needed you can incorporate IFF brush imagery with the menu.

One of the more powerful features of Power Windows is the Grab A Window menu option. When you select this option you are offered a menu which provides details of all of the screens and windows for all applications which are currently running. To grab a window you just select its name to cause the window, plus all of the associated gadgets and menus, to be imported into Power Windows. Only the window, text, gadget imagery etc, which is directly pointer linked to the window will be imported, so sometimes you will be disappointed with the results. Nevertheless this is a very useful function. Power Windows can also help with IDCMP event handling.

Once you are happy with the display, Power Windows can do one of two things. Firstly it can generate an intermediate file which contains the display data in a form which can be read back into Power Windows itself, which enables you to edit the display at a later date. Secondly it can generate the source code that your own programs can use to produce an identical display. There are several options available for code generation (either commented or uncommented) to be used with 68K assembler, Lattice/SAS C, Manx’s Aztec C, Benchmark Modula 2, TD1 Modula 2, MultiFORTH, TrueBASIC, AmigaBASIC, and ACBASIC Compiler vl.3.

Full control of screen, window, gadget, menu, text and border characteristics coupled with many other extras such as gadget cloning, collision checking, colour re-mapping and image compression makes Power Windows an extremely useful tool for the serious Amiga programmer.

Using these types of code generator for handling the Intuition interface has many advantages. First and foremost it will save you time! Secondly you’ll work with a display that can actually be seen as it is created. Thirdly it is possible, by keeping the reloadable intermediate files, to go back at a later date and make changes, eg reposition gadgets. Once the changes have been incorporated, just generate the new code, recompile and the new version will be up and running in a very short space of time. You can of course also use these types of tool to produce prototype interfaces for testing ideas and producing rough and ready skeleton interfaces. When you have finished your program you can then go back and tidy up the initial efforts. Once this has been done it is a simple matter to generate the new interface code and just swap that for the preliminary version.

Whilst on the subject of code generators, don’t forget that you can always tweak the source code that has been produced to suit your own purposes. There is nothing to stop you running the generated code through a text editor to change, eg globally prefix, the names of the structures.

Another good reason to modify the output code is to reduce its physical size. If, for example, you create a display with 48 identical gadgets, each having a border, then the generated code will have 48 identical border structures, one for each gadget. In such a case Intuition doesn’t need 48 instances but it will happily manage with one. So the trick is to read the generated source into a text editor, remove 47 of the identical structures, and then change the border pointers in each of the 48 gadgets so that they all point to the single remaining border structure.

Menus are the last of the Intuition building blocks that I’m going to look at. Again the purpose of this section will be not to mention every feature but to discuss the general ideas. You’ll see in the next chapter that the communications aspect of menu handling has much in common with gadget handling and many of the ideas that have already been dealt with can be expanded to provide generalised IDCMP-message based, event-driven, code loops.

When a user presses the right hand mouse button on an Amiga the title bar at the top of the screen changes to a menu strip which displays along its length one or more category names. As these names are touched by the mouse pointer, sets of options appear below the category name and these, if selected, can cause either particular program actions to occur or can result in the appearance of further sub-menu items.

Menus have many benefits. If properly organised, they can hide much of the complexity of a program from a user. They do not encroach on screen space until the right hand mouse button is pressed and even then their presence is almost completely transparent as far as things like use-detection, display saving and re-drawing are concerned.

The Amiga menu system is also very flexible and there are few absolute rules to follow. The menu content, overall structure, and the actions which should be performed when particular menu items are selected, can all be defined by the programmer. Intuition will use these definitions to set up and monitor the necessary graphics objects on the screen so from that point onwards the nitty-gritty details associated with menu use are handled automatically. When the user has done something significant, ie made a proper menu selection, Intuition will send the program a message explaining what has been done - it is then up to the program to decide what actions should be taken.

A menu, and here I’m talking about a single header followed by a number of menu items, will look like this:

MENU HEADER menu item 0 menu item 1 menu item 2 menu item 3

As far as positioning and size goes there are a number of constraints worth mentioning. The position/size of the item boxes must be such that they do not overlap the left or right sides of the header field. Item boxes should also be positioned so that they are directly adjacent, so that there are no spaces between menu item fields.

A menu item can itself invoke a sub-menu. From the programmer’s viewpoint sub-menu items, as you will see later in the chapter, pose no particular additional difficulties:

MENU HEADER menu item 0 menu item 1 menu item 2 menu item 3 sub item 0 sub item 1 sub item 2

To define a menu, Intuition uses a number of data sets, the first being the Menu structure itself:

STRUCTURE Menu,0 APTR mu_NextMenu WORD mu_LeftEdge WORD mu_TopEdge WORD mu_Width WORD mu_Height WORD mu_Flags APTR mu_MenuName APTR mu_FirstItem WORD mu_JazzX remaining fields are for internal use WORD mu_JazzY WORD mu_BeatX WORD mu_BeatY LABEL mu_Menu

mu_NextMenu provides a means of linking menus together. The next four fields describe the menu header’s select box. At the current time values for mu_TopEdge and mu_Height are ignored and the screen’s title bar values are used instead. mu_LeftEdge and mu_Width are then the fields which effectively size and position the menu header within the title bar framework.

The menu mu_Flags field contains two values. MENUENABLED indicates whether the menu is currently enabled or disabled so this flag should be set before asking Intuition to create the menu. Otherwise the user will be able to see the menu but will not be able to select anything. You should not directly alter this flag once Intuition has control of the menu - instead the OnMenuO and OffmenuO function calls can be used to enable or disable the menu as required. Another flag, M1DRAWN, is also defined. It is managed by Intuition and is used to indicate whether the menu items are currently visible or not.

mu.MenuName is simply a pointer to a null terminated string representing the menu’s header name. mu_FirstItem is a pointer to the head of a chain of Menultem structures used to describe the menu options themselves. As a STRUCTURE definition the format of a Menultem looks like this:

STRUCTURE Menultem,0 APTR mi_NextItem WORD mi_LeftEdge WORD mi_TopEdge WORD mi_Width WORD mi_Height WORD miFlags LONG mi_MutualExclude APTR mi_ItemFill APTR mi_SelectFill BYTE mi_Command BYTE mi_KludgeFillOO APTR mi_SubItem WORD mi_NextSelect LABEL mi_SIZE0F

These structures hold quite a lot of data so here’s the rundown on the most important Menultem characteristics that you’ll need to supply when building a menu:

mLNextltem is a pointer to the next item in a chain of such items. As usual the last item in the chain should have this field set to NULL.

mi_LeftEdge, mi_TopEdge, mi_Width and mi_Height describe the select box of the menu item.

mi_Flags. There are quite a few flag values defined by Intuition.

CHECKED tells Intuition that a CHECKIT item should be displayed in the checkmarked selected state right from the start.

CHECKIT tells Intuition that a menu item is an attribute, ie something with a value or characteristic rather than some action which is to be carried out. Intuition will checkmark the field when it is selected and the checkmark/no-checkmark state will toggle on and off with alternate selections.

COMMSEQ informs Intuition that the menu item has an alternative command-key sequence that may be used instead of mouse/menu selection. Menu command-key sequences are combinations of the Right-Amiga key with some other alphanumeric character. If such a sequence is received, which corresponds to a defined menu selection, Intuition will send the program the equivalent menu selection event which the program would treat in the normal fashion.

HIGHBOX is another highlighting flag which results in a box being drawn around the item’s select area.

HIGHCOMP is a select highlighting flag which complements the select box of the menu item.

HIGHIMAGE indicates alternate imagery based on either IntuiText or Image structures. If text items are being used, the ITEMTEXT flag should also be set.

HIGHITEM is an Intuition maintained flag which indicates the highlight state of an item.

HIGHNONE sets this flag and no highlighting will be done.

ISDRAWN is an Intuition maintained flag which indicates when subitems are on display.

ITEMENABLED should normally be set before submitting a menu to Intuition to ensure that the initial menu display is active. Once the menu is under Intuition’s control the flag should not be altered except indirectly through the OnMenuO and OffMenuO function calls.

ITEMNEXT tells Intuition that the miJtemFill/mLSelectFill fields point to IntuiText structures rather than images. The flag should be cleared, ie not set, when images are being used.

MENUTOGGLE must be set if a CE1ECKIT item is to be toggled. mi_MutualExclude. This field allows the programmer to define fields as mutually exclusive. The purpose of this facility is to enable the programmer to prevent the user from making incompatible menu selections. If your program has menu options which support both low and high-resolution screen displays, it’s pretty obvious that the user should not be able to select and turn on both options together so the solution is to make the two items mutually exclusive. By selecting high-res, the low-res option becomes de-selected and vice versa.

mi_ItemFilI. This field is a pointer to either an IntuiText structure or an Image structure used to describe the data for rendering this item. If text is used, the ITEMTEXT flag should be set in the menu item’s mLFIags field.

mi_SelectFill. If alternate imagery is being used, ie if the HIGHIMAGE flag has been set, this field should point to the appropriate IntuiText or Image structure.

mi_Command. This field stores a single alphanumeric character used as a command-key shortcut. If the COMMSEQ flag has been set the user will be able to hold down the key, together with the Right-Amiga key, to select this item. Intuition senses the keypresses and transmits a menu event which looks as though the user selected the item via the normal mouse/pointer approach.

mi_SubItem. Points to the first subitem in a subitem list. Subitems are defined using the same Menultem structure but they should NOT themselves have subitems!

mi_NextSelect. This field is maintained by Intuition and indicates when the item has been selected.

By the time the Menu and Menultem definitions are complete most of the programmer’s work is finished. All that remains is straightforward installation followed by management of the userc→program interactions. Intuition provides a number of function calls for this purpose.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: SetMenuStripO Attach a menu to a window result=SetMenuStrip (window_p, menu_p); dO aO al window_p - pointer to the window that menu is to be attached to. menu_p - pointer to the Menu structure result - TRUE/FALSE success or failure indicator Any menu strip attached to a window should be removed before closing the window.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: ClearMenuStripO Remove a menu strip from a window. Clear MenuStrip (windo w_p); aO window_p - pointer to a window structure None If menu is in use this function will wait until user has completed their menu operations before removing the menu.

Function: Description: Call Format: Registers: Arguments: Return Value: Notes: OnMenuO Enable a menu or a specific menu item OnMenu(window_p, menu_number); aO dO window_p - pointer to a Window structure menu_number - an unsigned 16 bit menu number value None Menu numbers, and their internal arrangements are discussed in detail in the RKM Libraries & Devices manual.

Function: Description: Call Format: Registers: OfXMenuO Disable a menu or a specific menu item OffMenu(window_p, menu_number); aO dO Arguments: Return Value: Notes: window_p - pointer to a Window structure menu_number - an unsigned 16 bit menu number value None Menu numbers, and their internal arrangements are discussed in detail in the RKM Libraries & Devices manual.

Function: Description: Call Format; Registers: Arguments: Return Value: Notes: ItemAddreasO This function returns the address of a specific menu item item_p =ItemAddress(menu_p,menu_number); dO aO dO menu_p - menu pointer menu_number - a 16 bit unsigned menu number address of the menu item (NULL if no item was selected).

Before we look at some examples of gadget and menu code I ought to point something out concerning the material that’s been covered over the last few chapters. As you will doubtless know Intuition is a big subject in its own right and it was never my intention to deal with all of aspects of gadget and menu use, let alone discuss Requesters, Alerts and so forth. What I have chosen to do instead is concentrate on some aspects that have clearly caused many new Amiga programmers a lot of problems including systematic, cleanly coded, message handling.

Once you’ve come to terms with some basic Intuition structures, and the ideas relating to the message passing environment, you’ll realise something very important - all the structures and Intuition objects have very similar layouts and use arrangements and, best of all, once you can handle one type of IntuiMessage, you’ll be able to handle any type of IntuiMessage. That, of course, goes a long way towards reducing the learning curve problems that we all have to face!

The purpose of this chapter is to build on the material already discussed to create a simple, but nevertheless complete, Intuition based example program. For the Amiga newcomer, getting involved with Intuition based programming usually comes as a bit of a shock to the system because a lot of system-related material needs to be understood. For those venturing out into the world of 68000 assembler the shock is even greater especially since much of the available documentation has been written for the C programmer.

The good news however is that, if you’ve got this far into Mastering Amiga Assembler, and have coped with the material to date, or at least acquired an appreciation of the main ideas, then you are almost home and dry. I’ve looked at the Amiga environment, the header files, the use of some important system macros (which make 68000 programming easier), and the ideas related to the opening of libraries and making library calls. I’ve also talked about Exec message-based IDCMP issues and provided a routine for the easy collection of CLOSEWINDOW type IDCMP messages.

Chapter 14 put some of those ideas together and the first thing I want to do in this chapter is to build on those ideas by presenting a program that uses a custom Intuition screen. The basic plan then is as follows:

Open Intuition Library Open Graphics Library Open an Intuition Screen Set up screen’s colour map Open an Intuition Window Print some Text, Borders and Images Go to sleep until user hits the CLOSE gadget Close Window Close Screen Close Graphics Library Close Intuition Library

The good news is that you’ll already recognise most of the program code (because it’s based on the Workbench screen orientated Example CH14-1.S) so all that remains is to provide some notes about the additions that have been made.

Because the LoadRGBQ function is going to be used to set up the screen colours I’ve had to open the graphics library, hence you’ll see what should by now be a very familiar piece of additional code, namely:

lea moveq CALLSYS move.l beq graphics_name,a1 #0,d0 OpenLibrary,_SysBase dO,_GfxBase CLOSE INTUITION library name start in a1 any version will do macro (see text for details) store returned value test result for success

To actually open the screen the custom screen routines, first discussed in Chapter 8, have been used. The following fragment makes use of the new_screen structure that you’ll find in the source listing:

OPEN_SCREEN lea CALLSYS move.l beq new_screen,aO new_screen base address OpenScreen,_IntuitionBase dO,screen_p CLOSE GRAPHICS

One of the additions to the program is the display of an Intuition image using the DrawImageQ function. Electronic Art’s Deluxe Paint was used to create an IFF brush and, after conversion to a dc.w based Image definition, this was read into the program. The graphic is displayed with this straightforward call:

DRAW IMAGE move.1 window_p,a1 get window address move.1 wdRPort(a1),a0 get rastport address lea imagel,a1 move.1 #0, do no additional offsets move.1 #0,d1 CALLSYS DrawImage,_IntuitionBase

Notice incidentally how indirect addressing with displacement is used to get the window’s rastport address.

The next stage in our experiments is to re-write this first program so that it uses a menu style quit option rather than the system’s close gadget.

To do this we have to create a menu structure and add it to our existing code. I’ve opted for the simplest example possible, one menu with a single menu item in it, and the data itself, which has been set up using the structures discussed in the last chapter, looks like this:

Having created the appropriate structures we need to tell Intuition to use the menu. This is done using the SetMenuStripO and ClearMenuStripO functions described in the last chapter and, as with so many of these system functions, the code is trivially simple once you’ve got the hang of library call use. Load the parameters needed by the function, and then use the CALLSYS macro.

Since setting the menu is the last job the program does before waiting to quit, removing the menu needs to be the first job to be done during program shutdown. Here’s the code fragment you’ll find in the Example CH15-2.S source:

ADD_MENU move.l window_p,aO lea Menul,a1 CALLSYS SetMenuStrip,_IntuitionBase SLEEP move.l window_p,aO window base address move.l wd_UserPort(aO),a2 user port jsr WaitForMenuMessage REMOVEMENU move.l window_p,aO CALLSYS ClearMenuStrip,_IntuitionBase

A few other changes have been made to the code from the first example. To start with I’ve removed the WINDOWCLOSE flag from the Flags field of the NewWindow structure, effectively telling Intuition that I no longer want a system window close gadget in the window. The CLOSEWINDOW flag has been removed from the IDCMP field. Obviously we will not get any of these messages because the close gadget is no longer present in the window.

The WaitForExitMessageO routine has been renamed WaitForMenuMessageO and where previously we checked for messages of class CLOSEWINDOW we now check instead for messages of class MENUPICK. Intuition makes this extremely easy to do and codewise all that is necessary is to change the comparison:

cmpi.l #CL0SEWIND0W,im_Class(a1) to: cmpi.l #MENUPICK,im_Class(a1)

Taken in isolation none of the above mentioned changes are particularly difficult but, with Intuition’s help, we have nevertheless been able to completely change the exit procedure. Here’s a listing of the revised code to examine:

When you run the assembled version of Example CH15-2.S you’ll notice that the program terminates even if you use the menu but decide not to make a menu selection. The reason stems from the fact that in this latter case Intuition sends a MENUPICK message whenever a menu is used regardless of whether a selection is made or not. To find out which items were selected it’s necessary to analyse the menu number information provided in the im_Code field of the intuimessage.

In the case of the simple menu I’ve used there is only one item and so the program will either receive the code corresponding to that item, or it will receive a MENUNULL code to indicate that a selection was not made. I’ve opted for just checking that the message does not have a MENUNULL code before setting the menu routine’s exit flag. In other words the fragment:

cmpi.l #MENUPICK,imClass(a1) bne GetMessagel move.l #TRUE,d2 user wishes to quit

has been altered to:

cmpi. 1 #MENUPICK,im_Class(a1) bne GetMessagel cmpi.w #MENUNULL,im_Code(a1) beq GetMessagel false alarm? move.1 #TRUE,d2 user wishes to quit

Since this is the only change made I’m not going to list the revised program (but you will find it on disk as ExampleCH15-3.s). Here though is the revised WaitForMenuMessageO routine so that you can see how the above changes fit into the general framework:

A Final Excursion

This last example puts our existing experiments firmly into an Intuition based framework by making things happen as a user selects (or de-selects) various gadgets.

Some of the changes, such as using different text and positional data in the IntuiText structures, will be easily recognised as being of no special significance. Similarly the only noticeable changes in the early part of the program are that the calls to display border and image data have been eliminated because these operations will be dealt with as part of the gadget handling code. One additional library call, to set the colour of the primary graphics pen, was needed and the code for this is as follows:

SET_PEN_C0L0UR move.l window_p,a1 get window address move.1 wd_RPort(a1),a1 get rastport address move.b #BLACK,d0 CALLSYS SetAPen,_GfxBase

The basic program framework is therefore still very similar to the previous example:

Open Intuition Library Open Graphics Library Open an Intuition Screen Set up screen’s colour map Open an Intuition Window Add Menu Set Pen Colour Print some Text Go to sleep until user does something Remove menu Close Window Close Screen Close Graphics Library Close Intuition Library

There are however two areas within this framework where things have changed quite dramatically. Firstly, a chain of three gadget definitions has been set up using the structure format outlined in Chapter 14. The setting up of gadget structures is just a matter of following the system guidelines. Once the definitions have been created, getting them displayed is easy because Intuition does most of the work - all the programmer needs to do is to place the address of the first gadget in the nw_FirstGadget field (see the source listing for details).

The second area where changes have occurred is the event handling section of the program. The good news here is that the ideas are still based on the message collection approach used with the WaitForExitMessageQ and WaitForMenuMessageO functions. The routine has however been expanded to provide gadget handling facilities. The three gadgets are of the Boolean on/off variety and have Text, Border, and Image labels. When a gadget is selected a corresponding Intuition item gets displayed, when the gadget is turned off the item is removed from the screen.

The method I’ve chosen for this example is as follows: I store the gadget address (retrieved from the intuimessage) in a variable called gadget_p then, at the end of a possible stream of intuimessages, I look to see whether a valid address is present. If a gadget had not been used then my pointer would contain its initial value of zero.

Here’s the code for the uppermost level of the handler:

MessageHandler movem. 1 clr. 1 MessageHandler2 clr. 1 move.1 CALLSYS jsr cmpi.1 beq tst. 1 beq jsr d0-d4/a0-a2,-(sp) preserve registers d4 clear exit flag gadget_p clear gadget pointer a2,a0 port address WaitPort,_SysBase GetMessage #TRUE,d4 exit flag set? MessageHandler3 gadget_p was a gadget hit? MessageHandler2 GadgetHandler do gadget operations bra MessageHandler2 MessageHandler3 movem.l (sp)+,d0-d4/a0-a2 restore registers rts logical end of routine

You will notice that register a4 is now being used as the exit flag. This is because my original exit-flag register (d2) is needed by a RectFillO graphics function which is used to clear a displayed image from the window. A further extension is that, having checked to see if the IDCMP message is a MENUPICK message, a further check needs to be included for GADGETUP messages. It is here that, providing we’ve got the right type of message, that the gadget address is retrieved and stored in the gadget_p variable: CheckGadgets cmpi.l #GADGETUP,im_Class(a1) bne GetMessagel move.l im_IAddress(a1),gadget_p save gadget address

With these fragments in place the second level of the message handling routine should still be comfortably familiar:

GetMessage move.l a2,a0 get port address in aO CALLSYS GetMsg,_SysBase get the message tst.l beq move.l cmpi.l bne cmpi.w beq move.l bra CheckGadgets cmpi.l bne move.l GetMessagel CALLSYS bra GetMessageExit rts dO GetMessageExit did it exist? dO,a1 copy pointer to a1 #MENUPICK,imClass(a1) CheckGadgets #MENUNULL,im_Code(a1) GetMessagel false alarm? #TRUE,d4 user wishes to quit GetMessagel #GADGETUP,im_Class(a1) GetMessagel im_IAddress(a1),gadget_p save gadget address ReplyMsg,_SysBase GetMessage check for more messages d4 holds exit flag

You will have noticed from the first level code that a jsr GadgetHandler call is made if gadget_p is non-zero. If it is non-zero it’s because it contains the address of a gadget placed there by the above code. If you go back to Chapter 14 and look at the Gadget structure you’ll see a field called gg_GadgetID. If you look at the gadget definitions given in the source code to Example CH15-4.S you will see that I’ve placed the values 1, 2 and 3 in the gg_GadgetID fields of Gadgetl, Gadget2 and Gadget3 respectively.

To find out which gadget has been hit all we need to do, using our nowadays familiar structure accessing via indirect addressing approach, is to identify the gadget number and take some appropriate action. Here’s a fragment that looks for gadget number 1 and, if found, executes a text printing routine:

GadgetHandler move.l cmpi.w bne jsr rts gadget_p,aO #1 jgg_GadgetlD(aO) gadget 1 hit? GadgetHandlerl PrintText

Here’s the fragment which checks for the second gadget: GadgetHandlerl cmpi.w #2,gg_GadgetID(aO) bne GadgetHandler2 gadget 2 hit? jsr DrawBorder rts

Since only three gadgets are in use, a gadget hit which turns out not to be gadgets 1 or 2, must be gadget 3. So the identity of gadget 3 doesn’t need to be checked: GadgetHandler2 jsr Drawlmage must be gadget 3 rts

Having recognised a gadget hit, stored the gadget address, and now reached the stage where we know the gadget’s identity, all that remains code-wise is to do the various print/drawing operations. There’s more good news here because these operations were done as part of the earlier program anyway and in two cases all that was needed was to move the routine from the original position to the gadget handling routine. This text print routine should therefore already be familiar:

PrintText move.l window_p,a1 get window address move.l wd_RPort(a1),a0 get rastport address lea intuitext2,a1 move.l #0,d0 no additional offsets move.l #0,d1 CALLSYS PrintIText,_IntuitionBase rts

Similarly the border drawing code is identical to that in the previous program:

DrawBorder move.l window_p,a1 get window address move.l wd_RPort(a1),a0 get rastport address lea border1,a1 move.l #0,d0 no additional offsets move.l #0,d1 CALLSYS DrawBorder,_IntuitionBase rts

Where they differ operationally however is that the RP_COMPLEMENT draw mode has been used so that the item is drawn and then un-drawn with successive calls to PrintTextO and DrawBorderQ!

Unfortunately the same approach cannot be used with the image drawing operation. Instead it is necessary to look at the gg_Flags field of the gadget structure to see whether it is selected or unselected and the easiest way to do this is to copy the gadget state into a data register like this: move.w ggFlags(aO),d0 get gadget state and then exclusive OR the value with the system-defined SELECTED flag: eori.w #SELECTED,dO zero flag set = SELECTED

If the zero flag is set then this means that the SELECTED bit was set in the gg_Flags field. The following code does this and on the basis of the result it performs either a Clear Image routine or the Draw Image routine (as used in the previous program). For the example the image clearing was done by using the RectFillO graphics library function. The co-ordinate details need to be placed in d0-d3 and the window’s rastport address in register al so the final image drawing/clearing section of the program ended up looking like this:

Drawlmage move. 1 window_p,a1 get window address move.w gg_Flags(aO),dO get gadget state eori.w #SELECTED,dO zero flag set = SELECTED beq Drawlmagel Clearlmage move.1 wd_RPort(a1),a1 get rastport address move.w #44,dO set image dimensions move.w #130,d1 move.w #44+232-1,d2 move.w #130+88-1,d3 CALLSYS rts RectFill,_GfxBase Drawlmagel move.l window_p,a1 get window address move.1 wd_RPort(a1),aO get rastport address lea imagel,al move.l #0,d0 no additional offsets move.l #0,d1 CALLSYS rts Drawlmage,_IntuitionBase

When all these fragments are placed together we end up with a routine that carries out the operations which we have deemed necessary for the menu and gadget events messages that could occur:

The material covered in this chapter takes us to the end of our Intuition experiments. The final program, Example CH15-4.S, may not be earth shattering but it contains examples of a lot of things that real Intuition programs have to do. It opens libraries, screens and windows, draws text, borders and images, and it uses menus and gadgets via the Exec-based IDCMP message facilities. Once you’ve come to terms with this material you should be ready to choose your own pathways as far as Intuition is concerned and so, in a sense, this last program just gives you a place to start. Nevertheless, a lot of material has been covered in recent chapters and it seems a good idea to make sure that a hard copy of the results are available as a point of reference:

By now it should be obvious that even simple 68000 Intuition programs can provide a few development headaches. When you see what needs to be done for more complex Intuition applications the whole Intuition thing can become quite frightening. Worse than that the pure 68000 approach has another disadvantage - it can take a lot of time. There is however a solution that is increasingly favoured by many commercial developers and since no Amiga assembler book would be complete without some discussion of it, I’ve decided to finish my 68000 meanderings with some details.

This chapter deals with issues which would not normally be regarded as suitable for the 68000 beginner. I’ve included it primarily because it could, if you have some C experience under your belt, enable you to get all the benefits of assembler programming without the disadvantage of having to code complete applications programs in assembler.

One of the problems that the programmer working solely in 68000 assembler has is time, or rather the lack of it. Large assembly language programs, as you now doubtless realise, take a long time to develop. This, coupled to the fact that 90% of most programs are not time critical, leads many programmers naturally to the conclusion that it is far quicker, and far easier, to develop a large program in a language like C and then fine tune it by rewriting the time critical parts using assembler. In that way you get the development speed of a high-level language coupled to the speed of assembler in the places where it counts.

This attitude isn’t a cop out, nor an admission that assembler isn’t up to the job when it comes to large applications programs. It is a practical solution which shortens development time but does not, in the end, sacrifice the efficiency gains which the Amiga assembler programmer can achieve. In order to be able to write this type of mixed code you obviously need to know how to get from C to assembler code and back again. The good news is that once you have seen it done, you will realise that it’s not actually that difficult. To be honest all decent C compiler manuals provide the necessary technical details although unfortunately the explanations are usually written in a way that only makes sense once you know a little about what’s going on in the first place.

This chapter is designed to do three things. Firstly, to provide the necessary background information so that, if you decide to get into this very useful area of Amiga programming, the accounts you’ll read in your compiler manuals will make more sense. Secondly, to provide details of the conventions used with the two most popular Amiga C compilers, Manx Aztec C and SAS/Lattice C. Thirdly, to offer some runable examples which will get you into mixed code programming in as painless a manner as possible. A general overview of the Amiga system programming issues has been provided but some system and RKM literacy is expected with the last example.

I mentioned early on in the book that there were a couple of places where some knowledge of C would be needed and it’s for this reason that an appendix giving an overview of the language was provided. For the rest of this chapter then I’m going to assume that you know what a C function call is and at least a little about the C language itself.

Let us then make a start by talking a bit about the magic which occurs when you place a call to a routine, say Convert!), into a C source program. The compiler uses such source code statements to generate a reference to the named routine.

Under normal circumstances both the Manx Aztec and SAS/Lattice C compilers tag on an initial underscore to the function name. The call to the function Convert!) therefore has the linker searching for a routine called _Convert and it is this routine, if the linker is going to successfully resolve the reference, that must be provided in the assembly language module!

The code which various C compilers produce when they encounter a function call does vary but the conventions to be followed will always be detailed in the compiler manual. To start with all you really need to be aware of is that the end result is usually that any parameters present in the function call get pushed onto the stack prior to a call being made to the appropriate subroutine. I say usually because there are some qualifying conditions with Lattice/SAS C because it allows register arguments to be used rather than the stack and in this case it is an @ character, rather than an underscore, which gets placed at the start of the function name.

From a practical viewpoint you, the mixed-code programmer, will have two tasks - writing the high-level C code which will take you out of C and into your assembler module, and writing the 68000 patch itself.

Writing the appropriate C code is easy - it simply involves placing suitably named function calls, with any required parameters, into the C source. This is done using normal C function conventions -you can even add your own ANSI C function prototypes to make sure that the compiler makes the appropriate usage and parameter-type checks!

The next step involves writing suitable assembly language code and assembling it to produce linkable object code. The assembler directives XDEF and XREF have to be used to get things running smoothly.

We’ve already covered these assembler directives but let’s go over the details once more for good measure. XDEF is used to define assembly language labels as being visible to other modules at link time. If you forget it, the assembly stage will go OK but you’ll get errors when linking because the linker will be unable to resolve the corresponding function reference in the C code module.

XREF goes the other way, ie it tells the assembler that the information needed about the item in question will be imported when the assembly language module is linked. If you forget these then you’ll get errors as soon as you try to assemble your code because the assembler will not realise that labels have been used whose values are unknown at assembly time.

Most assembler’s place a limit on the number of characters within a label that will be regarded as significant and the ANSI C compiler standard actually only requires that the compiler caters for six characters with external references (although most handle more). The consequence of this is that you can, and it has happened to me many times, think you’ve got all of your inter-module references right but because a label gets truncated you end up with unexpected linker errors. Luckily this is never a serious problem and having, perhaps rather unwisely, used a variable such as:

my_variable_with_an_extremely_long_name

only to find that the linker tells you that it cannot resolve a reference called: _my_variable_wi

it doesn’t take too long to realise where the problem lies. The moral here is that it pays to be a pessimist. Either check the manuals first, or don’t use long names for functions and variables whose references might need to be passed between modules. Manx’s Aztec C incidentally offers #asm and #endasm statements which allow assembler code to be embedded within the C source. This can be useful on occasions but, in general, I believe it is safer to always place any assembler code into a separate module.

These are the Function Entry rules. Upon entry to a function the stack, under conventional parameter passing conditions, contains the function arguments placed immediately above the long-word return address which register A7 (the stack pointer) points to. The arguments are pushed in right-to-left order and so it is the leftmost parameter which is the one immediately above the return address.

Here are some standard function entry steps which need to be carried out:

These steps can, if the work area required is less than 32K, be achieved with the 68000’s link instruction. Lattice/SAS expects registers d2-d7,a2-a4 and a6 to be intact on return so, if any of these registers are to be used, they must be preserved. Again it is common practice to place them on the stack. The above stack orientated procedure forms the basis of a powerful general parameter passing technique which is well worth studying.

Function return values are passed back in one or more registers, depending on the data type declared for the function in question. Here are the return value details that must be adhered to:

Return Type Size Pass Back Details char 8 low byte of dO short 16 low word of dO long 32 all of dO float 32 all of dO pointer 32 all of dO double (IEEE) 64 passed in dO and dl with high bits in dO double (FFP) 32 all of dO

If, incidentally, the function returns an instance of a structure or union (as opposed to a pointer to the object) then it must define a static work area, not on the stack, to temporarily hold the returned object. In these cases the function should return a pointer to the temporary copy in dO. Having set up the required return value the routine needs to reverse its entry steps, restoring the registers, advancing the a7 stack pointer past the work area, and restoring the previous frame pointer to a5, before exiting via a rts instruction. As mentioned in Chapter Four, the 68000 has an unlink (unlk) instruction specifically intended to simplify these operations. Note incidentally that it is the job of the calling function, and not the called function, to remove any arguments from the stack.

This last example is more advanced and has really only been included so that you can see something of the tricks that can be done with mixed code programming. It involves creating a pair of 68000 patches to create messages which flash, like the famous Amiga Guru alert. Creating flashing text on the Amiga is a relatively simple job because of the Amiga’s colour indirection scheme. As you already probably know the screen colours present on a display aren’t colours at all, they are references to colour registers, which is where the indirection comes in. By changing the values in these registers the effective, ie visible, colours present on the display can be changed without any additional screen manipulation effort. What we need to do therefore to create a flashing colour is to arrange to alternate the value in some particular colour register.

Now a program using such flashing facilities would not, or certainly should not, want to get involved with the task of continuously changing values in a colour register itself. The best idea, since it is not a particularly time consuming task, is to create a piece of code which is executed automatically and one way of doing this is via the interrupts.

Interrupt processing on the Amiga is a bit of a grey area especially since a lot of the early Amiga technical information verged on the misleading. At the Exec system level, two types of arrangements are available: interrupt handlers, and interrupt servers. Exec servers allow particular interrupt signals to be shared, so a number of quite independent routines can be tied to the same interrupt. In the case of my assembler code example, 1 am using the Exec server mechanism to modify a colour register value during selected vertical blanking intervals.

The Exec library offers a couple of system routines, called AddlntServerQ and RemlntServerQ, which allow sections of code to be added or removed from the interrupt chain in a system compatible fashion. These routines, which are documented in the Addison Wesley Includes and Autodocs RKM manual, take this form:

Add IntServer(interrupt_number, interrupt_pointer) RemintServer(interrupt_number, interrupt_pointer) register usage do aO

The interrupt number for the vertical blank interrupt is 5, but for clarity it’s best to use the include file symbolic value lNTB_VERTB.The second parameter is a pointer to a system Interrupt structure, which to a C programmer looks like this:

struct Interrupt { struct Node is_Node; APTR isData; VOID (* isCode)(); };

The equivalent assembler include file definition uses a value LN_SIZE to provide an offset equivalent to an Exec Node structure:

STRUCTURE IS,LN_SIZE APTR ISDATA APTR IS_C0DE LABEL IS SIZE Exec uses these types of data blocks to provide a list of jobs which must be done when the interrupt occurs. As can be seen from the above fragments, part of the Interrupt structure includes a Node structure. In C this looks like this: struct Node { struct Node ln_Succ; / struct Node ln_Pred; / UBYTE ln_Type; /* BYTE ln_Pri; /* char ln_Name; / }; pointer to successor node */ pointer to predecessor node */ set this to NT_INTERRUPT */ can be set from +128 to -127 */ NULL terminated string pointer */

But for the assembler programmer the system STRUCTURE macro again comes to the rescue and allows this definition to be created:

STRUCTURE LN,0 APTR LN_SUCC APTR LN_PRED UBYTE LN_TYPE BYTE LN_PRI APTR LN_NAME LABEL LN SIZE

Several points are worth mentioning. Firstly, the Node’s type, priority and name fields have to be provided. Secondly, the IS_CODE pointer must contain the address of your interrupt routine. Another rather important point is that you do not use rte instructions at the end of the routine - server chain interrupt code sections need to be written as subroutines ending in a rts! One last point concerns the IS_DATA field; this is available for convenience and Exec will pass anything you place in this field directly to the interrupt routine. How? It copies the field into the 68000’s al address register so it is ready and waiting as the interrupt code is entered.

Given a suitable piece of code, and the properly initialised Interrupt node structure, the installation is surprisingly easy and just involves using the AddlntServerO routine. Before exiting the program can use a RemlntServerO call to take the job out of the vertical blanking server chain.

For this example I’ve put three pieces of code on disk. Firstly, there is the assembler source code which handles the setting up and closing down of the flashing interrupt. This is just a short example which modifies the contents of colour register 7. Depending on your needs, it shouldn’t be too difficult to modify the routine to suit your own purposes. Secondly, I’ve included the source code for a skeleton C program which handles all the mundane Intuition screen/window opening, menu creation etc. Within this code you’ll see a couple of calls to my assembly language routines. FlashOnO installs my interrupt job in the server chain, FlashOffO does the opposite, ie it removes it. Lastly, I have included a Workbench/CLI runable example which allows you to turn a flashing text display on and off via a menu.

Here to finish with is a listing of the assembler code. Since it was written using HiSoft’s Devpac assembler I’ve left it in Devpac form to illustrate the use of the CALLEXEC and CALLGRAF (Devpac specific) macros. Users without Devpac will need to convert those macro calls by inserting the equivalent CALLSYS macro and specifying the appropriate library base. For instance the macro expression CALLGRAF SetRGB4, should be changed to CALLSYS SetRGB4, GfxBase:

The complete range of 68000 instructions can be roughly divided into the following classes:

I mentioned right at the beginning of the book that just to list the full details of the 68000 instruction set would take a book in itself. This being so the details that follow are just a summary of the main instructions with a few notes about their uses, the addressing mode restrictions, flag effects and so on. Some examples are provided but in most cases you will find the most complete discussions of usage in the main text of the book. Many 68000 instructions can work with byte, word and long word operands. Byte size values will not however be allowed if the destination or source operand is an address register. There are incidentally a number of instructions which can only be used in 68000 Supervisor mode. You’ll see a number of these mentioned (mainly for completeness) but for full details of these instructions, and discussions of other issues such as 68000 trap handling which have not been dealt with in this book, you are referred to the references given in the bibliography.

Mnemonic: EXG - Exchange Registers Purpose: Exchanges the contents of two registers Addressing Modes: Source Destination Data register direct X X Address register direct X X Flags affected: X N Z V C Notes: This instruction does exactly what you’d expect - it swaps the contents of two registers. Example: Before After exg a1,d2 d1=00000001 a1=44445555 d1=44445555 d1=0000001 Mnemonic: LINK - Link and Allocate Purpose: Creates temporary space on the stack Flags affected: X N Z V C Notes: The source address register is pushed onto the stack, the stack-pointer (a7) is copied into the source and the destination is added to the stack-pointer. The destination-operand needs to be negative because the 68000-stack grows downward in memory. This instruction is dealt with in Chapter 4.

Mnemonic: UNLK - Unlink Purpose: This reverses the link process Flags affected: X N Z V C Notes: See Chapter Four for a discussion of how the unlk instruction is used. Mnemonic: LEA - Load Effective Address Purpose: Loads an address register with a processor determined effective address. Addressing Modes: Source Destination Data register direct Address register direct X Address register indirect X Postincrement register indirect Predecrement register indirect Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate flags affected: X N Z V C Notes: This instruction allows you to load an address register with an effective source address, ie the source address specified by virtue of a chosen addressing mode. Example: The effective source address for the instruction: lea new_window,aO is the address of the location which has been labelled new_window. This is an example of absolute addressing.

Mnemonic: MOVE - Move Data from Source to Destination Purpose: Copies a source operand to specified destination Addressing Modes: Source Destination Data register direct X X Address register direct X* Address register indirect X X Postincrement register indirect X X Predecrement register indirect X X Register indirect with displacement X X Register indirect with index X X Absolute Short X X Absolute Long X X PC relative with displacement PC relative with index Immediate X Flags affected: X N Z V C - Y Y 0 0 Notes: You will find plenty of examples of move instructions within the chapters of this book. See the notes about the movea instruction and also be aware that address register direct addressing is not allowed if specified data size is byte! There are a number of specialised move instructions which allow reading from and writing data to the whole status register or just the lower byte that holds the condition codes, allowing you to forcibly clear/set the N, Z, V, C and X flags. Some of these instructions are privileged in one or more members of the 680x0 family and you should consult the official 680x0 documentation for details.

Mnemonic: MOVEA - Move Address Purpose: Loads an address register with a value Addressing Modes: Source Destination Data register direct X Address register direct X X Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C Notes: Only word or long word operands can be specified and if the operation is word-sized then the address is sign-extended. Most 68000 assemblers will accept move <ea>,An as well and the latter convention has been adopted in this book. You do however need to remember that when move is used to load an address register it is really a movea instruction and the flags are not affected.

Mnemonic: MOVEM - Move Multiple Registers to Memory Purpose: Copies multiple registers to memory Addressing Modes: Source Destination Data register direct Address register direct Address register indirect X Postincrement register indirect Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C Notes: The main use of the instruction in this book has been for storing registers on the stack. For example: movem.l d0-d7/a0-a6,-(a7) push all registers onto the stack.

Mnemonic: MOVEM - Move Multiple Registers From Memory Purpose: Copies multiple registers from memory Addressing Modes: Source Destination Data register direct Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C Notes: The main use of the instruction in this book has been for retrieving registers from stack. For example: movem.l (a7)+,d0-d7/a0-a6 pull all registers from the stack.

Mnemonic: MOVEP - Move Peripheral Data Purpose: To transfer data to or from a peripheral Flags affected: X N Z V C Notes: This instruction has been specially designed for communication with devices which have been originally designed to work with 8-bit microprocessors. Purpose: Copies immediate data to a specified data register Flags affected: X N Z V C - Y Y 0 0 Notes: This instruction provides a quick (efficient) way to set a data register to a particular value which can be from -128 to +127 decimal. Most 68000 assemblers, given an immediate addressing move instruction, will generate moveq instructions where possible. For example: Before After moveq #$58,dO dO=ffffffff d0=00000058 Mnemonic: PEA - Push Effective Address Purpose: Pushes an address onto the stack Addressing Modes: Source Destination Data register direct Address register direct X Address register indirect Postincrement register indirect Predecrement register indirect Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate Flags affected: X N Z V C Notes: This instruction is often used to write position independent code. It provides a function similar to moved <ea>,-(a7). For example: pea (a6) Before a6=12345678 a7=44444444 After a6=12345678 a7=44444448

Mnemonic: SWAP - Swap Register Halves Purpose: Exchanges upper and lower halves of a data register Flags affected X N Z V C - Y Y 0 0 Notes: This instruction does exactly what you’d expect. For example: Before After swap dO d0=12345678 d0=56781234 Flow Control Instructions These instructions, as you will see from the main text, enable a programmer to create loops, if-then-else and case structure decisions and subroutines. They work by altering the contents of the program counter.

Mnemonic: Bcc - Branch Conditionally Purpose: Transfers program control using relative addressing Flags affected X N Z V C Notes: The branch data sizes may be byte or word so these instructions can branch in an area of 32K. When using a branch with a byte offset you can in fact put a .s (for short) suffix behind the instruction (eg beq.s HERE). Similarly when using a branch with a word offset you can use a .w suffix (eg beq.w HERE). Most assemblers will determine if the short or word form is needed automatically and will optimise word-branches to byte-branches whenever it is possible. These instructions test a combination of the NZVC flags in the status register and conditionally perform a branch to another address. If the testing of the condition codes is true, then the branch is taken, otherwise the instruction immediately following the bcc instruction is executed. Fourteen variations of this instruction are available and a related bra (branch always) instruction adds another condition to the testable set : bcc: where cc stands for carry clear. The branch is taken if the carry © bit is 0. This instruction is often used in combination with shift and rotate operations. bcs: where cs stands for carry set. The branch is taken if the carry © bit is 1. beq: where eq stand for equal. The branch is taken if the zero (Z) bit is 1. This instruction, as we’ve seen many times within this book, is frequently used after tst and cmp type instructions. bne: where ne stands for not equal. The branch is taken if the zero (Z) bit is 0. This instruction is of course the opposite of beq. bpl: where pi stands for plus. The branch is taken if the negative (N) bit is 0. bmi: where mi stands for minus. The branch is taken if the negative (N) bit is 1. bvc: where vc stands for overflow clear. The branch is taken if the overflow (V) bit is 0. This instruction is often used in conjunction with arithmetic instructions like add, mul, and so on. bvs: where vs stands for overflow set. The branch is taken if the overflow (V) bit is 1. bge: where ge stands for greater or equal. The branch is taken when the negative (N) and overflow (V) bits contain the same value. bgt: where gt stands for greater than. The branch is taken in cases where either N=l, V=1 and Z=0 or N=V=Z=0. ble: where le stands for lower or equal. This branch is taken in cases where Z=1 or the N and V bits contain different values. bit: where It stands for less than. This branch is taken if the negative (N) and overflow (V) bits contain different values. bhi: where hi stands for higher. This branch is taken if the negative (N) and overflow (V) bits contain the same value. bis: where Is stands for lower or same. This branch is taken if the carry © and zezo (Z) bits contain different values. bra: branch always - this instruction is commonly seen at the end of a loop to force control back to the top of the loop. Mnemonic: DBcc - Test Condition, Decrement and Branch Purpose: An automated decrement and branch loop instruction Flags affected X N Z V C ----- Notes: First the condition is tested and if satisfied the branch is not taken. Otherwise the specified data register is decremented and the branch only taken if Dn is -1. Data sizes may be byte or word so the instructions will branch in an area of up to 32K, thus providing an efficient way of creating many loops. There are 16 possible condition variations of this instruction and these are as per the bcc instructions except for the following two additions. dbf or dbra: An unsatisfiable condition allows the programmer to force a loop to only be terminated when the count value reaches -1. dbt: Only performs a decrement on the specified data register. It never branches. Chapter Three contains a discussion of this group of instructions.

Mnemonic: BSR - Branch to Subroutine Purpose: Transfers program control to a subroutine Flags affected X N Z V C ----- Notes: See jsr notes below Mnemonic: JSR - Jump to Subroutine Purpose: Transfers program control to a subroutine Addressing Modes: Source Destination Data register direct Address register direct Address register indirect X Postincrement register indirect Predecrement register indirect Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate Flags affected: X N Z V C Notes: The bsr (branch to subroutine) and jsr (jump to subroutine) instructions are used for calling subroutines. The bsr form is a relative branch with a range of 32K. For subroutine calls beyond this range the jsr instruction should be used but, having said that, most assemblers would optimise jsr to bsr when possible because bsr is more efficient. When executing a bsr/jsr instruction, the 68000 pushes the program counter on the stack and then reloads it with the target address. Purpose: Transfers control to a stack-retrieved address Flags affected: X N Z V C Notes: In a sense this is the counterpart of the bsr/jsr instructions because it reloads the program counter register with the value on top of the stack. This value will usually have been put there by a bsr or jsr instruction.

Mnemonic: JMP-Jump Purpose: Transfers program control to a specified address Addressing Modes: Source Destination Data register direct Address register direct Address register indirect X Postincrement register indirect Predecrement register indirect Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate Flags affected: X N Z V C Notes: This instruction is a variant of the move instruction but in this case the destination register, namely the program counter, is inherently defined. You could therefore just as easily use move.l (ea>,PC instead of jmp <ea>. Purpose: Retrieves condition codes from stack and then transfers control to a stack-retrieved address Flags affected: X N Z V C Y Y Y Y Y Notes: Similar to RTS but with rtr the condition codes are reloaded from the stack. This instruction comes in handy when the programmer doesn’t want a subroutine to influence the condition codes. Before the jsr instruction you need to do a move.b ccr,-(a7) which pushes the ccr on the stack. Logical Operations

Mnemonic: AND - AND Logical Purpose: Performs a boolean bitwise AND from source to destination and stores result in destination Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C - Y Y 0 0 Notes: There are two forms of this instruction. The above version uses a data register as the destination and all addressing modes except address register direct are allowed for the source. The second form uses a data register as the source. For example: Before After and.b d0,d1 d0=33333333 d0=33333333 d1=ffffffff d1=ffffffcc

Mnemonic: AND - AND Logical Purpose: Performs bitwise AND from a data register to a destination storing result in the destination Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C - Y Y 0 0

Mnemonic: ANDI - AND Immediate Purpose: Bitwise AND of immediate data source with destination Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate X Status register X Flags affected: X N Z V C - Y Y 0 0 Notes: In addition to the more conventional register and memory usage the destination may be the condition codes or the whole of the 68000 status register. In the latter case the instruction is privileged. For example: Before After d0=9999aaaa andi.b #7,d0 d0=9999aaa0

Mnemonic: EOR - Exclusive OR Logical Purpose: Performs bitwise Exclusive-OR from a data register to a destination storing result in the destination Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C - Y Y 0 0 Notes: This instruction, unlike the AND and OR instructions, can only take a data register as the source. For example: eor.l d4,d5 Before d4=ffffffff d5=fOfOfOf0 After d4=ffffffff d5=0f0f0f0f

Mnemonic: EORI - Exclusive OR Immediate Purpose: Bitwise Exclusive-OR of immediate data source with destination Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate X Status register X Flags affected: X N Z V C - Y Y 0 0 Notes: Destination may be condition codes or the whole of the 68000 status register. In the latter case the instruction is privileged. For example: Before After eori.b #$ff,d6 d6=eeeeee30 d6=eeeeeecf

Mnemonic: NOT - Logical Complement Purpose: Performs a bitwise complement of an operand Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C - Y Y 0 0 Notes: The instruction not.w An has the same effect as: eori.w #$ffff,An.

Mnemonic: OR - Inclusive OR Logical Purpose: Performs bitwise OR from source to a data register Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C - Y Y 0 0 Notes: There are two forms of this instruction. The above version uses a data register as the destination and all addressing modes except address register direct are allowed for the source. For example: Before After or.l d0,d1 dO=ffffffff dO=ffffffff d1=33333333 d1=ffffffff

Mnemonic: OR - Inclusive OR Logical Purpose: Performs bitwise OR from data register to destination Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C - Y Y 0 0 Mnemonic: ORI - Inclusive OR Immediate Purpose: Performs bitwise OR using immediate data source Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate X Status register X Flags affected: X N Z V C - Y Y 0 0 Notes: Destination may be condition codes or the whole of the 68000 status register. In the latter case the instruction is privileged. For example: Before After ori.b #ff,d0 dO=efefefef dO=efefefff Shift and Rotate Operations A whole range of logical and arithmetic shifts and rotate instructions are available on the 68000 processor. The following examples are just a selection.

Mnemonic: ASL - Arithmetic Shift Left in Data Register Purpose: Left shifts the contents of a data register Flags affected: X N Z V C Notes: This instruction arithmetically left shifts the contents of the data register so that the carry © and extend (X) flags receive the last bit shifted out. The shift count may be specified either by another data register or by immediate data and, in the latter case, a shift count in the range 1-8 may be specified. When a data register is used, counts in the range 0-63 are allowed. ASL instructions can be used as a fast form of multiplying an operand by a power of two. The lower bit of the destination is always set to zero. For example: Y Y Y Y Y asl.l #4,d1 Before d1=0000000f After d1=000000f0

Mnemonic: ASL - Arithmetic Shift Left in Memory Purpose: Left shifts the contents of a memory location Addressing Modes: Source Destination Data register direct Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C Y Y Y Y Y Notes: This form of the instruction is restricted to a one-bit shift and can only be used for word sized operands.

Mnemonic: ASR - Arithmetic Shift Right Purpose: Right shift contents of data register or memory Addressing Modes: Two versions as per ASL Flags affected: X N Z V C Y Y Y Y Y Notes: This instruction arithmetically shifts the bits of the operand to the right and, as with the ASL instruction, two forms exist. One version allows an operand in a data register to be shifted by a count value specified either in a data register or as immediate data, the second version allows a one-bit shift of a word operand contained in memory.The shifted out low-order bit goes into the carry © and extend (X) flags and, at the other end of the operand, the sign bit is always repeated. ASR can be used as a fast form of dividing an operand by a power of two. I Mnemonic: LSL - Logical Shift Left Purpose: Left shift contents of data register or memory Addressing Modes: Two versions as per ASL Flags affected: X N Z V C Y Y Y Y Y Notes: This instruction is identical to ASL and likewise exists in two forms.

Mnemonic: LSR - Logical Shift Right Purpose: Right shift contents of data register or memory Addressing Modes: Two versions as per ASL Flags affected: X N Z V C Y Y Y Y Y Notes: This instruction also exists and is similar to ASR except for the fact that the high-order bit is always cleared, so zeros are fed in rather than the sign bit being duplicated. Bit Manipulation Instructions

Mnemonic: BTST - Test a Bit Purpose: Tests an operand bit and sets zero flag accordingly Addressing Modes Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C - - Y - -

Mnemonic: BCLR - Test a Bit and Clear Purpose: Tests bit, sets Z flag accordingly, and then clears bit Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate X Flags affected: X N Z V C - - Y - - Mnemonic: BSET - Test a Bit and Set Purpose: Tests bit, sets Z flag accordingly, and then sets bit Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate X Flags affected: X N Z V C - - Y - -

Mnemonic: BCHG - Test a Bit and Change Purpose: Tests bit, sets Z flag accordingly, then inverts bit Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate X Flags affected: X N Z V C - - Y - - Arithmetic Instructions

Mnemonic: ADD - Add Binary Purpose: Add source operand to data register destination Addressing Modes: Source Destination Data register direct X X Address register direct X* Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C Y Y Y Y Y Notes: Address register direct addressing is not allowed for byte size operations. Two forms of the instruction are available. For example: Before After add.w do,d2 d0=00000011 d2=0000FFFA XNZVC=00000 d0=00000011 d2=OOOOOOOB XNZVC=11001

Mnemonic: ADD - Add Binary Purpose: Add data register to destination operand Addressing Modes: Source Destination Data register direct X X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C Y Y Y Y Y

Mnemonic: ADDA - Add Address Purpose: Add source operand to an address register Addressing Modes: Source Destination Data register direct X Address register direct X X Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C Notes: This operation does not change any of the condition code values. For example: Before After adda.l a3,a3 a3=00000002 a3=00000004

Mnemonic: ADDI - Add Immediate Purpose: Add immediate data to specified operand Flags affected: X N Z V C Y Y Y Y Y Notes: This instruction has exactly the same characteristics as the ADD using a data register source instruction, except that immediate addressing is used to specify the source (ie the source must be a constant).

Mnemonic: ADDQ - Add Quick Purpose: Add data specified in instruction code to operand Flags affected: X N Z V C Y Y Y Y Y Notes: Similar in effect to ADD1 but the value is built into the instruction code itself. The immediate values in the source field are restricted to the range 1 to 8. This instruction is the fastest way to add a number between 1 to 8 to a destination operand. Additional notes on ADD, ADDI, ADDQ: Most assemblers will optimise your code automatically and so if, for example, you write: add #1,Dn the assembler will translate it automatically to: addq #1,0n thus reducing the size of the object code and saving a few clock cycles of execution time.

Mnemonic: CLR - Clear and Operand Purpose: Sets specified register or memory location to zero Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C - 0 1 0 0 Notes: You cannot use clr to clear an address register but most assemblers allow instructions like clr aO to be written and then substitute a sub.l instruction which has the same effect (sub.l aO,aO in the case of clr aO). For example: clr.w dO Before dO=bbbbbbbb NZVC=1011 After d0=00000000 NZVC=0100

Mnemonic: CMP - Compare Purpose: Compares operand with a data register and sets flags Addressing Modes: Source Destination Data register direct X X Address register direct X Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C - Y Y Y Y Notes: CMP is a subtraction instruction which affects only the condition codes. For example: Before After cmp.l d2,d3 d2=00000001 d3=00000002 NZVC=1111 d2=00000001 d3=00000002 NZVC=0000

Mnemonic: CMPA - Compare Address Purpose: As CMP but uses an address register as destination Flags affected X N Z V C - Y Y Y Y Notes: This instruction differs only from CMP in that the second operand is an address register and that the data size cannot be byte. Mnemonic: CMPI - Compare Immediate Purpose: As CMP but compares against immediate data Flags affected : X N Z V C - Y Y Y Y

Mnemonic: CMPM - Compare Memory Purpose: Compares contents of two memory locations Flags affected X N Z V C - Y Y Y Y Notes: Similar to CMP, but both the source and destination operands must use postincrement addressing. This instruction is used to compare areas of memory. Additional note on all CMPx instructions. Most assemblers accept instructions like: cmp.w (a0),(a1) and: cmp.l #3,dO

Mnemonic: DIVS - Signed Divide Purpose: Divides a 32 bit destination by a 16 bit source Flags affected X N Z V C - Y Y Y 0 Notes: This instruction performs a division between two signed numbers. The destination register is always a long word and the source operand is always a word. After the division, the destination operand contains the result. The quotient is always in the lower word and the remainder is always in the high order word of the data register!

Mnemonic: DIVU - Unsigned Divide Purpose: Divides a 32 bit destination by a 16 bit source Flags affected: X N Z V C - Y Y Y 0 Notes: Nearly exactly the same as DIVS, only this time both operands are assumed to be unsigned.

Mnemonic: EXT - Sign Extend Purpose: Propagates the upper bit of a byte, word or long word Flags affected X N Z V C - Y Y Y 0 Notes: This instruction provides a convenient way to turn a word into a long word. If the high order bit of the data register is 0, so the data register is positive, zeros are padded in, otherwise ones are padded in. For example: Before After ext.w d5 d5=000000ff d5=0000ffff

Mnemonic: MULS - Signed Multiply Purpose: Multiplies two 16 bit operands Flags affected X N Z V C - Y Y 0 0 Notes: This instruction performs a multiplication of the source and destination operand, putting the result in the destination operand.

Mnemonic: MULU - Unsigned Multiply Purpose: Multiplies two 16 bit operands Flags affected X N Z V C - Y Y 0 0 Notes: Similar to MULS, only both operands are assumed to be unsigned.

Mnemonic: NEC - Negate Purpose: Subtract from zero using two’s complement arithmetic Flags affected X N Z V C Y Y Y Y Y Notes: Negate an effective address operand. In a high level language this might look like this: X = -X. For example: Before After neg.l d5 d5=00000001 d5=ffffffff

Mnemonic: SUBQ - Subtract Quick Purpose: Subtract data specified in instruction code Flags affected X N Z V C Y Y Y Y Y Notes: Similar in effect to SUBI but the value is built into the instruction code itself. The immediate values in the source field are restricted to the range 1 to 8. This instruction is the fastest way to subtract a number between 1 to 8 from a destination operand. Additional notes on SUB, SUBI, SUBQ: Most assemblers will optimise your code automatically and if, for example, you write: sub #1,Dn the assembler will translate it automatically to: subq #1,Dn thus reducing the size of the object code and saving a few clock cycles of execution time.

Mnemonic: SUB - Subtract Binary Purpose: Subtract source operand from data register destination Addressing Modes: Source Destination Data register direct X X Address register direct X* Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C Y Y Y Y Y Notes: Address register direct addressing is not allowed for byte size operations. Two forms of this instruction exist.

Mnemonic: SUB - Subtract Binary Purpose: Subtract data register from destination operand Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C Y Y Y Y Y

Mnemonic: SUBI - Subtract Immediate Purpose: Subtract immediate data from specified operand Flags affected X N Z V C Y Y Y Y Y Notes: This instruction, except for the fact that subtraction is involved, has exactly the same characteristics as the ADDI instruction.

Mnemonic: SUBA - Subtract Address Purpose: Subtract source operand from an address register Addressing Modes: Source Destination Data register direct X Address register direct X X Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement X PC relative with index X Immediate X Flags affected: X N Z V C Notes: This operation does not change any of the condition code values.

Mnemonic: TAS - Indivisible Test and Set Purpose: Test operand, set flags, then set the high-order bit Flags affected X N Z V C - Y Y 0 0 Notes: This instruction should not be used in Amiga programs because it can conflict with the Amiga’s DMA (direct memory access) operations.

Mnemonic: TST - Test an Operand Purpose: Test an operand and set status flags accordingly Addressing Modes: Source Destination Data register direct X Address register direct Address register indirect X Postincrement register indirect X Predecrement register indirect X Register indirect with displacement X Register indirect with index X Absolute Short X Absolute Long X PC relative with displacement PC relative with index Immediate Flags affected: X N Z V C - Y Y 0 0

In addition to the instructions outlined in this chapter the 68000 includes many other specialist instructions including binary coded decimal (BCD) operations, a range of supervisor-mode-only commands(privileged instructions) and trap generating and handling instructions. Please consult the official 68000 literature for details.

Functions are the subprogram units which form the essential building blocks of all C programs. You don’t have to write functions for everything you need to do in C - many functions come pre-written with the compiler or as part of the computer’s operating system.

C functions, when properly written, make ideal program building blocks. They behave in many ways just like a black box - the user provides some input, called parameters or arguments, and the function carries out its job, possibly returning some information. The basic C syntax for a function call looks like this:

return-type function-name ( parameter list ) { variable declarations C statements which specify what the function does

} Here’s a simple example which calculates the area of a rectangular box:

int BoxArea(int width, int length) { int result; result=width*length; return(result); }

You wouldn’t normally write such a trivial calculation as a function, but if you were going to, this shortcut form would also be allowed:

int BoxArea(int width, int length) { return(width‘length) }

Functions can call other functions and, if suitably written, can also call themselves. In other words, C supports recursion!

In C //conditional testing takes this form: if (expression) statement The statement which gets executed can either be a single C statement or a group of statements enclosed within braces like this:

if (expression) { any number of statements }

Both syntax forms operate in the same way - the expression enclosed in parenthesis is evaluated and, if it’s true, the statement or statements which follow are executed. For example the statement:

if (exit_flag==TRUE) closedown();

has this effect. The variable exit_flag is tested and if the condition is true, which in C means it has evaluated to a non-zero value, then the function closedownO is called.

C also provides an if-else extension whose formal syntax is:

if (expression) statement 1 else statement 2 Again the statement parts may be either single statements or blocks of statements placed in braces, for example: if (keypress==ESCAPE) /* user wants some help */ { PreserveScreen(); DisplayMesage(); GetCharacter(); RestoreScreen(); } else { HandleCharacter(keypress); }

C provides the case structure construct, although it calls it a switch statement. This allows you to test an expression and then, on the basis of the result, carry out any number of code sections. The general form looks like this:

switch (expression) { easel constant-expression: statement case2 constant-expression: statement case3 constant-expression: statement caseN constant-expression: statement default: statement }

Again the sections of code can be either a single statement or a bracketed block of statements. The only limitation is that the expressions used to identify the individual cases must be integers.

As written the switch statement does not execute a particular set of statements and then return control to the program, execution falls through to other case sets. The way to avoid this is to use C’s break statement which effects an immediate exit from the switch statement. So, although not specified in the syntax, the most useful description of the switch construct is this:

switch (expression) { easel constant-expression: statement break; case2 constant-expression: statement break; case3 constant-expression: statement break; } caseN constant - expression: statement break; default: statement break;

The while loop uses this type of format:

while (expression) statement

As before the statement part may consist of either a single C statement or a block of statements enclosed in braces:

while (expression) { any number of statements }

C’s equivalent of the common for loop adopts a most useful arrangement: for (entry-expression; exit-expression; continuation-expression) statement Again the statement part may consist of either a single C statement or a block of statements enclosed in braces. The parenthesised conditions are most usually assignment statements and conditional tests. The first part specifies the entry conditions, the second (commonly a conditional test) is evaluated before the body statements are executed, and the third part is usually an assignment which controls (increments or decrements) a loop variable.

An alternative C construct, a do-while loop, is also supported. Here the condition test is made at the end of the loop. As before braces are unnecessary for the single statement form, so the following two versions are acceptable:

do statement while (expression); and: do { any number of statements } while (expression);

Notice that, unlike the control statements mentioned earlier, a semicolon must follow the parenthesised expression.

Data items used within a C program fall into two basic categories -constants and variables. C allows four fundamental type specifiers:

char a single byte capable of holding one character. int an integer, usually reflecting the natural size of an integer on a given computer/processor. float a single precision floating point number. double a double precision floating point number.

And to these a number of qualifiers can be applied:

short applies to int type only. long applies to int type only. unsigned applies to int or char types. signed applies to int or char type.

The exact number of bits which must be used to represent particular data types aren’t specified by the language, they are determined by the underlying hardware of the machine and are therefore hardware dependent. On the Amiga for instance a long int is a 32-bit number, a short only 16-bits. Character char variables contain 8-bits.

The intention is that these qualifiers offer additional flexibility. If, for instance, we were dealing with a variable that we were certain would never hold values greater than 255 we could declare it as an unsigned char and the compiler would realise that the item will never require more than 8 bits of storage and would allocate memory accordingly.

An integer constant is a whole number which may be positive, zero or negative. In C they may be specified using decimal, octal or hexadecimal (hex) notation.

The only restriction which C places on decimal integer constants is that they must not start with a 0 (zero). 999 and -126 are decimal constants. 016 is not! Why the restriction? It’s because numbers which start with zeros are regarded as octal numbers, ie they’re assumed to be base 8 numbers. Octal numbers must of course only contain the digits 0-7. Numbers which start with the characters Ox (or OX) signify a hexadecimal, ie base 16, number. These may consist of the digits 0-9 and the letters A-F (or a-f) inclusive. Hex numbers are very useful as a concise way of representing bit patterns, masks for logical operations etc.

Integer constants can be written with a qualifier. A decimal, octal or hex number followed by L, indicates a long integer, U indicates an unsigned int.

In C floating point constants can be written in one of two ways - as decimals or in scientific, exponential, form. The latter scheme involves writing the number as either a floating point number or integer, adding the letter E, and then following that with an integer representing the appropriate power of 10.

Character constants in C are single characters written within single quote marks, 'B', 'd', 7','%' etc. The value of the constant is the numeric value of the character in the machine’s character set. These are not to be confused with the equivalent integer numbers. The ASCII character 0 (zero) for instance, which can be written as as the constant ‘O’, is represented internally by the numerical value 48, not by a zero value. Equally important is the fact that, on a machine which used a different character set, ‘0’ would (as represented internally) be yet a different value again.

C allows a number of escape sequences to be used:

\a alert (bell) \b backspace \f formfeed \n newline \r carriage return \t horizontal tab \v vertical tab \\ backslash \? question mark \' single quote \" double quote

As well as the above sequences, byte-sized bit patterns can also be specified, \ooo, where ooo is an octal number x\hh is the hexadecimal equivalent. The ASCII space character could therefore be defined using the definition:

#define BELL '\x20‘

One constant that crops up very frequently is the ‘\0’ character. Its internal numerical value is zero and it is commonly known as the null character. String Constants A string constant is written as a sequence of characters enclosed in double quotes thus: "some string" Such constants can be concatenated at the time the program is compiled so it is legal to spread such strings over a number of lines if necessary. Internally all strings terminate with a null character, ie with ‘\0’. This is a C language requirement and it means that if, for instance, you write an eleven character string "some string” it will be stored using 12 locations. Identifiers C requires that various quantities, such as variables and constants, are given names in order that they can be referenced within the program. These names, which are called identifiers, can be made up of letters, digits and _ the underscore character. The only proviso is that the name must not start with a number. Identifiers are case sensitive and C programmers, because of a long established convention, tend to write all symbolic constants in uppercase. It is worthwhile maintaining this convention. Arithmetic Operators C supports all of the normal arithmetic operations, addition (), subtraction (-), multiplication (*) and division (/). C also provides the % operator which is a modulus function. The expression x % z for instance gives the remainder after x has been divided by z. Relational Operators C offers the following relational operators: > greater than >= greater than or equal to < less than == equal to != not equal to Notice that equality uses a double == sign. Assignment and the Assignment Operators Assignment itself, as we’ve just mentioned, uses a single = sign. Its simplest use is in statements which take the following form: variable = some expression or value For assignments such as: area = area + 40; C allows a shortcut . The above expression can be written as: area += 40; Most binary operands, namely +, -, *, /, %, «, », &, a, and | can be used in this way. C’s Increment and Decrement Operators C provides two very useful operators for incrementing and decrementing variables. Operations such as y = y + 1 can be written as: y; /* this means add 1 to the value of y */ Similarly y = y - 1 can be written: y-; It’s also possible to control when the increment/decrement operation will occur. There are post-increment and pre-increment modes available: y = x; x is incremented after the righthand side expression is evaluated and assigned. y = x; x is incremented before the righthand side expression is evaluated and assigned. Type Conversions If an operator like * or + is used with operands of different types then the less precise operand will usually be promoted to the same type as the most exact operand for the purposes of the calculation. The above type of conversion is called implicit type conversion. C also allows the programmer to explicitly change types, providing of course that it is sensible to do so. Bit Manipulation Operators C was originally designed as a systems programming language and because of this, it was given quite a few operators that can act on the individual bits of an integer operand. Category Symbol Name Bitwise Operators unary one's complement & bitwise AND 1 bitwise inclusive OR A bitwise exclusive OR Shift Operators << left shift >> right shift The unary one’s complement operator will turn all the Is present in the binary form of an integer into Os, and all positions that were originally Os are converted to Is. Bitwise AND is most often used to mask out a particular bit pattern, ie to turn off certain bits of the number. If, for instance, the #define statement defines a constant called BITMASK as: #define BITMASK 0x7FFF then the expression: x = x & BITMASK; results in the most significant bit of the x variable being set to zero. Similarly bitwise OR can be used to turn bits on. For instance, the expression: x = x | BITMASK; is an assignment which will set to 1 all of the bit positions in x which are set to one in the constant called BITMASK. These types of operations, particularly in systems programming, are very common so the shortcut notation which C’s assignment operators provide are very useful. The expression x = x & BITMASK for instance can simply be written more concisely as: x & = BITMASK; The bitwise exclusive OR operator a performs the standard exclusive OR operation. Every bit position where the two operands have different values will be set to 1, bits in other positions are set to zero. Shift operators perform left and right shifts of their specified operands by a number of bits specified on the right of the operand, The expression: x = x << 4; shifts the contents of x four positions to the left. Logical Operators The operators && and || are known as C’s AND and OR logical operators. Expressions connected by these operators are evaluated from left to right to see whether they are true or not. By definition the numeric value of a relational or logical expression is unity if the expression is true, and zero if it is false. A unary negation operator ! is also available which converts a non-zero operand into a zero operand and vice versa. Precedence The C language gives operators a precedence and in cases where operators of equal precedence have to be resolved it defines whether evaluation occurs on a left to right or a right to left basis. The following table gives the details of all of the C operators: Operators PRECEDENCE TABLE Associativity o n -> • left to right 1 - --* & (type) sizeof right to left * / % left to right + - left to right << » left to right II A A II V V left to right == ! = left to right & left to right left to right I left to right && left to right II left to right ? : right to left = = -= *= /= %= &= A= |= «= »= right to left , left to right The C Preprocessor One of C’s greatest strengths is that it offers a user programmable pre-processing stage. Prior to the start of compilation proper the source file is scanned for special preprocessor directives and these can be used to modify the source code. In general the preprocessor can perform three basic jobs: file inclusion, macro substitution and conditional compilation. The syntax of the preprocessor is quite separate from C. To start with, all preprocessor directives (ie preprocessor commands) must start with a hash # sign. The restrictions on the layout are also stricter than the C language itself. Pointers and Address Related Operators C allows you to work with pointers which represent memory addresses. The declaration: char *buffer_p; declares a variable called buffer_p as being a pointer to a char type item. An address of operator & is also available. Complex Variables The C language supports arrays of all types using separate square brackets for individual dimensions. It also allows variables of different types to be collected together into a unit known as a structure. For instance: struct Date { long int Day; long int Month; long int Year; }; Such structures may be copied or assigned as complete units, their addresses may be taken and their individual members can be accessed, copied and assigned. ANS1I C allows a structure to be passed to a function as a complete unit, and it allows the function to return a complete structure. C has a special notation for working with structure pointers, the -> operator. If p is a pointer to a structure then one of its members can be accessed with this type of statement: p->MemberName; If date_p is a pointer which has been declared as a pointer to the Date structure described earlier, ie as: struct Date *date_p; then the individual structure members could be initialised to represent 1st January 1992 using the statements: date_p->Day=1; date_p->Month=1; date_p->Year=92; Standard Input and Output (I/O) Functions The C language itself doesn’t actually have any inbuilt I/O facilities. What it does have is a standard library which provides a set of functions that, amongst other things, offer I/O and string handling. Nowadays ANSI C defines this library quite precisely so no matter what compiler, machine or operating system you are using you’ll find these functions available. As far as I/O goes, the C library adopts a very simple model for character I/O based on the idea of a text stream. A text stream is essentially a sequence of text lines, each of which ends in a newline character. If the system uses some other end-of-line character then, during I/O operations, the appropriate conversions are made transparently. Associated with such operations is the idea of a standard input and standard output, places from which input can be received and output sent. On the Amiga for instance a CLI program, unless otherwise directed, receives its input from the keyboard and returns its output back to the CLI. This happens because C’s standard I/O handles, called stdin and stdout, have been set up to achieve this. getchar() This routine reads one character from the standard input device. Since it collects single characters you might expect it to be used like this: unsigned char keypress; /* DON’T COPY - THIS IS WRONG */ keypress=getchar(); Somewhat surprisingly this isn’t the case. As well as returning all 256 possible eight bit characters getcharQ, since it may be reading from a file, also has to be able to return an end-of-file (EOF) indicator. On the Amiga this is defined like this: tfdefine EOF (-1). The net result is that we need a type larger than char and so int is used. The prototype for getcharQ is therefore: int getchar(void); which just says that the function works without you specifying any parameters and that it provides you with an int sized object. Its correct use therefore would be as in: int keypress; keypress=getchar(); In many environments, including the Amiga, it is possible to redirect these I/O streams. If a program is getting its data using getcharO then typing something like: test <RAM:inputfile will tell the test program to collect its input from a ram file called inputfile. This switching occurs via AmigaDOS’s re-direction options and is totally transparent to the program itself. Although getcharO is always called a function it is, like many library functions actually a macro. The compiler inserts the necessary code in-line rather than generating conventional function call code. The getcharQ implementation, which we are not going to discuss, is actually made in terms of a lower-level macro called getcQ. putchar() This is the corresponding single character standard output routine. It’s another macro and, like getcharQ, is defined in terms of a lower-level function. The function prototype looks like this: int putchar(int); so you have to supply an int value. If you don’t you will find that the compiler complains bitterly. Programs using getcharQ can, incidentally, also use re-direction. printf() We have already come across a printfO type function in Chapter 12 so now we can fill in some extra details. To start with the function uses this general arrangement: printf(pointer-to-format - string, argumentl, argument2,... argumentN) The format string can contain two types of objects: ordinary characters, which are sent to the standard output unchanged, and special control fields which are groups of characters starting with the % sign. This arrangement means that if there are no control groups present the format string will be printed as just an ordinary string. This is why it is possible to use: printf("just an example"); instead of: printf("%s“, "just an example"); One word of warning here. With string literals, such as the above, you will know what the string contents are. You sometimes see programmers using the shortcut version with ordinary strings, ie writing: printf(text_p); instead of: printf("%s", text_p); Don't do it, unless you can be 100% sure that the string being pointed to will never contain a % percent character. A conversion command will end with any one of a number of characters which, for printfO, have special significance. Here are some examples: d»i prints an int decimal number 0 prints an int unsigned octal number (no leading zero) x, X prints an int unsigned hex number u prints an int unsigned decimal number c prints a single int character s char * prints s string f prints a double number e,E prints a double in exponential form o, o prints a % sign A number of other characters can be included between the % sign and the group terminator. A minus sign indicates left adjustment of the argument. A number specifies the minimum field width. A period is used to separate the field width from a number which specifies the maximum number of characters to be printed, the number of digits after the decimal point of a floating point number, or the minimum number of digits for an integer. One useful printfO characteristic is that the width or precision can be specified as an argument itself (of type int) by using an asterisk. (*). The looped example: for (length=1;length<=4;length+) { printf("%s\n",length, "test"); } would produce the output: t te tes test As you’ll probably realise, printfO uses its first argument to decide how it must handle the other arguments it encounters. It will fail miserably if you mislead it by providing an inappropriate, or otherwise incorrect, format string. Another point worth mentioning is that, although rarely used, printfO does return information to the user - an int value representing the number of characters generated by the function. The printfO function has many other options. You will find detailed discussions in your compiler manual along with other related functions such as sprintfO. Warning: The above discussion outlines C’s printfO function. You should be aware that the version provided in the amiga.lib linker library, ie that used in Chapter 12 is not as sophisticated. The main difference is that it does not support the use of floating point numbers! scanf() Just as putcharO had a complementary getcharO routine, so printfO has a corresponding data collection function. It’s called scanf() and it adopts similar conventions to printfO for its format descriptions and has this arrangement: int scanf(char *format-string, list of pointer arguments) scanf() reads characters from the standard input. As it does so it translates them according to the format string which has been provided. The big difference to watch for is that scanf() expects not the arguments themselves but pointers to them. Why? It’s because scanfO isn’t interested in their values. It wants to know where they are so it can store data in them. scanfO stops prematurely if it encounters errors returning a zero value to the caller. If all goes well scanfO will return a positive number indicating the number of input items successfully matched. The format string can contain printable characters and these are then expected to match the next item in the input stream. It can also contain conversion characters which again will be detailed in your compiler manual along with other related functions such as scanf(). Format string options which are available include the following: d pointer to i pointer to u pointer to s pointer to e,f ,9 pointer to an int decimal number an int octal or hex number an unsigned int decimal number a char character a floating point number Examples Here are a couple of versions of a short program which asks the user to type something and then prints their response back at the CLI. First the quick and dirty version: #include <stdio.h> main() { char user_input[129]; / Allow for 128 characters plus a NULL */ printf(“Please type something\n); scanf(“%128s", user_input); printf(“You typed…​ %s\n", userinput); } There is nothing seriously wrong with this code - at least a check has been made to ensure that scanfO does not exceed the space set aside for the user’s response. A few improvements could however be made by using #defines to remove the embedded numeric and string constants like this: #include <stdio.h> #define MAX_SIZE #define INPUT_FORMAT_STRING #define INPUT_MESSAGE #define OUTPUT_FORMAT_STRING main() 128 "*s128s" "Please type something\n "You typed…​ %s\n" { char user_input[MAX SIZE+1 ]; printf(INPUT_MESSAGE); scant(INPUT_FORMAT_STRING, user_input); printf(OUTPUT_FORMAT_STRING, user_input); }

As you have probably realised, C is both a powerful and flexible high-level language. To start writing C programs on the Amiga you will of course need a C compiler but the good news here is that a number of reasonable public domain C compilers exist so nowadays you can start C programming for just a few pounds. You’ll find a number of C books listed in the bibliography.

The tables in this appendix provide library vector offset values and register usage details for some commonly used Amiga library functions, many of which have been used in the programs of this book. The term void in the following descriptions indicates that no return value is supplied. For full details of all libraries and their available functions you should consult the official Amiga documentation.

DOS Functions LVO offset _LV00pen -30 file(dO) = Open(name.mode) (dl,d2) _LVOClose -36 voidQ = Close(file) (dl) _LVORead -42 collected(dO) = Read(file,buffer,length) (d 1 ,d2,d3) _LVOWrite -48 written(dO) = Write(file, buffer, length) (dl ,d2,d3) .LVOLock -84 lock(dO) = Lock(name,type) (dl,d2) .LVOUnLock -90 void() = Unlock(lock) (dl) _LVOExamine -102 success(dO) = Examine(lock,info_block) (d 1 ,d2) _LVOExNext -108 success(dO) = ExNext(lock,info_block) (dl,d2) _LVODeIay -198 voidO = Delay(time) (dl) Exec Functions _LVODisabie -120 voidO = Disable!) () _LVOEnable -126 voidO = Enable!) () _LVOForbid -132 voidO = ForbidO () _LVOPermit -138 voidO = PermitO 0 _LVOAddIntServer -168 voidO = AddIntServer(number,interrupt) (d0,al) _LVORemIntServer -174 voidO = RemlntServer(number, interrupt) (dO.al) _LVOAllocMem -198 block(dO) = AllocMem(size,type) (d0,dl) _LVOFreeMem -210 voidO = FreeMem(block,size) (al,d0) .LVOWait -318 signals(dO) = Wait(signals) (dO) _LVOGetMsg -372 message(dO) = GetMsg(port) (aO) _LVOReplyMsg -378 voidO = ReplyMsg(message) (al) _LVOWaitPort -384 message(dO) = WaitPort(port) (aO) _LVOCloseLibrary -414 voidO = CloseLibrary(library) (al) _LVOOpenLibrary -552 base(dO) = OpenLibrary(name, version) (al.dO) Graphics Functions _LVORectFili -306 voidQ = RectFill(rastport,xl,yl,x2,y2) (a 1 ,d0,d 1 ,d2 ,d3) _LVOSetAPen -342 void() = SetAPen(rastport.pen) (a0,d0) _LVOSetBPen -348 voidO = SetBPen(rastport.pen) (aO.dO) intuition Functions _LVOClearMenuStrip -54 voidO = ClearMenuStrip(window) (aO) _LVOCloseScreen -66 voidO = CloseScreen(screen) (aO) _LVOCloseWindow -72 voidO = CloseWindow(window) (aO) _LVODisplayBeep -96 voidO = DisplayBeep(screen) (aO) _LVODrawBorder -108 voidO = DrawBoarder(rastport,border,x,y) (aO.al ,dO,d 1) _LVODrawImage -114 voidO = Drawlmage(rastport, image, x,y) (aO,a 1 ,dO,d 1) _LVOOpenScreen -198 screen(dO) = OpenScreen(new_screen) (aO) _LVOOpenWindow -204 window(dO) = OpenWindow(new_window) (aO) _LVOPrintIText -216 voidO = PrintIText(rastport,itext,x,y) (aO,a 1 ,dO,d 1) _LVOSetMenuStrip -264 success(dO)= SetMenuStrip(window.menu) (aO,al) Usage Notes The system macro LINKLIB is used to generate function call code in an easy-to-read, and conceptually tidy, fashion. An Intuition library OpenScreenQ call for instance might take this form: LINKLIB _LV00penScreen, _IntuitionBase and the instructions generated would be: move.l a6,-(sp) move.l _IntuitionBase,a6 jsr _LV00penScreen(a6) move.l (sp),a6 To create an executable program the _LVOOpenScreen reference must at some stage be resolved, ie the real value for it must be found. This may be done either at link time, via the LVO values present in amiga.lib, by using an include file which contains the appropriate LVO value, or by the programmer inserting a suitable EQUate within their program. Since the numerical LVO values are available from the system documentation, programmers are sometimes tempted to use the numerical equivalents directly. For instance, knowing that the _LVOOpenScreen reference is -198, a programmer could decide to code the above library opening fragment in one of these ways: 1) LINKLIB _LV00penScreen, _IntuitionBase 2) move.l a6,-(sp) move.l _IntuitionBase,a6 jsr _LV00penLibrary(a6) move.l (sp),a6 3) LINKLIB -198, _IntuitionBase 4) move.l a6,-(sp) move.l _IntuitionBase,a6 jsr -198(a6) move.l (sp)+,a6 The preferred approach is to use the LINKLIB macro, or an equivalent macro, but if you do write the code manually you should always use the LVO name and not the numerical value. There are two reasons for this. Firstly, the LVO name approach provides more readable code. Secondly, if Commodore-Amiga do ever change the existing function arrangements in a library then, providing you’ve used the LVO symbolic names, it would be possible to re-assemble/re-link your program with the new LVO data and it would work. This would not be possible if you had used numerical LVO equivalents in your code. In short you should avoid the style of the last two examples shown above!

Between April and June 1986 the Dr Dobbs Journal published the source for a 68000 cross assembler written in Modula 2 by Brian Anderson. Charlie Gibbs took these ideas, translated them into C, and used them as the basis for an Amiga assembler. After adding a great many enhancements, the package we now know as A68K was born! A68K is a freely distributable assembler that is available from almost all public domain libraries. It is found both as a separate package and as a component of a variety of public domain high-level languages. If, for example, you have a copy of Steve Hawtin’s NorthC compiler then you’ll find that you have A68K and Blink (and documentation files) in the bin directory of the main compiling disk. The code examples in this book were created initially using Devpac but the good news is that all of the programs can be assembled using other assemblers with little or no change. A68K however does require that source files contain an explicit END statement at the end of the source code so a small change is necessary before the examples listed in this book can be assembled using A68K. This is easily done and if you read the source file into any available ASCII text editor (ED or Memacs will do), move to the end of the text file and insert a terminal END statement as the last line of the source code you will then find that most of the examples will assemble without problem. With one or two examples, namely those that use the SECTION directive to ensure that graphics data gets placed in chip memory, another small change will be necessary. For A68K users the source code line: SECTION IMAGE,DATA_C which appears just before the graphics data itself will need to be changed to: SECTION IMAGE,DATA,CHIP The A68K and Blink usage options themselves are well explained in the associated document files (which are always distributed along with these programs) and for the examples in this book only simple command lines will be needed. If, for example, a source file called test.s is present in the RAM Disk and your include files are present in the include directory of the disk in dfO then the CLI/Shell command line to assemble the program test.s would be: a68k ram:test.s -oram:test.o -idfO:include This would produce in the RAM Disk an object file, test.o, which could subsequently be linked using Blink. In the simple case where no startup code or linker libraries were being specified the Blink command line: blink ram:test.o to ram:test would result in an executable (runable) program called test being placed in the Ram Disk. The Official Amiga Include Files One thing that A68K users do need to be aware of is the fact that they will not get the official Commodore include files with their assembler. It is possible however that some high-level language users will already have suitable include files, Lattice/SAS C for instance provides these as part of the compiler package, but if not two options are available. Firstly, the details of the appropriate parts of the include files can be typed in from the RKM Includes & Autodocs manual. Secondly,the files can be obtained by sending a written order for the Amiga 2.0 Native Developer Update disk set (accompanied by a cheque for £25) to: Mrs S. A. McGuffie Developer Liaison Manager Commodore Business Machines UK Ltd. Commodore House, The Switchback, Gardner Road, Maidenhead, Berks, SL6 7XA The following books are a selection of those currently available on assembly language programming, the Amiga, and on general programming. They’ve been chosen because they have all, at some period in time, been found to be particularly useful.

Title: Amiga ROM Kernel Reference Manual - Libraries Author: Commodore-Amiga Inc. Publisher: Addison-Wesley ISBN: 0-201-56774-1 One of the major Amiga reference books - for details see the discussions in Chapter Eight. Title: Amiga ROM Kernel Reference Manual - Devices Author: Commodore-Amiga Inc. Publisher: Addison-Wesley ISBN: 0-201-56775-X One of the major Amiga reference books - for details see the discussions in Chapter Eight. Title: Amiga ROM Kernel Reference Manual - Includes & Autodocs Author: Commodore-Amiga Inc. Publisher: Addison-Wesley ISBN: 0-201-56773-3 One of the major Amiga reference books - for details see the discussions in Chapter Eight. Title: Amiga Hardware Reference Manual Author: Commodore-Amiga Inc. Publisher: Addison-Wesley ISBN: 0-201-56776-8 One of the major Amiga reference books - for details see the discussions in Chapter Eight. Title: Amiga User Interface Style Guide Author: Commodore-Amiga Inc. Publisher: Addison-Wesley ISBN: 0-201-57757-7 One of the major Amiga reference books - for details see the discussions in Chapter Eight. Title: The AmigaDOS Manual Author: Commodore-Amiga Inc. Publisher: Bantam Books ISBN: 0-553-35403-5 Now in its third edition this is the most comprehensive guide to the internal workings of AmigaDOS that exists but parts of it are technically heavy going. Title: Mastering AmigaD0S2 Vols I and II Authors: Bruce Smith and Mark Smiddy Publisher: BSB Books Ltd ISBN: 1-873308-10-8 and 1-873308-09-4 These two volumes contain masses of useful information and bring the AmigaDOS reference material right up to date, including 2.04. Title: The Kickstart Guide to the Amiga Author: Dave Parkinson and Mike Boley. Publisher: Ariadne Software Ltd. This book has been about for quite a few years now so it is a little out of date in places. Nevertheless it contains a lot of useful information and is still worth reading. Title: Computers - From Logic to Architecture Author: R. D. Dowsing and F. W. D Woodhams Publisher: Van Nostrand Reinhold ISBN: 0-278-00093-2 Contains good general introductions to hardware issues (processors, memory chips and so on) including some 68000 material. Title: Dr Dobb’s Toolbook of 68000 Programming Authors: Editors of the Dr Dobbs Journal Publisher: Prentice Hall ISBN: 0-13-216557-0 A goldmine for ideas once you are fairly 68000 proficient, but does not contain any Amiga specific material. Title: 68000 Assembly Language Programming Authors: Kane, Hawkins and Leventhal Publisher: Osborne/McGraw-Hill ISBN: 0-931988-62-4 A very good general Motorola 68000 book with very detailed accounts of the instruction set. Title: Mastering Amiga System Author: Paul Andreas Overaa Publisher: BSB Books Ltd ISBN: 1-873308-04-6 This provides introductory coverage of Amiga System programming from a C orientated viewpoint. It attempts to answer the questions that other Amiga books either didn’t cover or didn’t seem to explain well enough. Titie: Mastering Amiga C Author: Paul Andreas Overaa Publisher: Bruce Smith Books Ltd ISBN: 1-873308-04-6 Provides an Amiga-orientated introduction to the C language. Title: Program Design 3rd Edition Author: Peter Juliff Publisher: Prentice Hall ISBN: 0-13-728916-2 A good, easy-to-read, introduction to program design techniques. Title: Program Design on the Amiga Author: Paul Andreas Overaa Publisher: Kuma Software ISBN: 0-7457-0032-2 A comprehensive introduction to some serious program design techniques, with a lot of emphasis on the Warnier diagram and the Amiga. Title: The Software Life Cycle Editors: Darrel Ince and Derek Andrews Publisher: Butterworths ISBN: 0-408-03741-5 This book contains a collection of papers on software design issues of current interest. It is well worth looking at! Title: Abstract Data Types and Algorithms Author: Manochehr Azmoodeh Publisher: Macmillian ISBN: 0-333-51209-X This is an excellent introduction to the world of the ADT. Title: Computer Graphics 2nd Edition Authors: Foley, van Dam, Feiner and Hughes Publisher: Addison Wesley ISBN: 0-201-12110-7 When you want to get serious about graphics, and the underlying theory, this book will set you on the right road. Title: Three Dimensional Computer Graphics Author: Alan Watt Publisher: Addison Wesley ISBN: 0-201-15442-0 Another useful graphics book.

Mastering Amiga Assembler The Amiga is a wonderful computer but the sheer complexity of its operating system has provided a major obstacle to many programmers wishing to enter the world of Amiga assembly language programming. In this Mastering Amiga guide Paul Overaa has produced a book guaranteed to get the serious Amiga owner into 68000 assembly language programming as quickly and painlessly as possible. The introductory text expects the reader to have a basic knowledge of the Amiga and some experience of languages such as BASIC or AmigaDOS, but no prior knowledge of 68000 programming. Any operating system concepts to be understood are fully covered in a straightforward and easy to read fashion. Topics covered include: • Fundamental assembly language concepts • The 68000 processor and its important instructions • Use of the system header files and official Amiga documentation • Details of HiSoft’s Devpac and the PD A68K assembler • Advanced 68000 topics including mixed code programming • Low-level Intuition and graphics programming • CLI/Shell and Workbench programming • Working with the Amiga libraries • The 68000 addressing modes • And everything you need to enjoy Amiga assembler programming FREE SOFTWARE ON DISK The programs in this book are available free, subject to carriage. See inside for details. £24.95 ISBN 1-873300-11-6 781873 30811 9781873308110