Concise Atari ST 68000 Programmer's Reference Guide
There are a number of assemblers available for the Atari ST programmer, they have small discrepancies in the assembly syntax used, no uniformity in the library and utility files supplied or of the method of creating an executable program.
This makes it difficult for the inexperienced programmer to type as source a program listing created for another assembler, and to get it operational. What I have tried to produce is an analysis of each assembler and a conversion chart that may help in isolating fairly straightforward problems.
Where a published program uses a particular assembler specific facility (special macros etc.) then translation will not always be possible by simple substitution and there may be no easy solution. Hopefully the general assembler compatibility chart will indicate whether there is the likelyhood of a conversion.
This guide is very much less than perfect, but it is an attempt at assisting inexperienced programmers in a very difficult field.
Very few of the assemblers provide programming details of the Motorola M68000 processor instruction set, or teach the user basic assembler language programming. If the reader has not written assembly language programs before, the brief overview of the language in Appendix G and H should help.
The combined editor/assembler/monitor/debugger is held in a very compact 20K of code, this means that parts of the package are a bit weak. Although two editors are supplied, a line editor and a screen editor, neither performs block find and replace function. Use the Atari wordprocessor in non wp mode for major or block changes in large files. What is likely to be more of a significant problem is the limitation to a leading letter for label and symbol names (the use of an underscore is very common in most libraries and the Atari system variables). A possible solution would be to substitute a little used letter for the leading underscore, say ‘z’.
On the positive side, the Seka assembler generates absolute or relocatable executable code directly, has limited macro and conditional capability, and is a quick assembler for writing programs if you know what you are doing - some of the runtime error messages are incomprehensible with no guide in the manual as to what they are trying to tell you. It is very convenient having all the facilties in one program, an assembly error leaves the editor at the erroneous line for immediate correction and reassembly or the programmer may trace through the code with the monitor/debugger. The editor also allows the programmer to type the source code in free format; the assembled output listing is automatically tabulated, but there is no way of simply listing the code to a printer in a tabulated form which makes the source difficult to read when trying to debug program logic errors.
Source files entered in a tabulated form are occasionally detabulated in parts of the assembly list file. The system for linking files is a bit messy and very non-standard as are some of the assembler directives. The monitor/debugger allows the programmer to single/multiple step through a program, examine registers, set breakpoints and provides all the necessary facilities to aid program debugging. It is important to ensure that program files are of even length; odd file lengths sometimes produce run-time errors not discovered by the debugger, which makes the fault extremely difficult to locate.
The assembly syntax is pretty standard; labels must terminate in a colon, ‘movea’ should be entered as ‘move’, the assembler correcting the syntax but strangely ‘adda’ is acceptable. The 36 page manual limits the two examples to very simple TOS programs, one of which includes macros. The manual has a lot of ground to cover which it manages only at a fairly minimal level. i.e it does not provide enough information regarding the cause of errors - an error in a macro is flagged as an illegal operand in the calling code. The manual contains a very useful single page command summary.
The package is very easy to use, although not as powerful as some of the other packages in this Appendix. As an assembler, it is complete with minimal libraries of DOS calls equates and GEM array generators.
A combined editor/assembler with a separate monitor/debugger. The Hisoft assembler employs include files to ease the access to the GEM and TOS functions and produces machine code directly. The include files require function parameters to be explicitly placed in the parameter arrays as per the assembler GEM example (Appendix L). The assembler package incorporates a selective GST compatible linker and does not like labels followed only by comments on the same line. The editor is a full feature program with the minor omission of displaying and handling only one file at a time.
The package contains include files of equates for BDOS, BIOS, extended BIOS calls, system variables and a GEM include file that provides program initialisation, VDI and AES constant equates and parameter array initialisation. The package does not provide details of the data (Chapter 3) to be placed in the arrays.
The monitor/debugger besides supporting the usual step, set breakpoints, examine and modify registers and memory etc. enables the assembled program to be run and debugged using separate screens for the graphics and the monitor output, a very useful feature.
The documentation is well written and provides a good introduction for the beginner.
A very friendly package that could benefit from the use of a RAM disk to hold all the files in memory at once. In a 512K machine, separating the program into two components does not appear to provide the optimum ‘modus operandi’.
The GST assembler package has a very good GEM based editor that enables up to four files to be worked on at the same time in multiple windows, copying blocks from one to another with ease. The only possible complaint regarding the editor could be the relatively slow loading of program and files and of cursor movement up and down within the file.
The assembler can produce relocatable binary output suitable for the linker or executable code directly from position independent source. The executable code does not contain the standard Atari TOS file header preamble, which must be added by the programmer if the file is to act as a stand alone program. A very useful list of the instruction mnemonics is provided, as is information on the optimisation route taken in compiling code. The use of an underscore for the leading character of a label or symbol is not permitted, which entails a degree of non compatibility with the standard Atari ST notation for some system variables and extended BIOS calls.
The assembly of source is slow by virtue of the many disc accesses, but the use of RAM disc for compilation and the loading of all modules into memory together will obtain reasonable speed. There is no uninitialised data (BSS) d. The GST linker is also supplied with the Metacomco macro assembler, it enables other high level language modules written in Pascal, Assembler and C to be linked together in a single program.
The library supplied contains macro definitions of conditional structures. GEM and TOS libraries are not supplied.
The documentation consists of separate (unindexed) assembler, editor and linker manuals, which are very well packaged in a ring binder, the manuals are very detailed, but may be difficult for the inexperienced assembly language programmer to read.
The screen editor is good but does not follow the normal GEM style of access, although the user will very quickly adjust. The global 'find and replace' is comparatively slow as the screen is re-written for each change.
The assembler is slow in comparison with the smaller assemblers evaluated in this Appendix and would benefit greatly from the use of RAM disk. Symbols may be of up to thirty significant characters, but tabulated 'dc' data values on one source line separated by a comma and space are not permitted - the space may be used to introduce a comment.
Metacomco supply the GST linker with their macro assembler which can produce either a binary file suitable for the GST linker or a CP/M 68K object file suitable for the DR link68 linker; which links to the complete DR set of GEM and TOS libraries, but is undocumented.
The Metacomco assembler package is supplied with assembler source to the GEM libraries and a monitor program. The monitor provides breakpoints, a trace mode and register/memory change and examine facilities.
The assembler suite of programs can be batched using the Menu+ program provided, It enables the sequence of edit, assemble, link and run to be controlled by the menu file, which runs and loads each program producing the specified outputs as requested and entering the next stage automatically via a pause, wait or continue programmed instruction.
The documentation is concise and very well laid out, but gives no additional explanation on assembly errors to that displayed on the screen during the assembly phase.
The Digital Research package can use any editor/word processor that is capable of producing an unformatted ASCII text file.
The assembler, which is a reasonable implementation of the Motorola M68000 assembly language, has no macro facilities but optimises instructions and branches to produce efficient code.
The DR LINK68 linker provides access to the DR GEM and TOS libraries that consist of accessory and application header files, GEMDOS, BIOS, XBIOS, VDI, AES and floating point libraries.
Although the assembler, linker and relocator programs can be installed as TTP (TOS Takes Parameters) files, the programs are much easier to run via the Activenture Corp. batch program. The additional use of a RAM disk to hold the files and programs produces a very reasonable response, eliminating much of the disc access.
The development package was intended for software developers and not the general public, as such it is written with a high degree of technical jargon. Complete with no omissions, a veritable ‘War and Peace’. It provides information on all of the GEM VDI functions and makes no mention of those not implemented on the ST.
DR C language modules may also be linked with the assembled source and DR libraries to produce executable programs.
The package is supplied with the DR symbolic interactive debugger ‘SID’ enabling the program writer to test and debug M68000 executable code, either from TOS or GEM, read/write/move blocks of memory, disassemble code or produce a hex dump, examine the CPU state, trace, run or step through the code.
Compatibility table
The analysis of each package necessarily concentrates on the flaws, looking for inconsistencies and omissions. What may not be apparent is how good in absolute terms the packages are, any purchaser being able to justify the cost on technical excellence alone.
It may be useful to give an indication as to the range of likely purchasers of each package:
Kseka assembler
Absolute beginner - competent programmer: very fast program development
Hisoft devpak
Absolute beginner - competent programmer: fast program development, with GEM and TOS bindings.
GST macro assembler
Absolute beginner - expert: full feature assembler capable of linking with other high level language modules to form executable programs.
Metacomco assembler
Competent programmer - expert: full feature assembler with macros. DR’s linker may be used to provide access to the complete set of system libraries, and GST’s linker to link high level language modules into a combined language program.
Digital Research assembler
Software developer: not available to the general public.
There are a number of assemblers available for the ST, each with different characteristics, this section is provided as an aid to translation of programs presented from alternative sources.
One of the by-products of the compatibility information is that it provides the opportunity of generating a subset of directives and instructions that are of almost universal applicability, but compatibility does tend to look at the lowest common denominator.
All of these programs have other attributes which provide a significant improvement in performance over the base standard, these improvements are not always apparent to the casual user but very handy to have if required.
If you wish to write source for maximum compatibility with other assemblers, the following should minimise the problems:
Sizing instructions is perhaps the most difficult factor to come to terms with. I find it extremely difficult to ignore and not stop and read any warning messages, and become a little irritated to find that a branch ‘might be short’ or that LEA has not got a .L extension. All warnings should be significant or else they will all be treated as superfluous information.
The above table will help to eliminate some of the more straight-forward program conversion problems, those that remain are likely to be due to the use of assembler specific directives and or libraries (especially label errors).
If a program is published, one assumes that any include file data will be generally available and can either be appended as an include file or the code integrated with the main program block of code.
If your assembler does not have VDI and AES libraries, then to use GEM you will have to create the arrays and load the addresses as shown in the assembler GEM example in Appendix L.
The chart is limited to simple conversions. Once include files and global label definitions are used, you will need to assemble the program, generate a list of the missing external labels and hopefully find them in the examples Appendix and/or the call listings Appendix E.
Numbers
The following shows the standard presentation of the various numeric types:
Binary %xxxxxxxx x = 0 or 1 Decimal nnnn n= 0 to 9 Hexadecimal $nnnn n = 0 to 9, a to f
considerably in use of parameter names, the call and parameters are therefore not provided here to avoid confusion. The manual of the C compiler you are using will provide a definitive list of the library routines available, interfaces, and the required parameter size, sequence and annotation.
Many compilers will have additional features to greatly simplify the task of writing GEM programs; but bear in mind that the use of these ‘super C’ GEM functions may put a restraint on program portability. A definite decision should be made as to whether the programmer is writing portable code or simply writing a program.
On a more general note; it is very much easier to develop programs on a 1 Megabyte disk drive, which makes the larger drive well worth the small additional cost for those machines without the built-in drive.