ARGASM 68000 ASSEMBLER Typed by AMAZON for LSD. INTRODUCTION MINIMUM SYSTEM REQUIREMENTS. ArgAsm is supplied to operate on a Commodore Amiga computer. It has been tested on a variety of configurations including the 1.2, 1.3 and 1.4 OS's. It is known to be compatible with the entire Motorola 680x0 range, and has been tested on the 68000, 68010, 68020 and 68030 processors, and will probably work on the 68040 which was not available at the time of writing this manual. The minimum memory requirement for ArgAsm to run in any useful manner is about 1 megabyte of free ram, but for large projects we recommend 1.5 meg or more. We have been able to assemble quite substantial programs (eg: a Flight Simulator, 800k of object code) with only 1.5 meg of memory inhouse at Argonaut. As with most multi-tasking machines, more RAM is always a useful addition to your computer, as is a nice fast hard disk. ArgAsm supports all standard Amiga DOS devices, including RAM-Disks, Hard Disks, Networks, etc. We have streamlined ArgAsm to assemble as quickly as possible once the sourcefile has been read into the computer. But our bottleneck is still disk I/O performance since the Assembler can outrun most hard disks. We therefore recommend you to go for the fastest hard disk your budget can support. The faster your disk performance, the faster ARGASM can read, and then assemble your sourcefiles. As proof, do some assemblies from Ram-disk just to see how ArgAsm performs in an ideal I/O situation. TECHNICAL ISSUES ArgAsm is a One-Pass assembler. This means that it only needs to read and parse the source file once in order to create the correct object code. Most assemblers on the Amiga are Two-Pass, though some of them only read the source file once (but still parse twice) to cut down on I/O time. In real terms, there is no loss of functionality between a well written one-pass assembler and a two-pass assembler, but there are obvious performance gains in the former! The concept isn't new, as many compilers are One-Pass, including a few recent PASCAL and MODULA-2 implementations. A two-pass assembler (like assem, Devpac and Cape) will simply assemble the source code twice, the first time ignoring any 'undefined symbol' errors due to forward references and the second time around, with full error reporting writing out the correct object code. A one-pass assembler (like ArgAsm) simply assembles the source code directly into an object code buffer, keeping track of any forward references as it goes along. After the pass is complete, any forward references are resolved and inserted into the object code buffer to create the correct code exactly as if it had been done in two- passes, when in reality it was about 'one and bit' passes. The advantage of this is naturally a doubling in performance over conventional assembly techniques, the disadvantage is that the object code buffer must be held in memory at all times. In real terms there is little loss of memory since most two-pass assemblers buffer up their object code to speed up on disk I/O, thus taking up the same memory as ArgAsm uses. In some ways, being a one-pass assembler can be more memory efficient than a two-pass one that buffers up the sourcefiles, because once it has parsed a sourcefile, it doesn't need to be held in memory for the next pass (since there isn't one), which is great when you have lots of Include files at the same nest level. When an Assembly listing File has been requested, ArgAsm produces this in the same pass as the Assembly is being performed. For most instructions, there will be no difference between our Listings, and those generated by other Assemblers. But, if there were any forward references in the sourcecode then the listing will show zeroes in the hexbyte column of the listing output file. This does not affect the object code generation in any way, and is purely a listing idiosyncracy due to the one-pass nature in an Assembly. Most people don't even bother reading the actual hex bytes in an Assembly listing anyway, especially when we went to the trouble of cramming in a lot of extra 68000 information in our listing files that other assemblers cannot produce. TECHNICAL SUPPORT. We are only too willing to offer help and advice with any problems you might have when using ArgAsm, but this must be limited to direct use of ArgAsm. We are unable to offer general programming advice or help you track down bugs in your code, but we will directly support ArgAsm and it's usage on the Amiga computer. Simply write in or FAX us with a concise description of the problem and we will get back to you as soon as we can (usually within 48 hours). Leave us your name, (rank?) and serial number and also an address/telephone number where you can be reached. If the problem is really urgent and you need to speak to someone by 'phone, then our preferred time to call the ArgAsm Tech Support is between 2 and 3pm UK time (9-10am Eastern USA time) If you call us at any other time, we cannot guarantee that the appropriate person will be there. ArgAsm has been developed for a year, and we won't stop here! We intend to improve, perfect, incorporate ideas and fix any new bugs to keep ARGASM on top! No product can be guaranteed 'Bug Free.' As with any product of this complexity (ArgAsm is over 100k of pure handcrafted machine code, 1 meg of source code) there are always bound to be subtle things we didn't find, even during our extensive testing on both sides of the Atlantic. If you have discovered a bug or compatibility issue then we need your help to track it down to a few lines of example code that consistently show up the existence of the bug every time. If you can send it to us on disk, or if it is easier by FAX then we will get right onto it! If we can Reproduce it, we can fix it. And we WILL fix it! As an extra incentive, The first person to highlight an undiscovered bug will receive an upgrade at our expense. If you find you have to alter your sourcecode to skirt around a problem or idiosyncracy, don't keep it to yourself. Tell us, and with any look the next upgrade release will have your improvement requests made to it. You must be registered with us prior to using our Tech Support service, and you will need to supply your Serial Number with any Enquiry. be it by mail, fax or 'phone. UPGRADE POLICY. From time to time, we will make available Enhancement Upgrades to add features, increase the functionality or to fix bugs/idiosyncracies in ARGASM that are reported by our customers. The fee for an upgrade will be small and is only there to cover costs in getting it to you. In general, A Bugfix Upgrade will cost less than a Feature Enhancement upgrade: due to less paperwork (manuals, programming etc.) Approximate cost will be around £10 to £15 pounds sterling. In addition to normal upgrades to ArgAsm, we intend to have a more powerful big brother that is provisionally known as ArgAsm Professional (not that we're implying the current version isn't professional) that will support the extra 68030 specific instructions (and maybe even 68040), 68881/68882 and many other sophisticated enhancements like built-in fast linker, not yet seen in an Amiga Assembler. This package will cost more than the original ARGASM package and will be marketed on a two-tier sophistication level. We will of course allow upgrades from ArgAsm to ArgAsm Pro, for a reasonable fee that has yet to be decided, but our policy is to provide existing users with a way of upgrading to the latest and greatest products we sell. Our Existing users will never be penalised when we add to, or improve our product range. As with any usage of ArgAsm, we urge all customers to Register with us so we can provide notice of improvements, bugs or new products. Needless to say, Upgrades will only be available to registered users. EXTRA DEVELOPMENT TOOLS An invaluable extra development tool is a Debugger. We don't supply one with ArgAsm just yet, for many reasons, the most important being that we only like to do products where we know we can be the best at what we do. That usually means being faster, or better. To be honest, we don't think we could do any better a debugger than is already available elsewhere so there is unlikely to be one from Argonaut unless of course someone submits one to us that fulfils our high requirements. We have used many Amiga debuggers over the years, and two spring to mind that are really quite good. the first is MonAm2 from Hisoft, it very powerful, eminently usable, and is good for low level work. An excellent all round monitor, but at the time of printing it was not available separately. Hisoft tell us that they are planning on marketing it separately so do check with them about it. Another good debugger is MetaScope from MetaDigm. This is a much friendlier monitor than MonAm2, but doesn't seem so usable for low level work. Also, it runs on a Workbench screen so suffers more from buggy programs interfering with it than MonAm2, which creates its own screen. This one definitely is available as a standalone product. The last two debuggers are available free with C compilers, these are CodeProbe (CPR) from Lattice, and SDB from Manx. Both are excellent source level debuggers, but don't seem to be available as standalone packages just yet. You can always ask though. Perhaps by the time ARGASM Professional is ready, we may have changed our mind and written our own Amiga Debugger. Watch this space, and let us know if yet another debugger is really wanted? We intend to write a fast multi- format linker, possibly built into the assembler. ARP.LIBRARY ArGed uses the infamous Arp.Library file requester written by Charlie Heath of microSmiths. If Arp.Library isn't present in your libs: directory you will only see a simple file requester (a String Gadget) when trying to load or save files. The Arp file requester has a scrolling list of files that you can double- click to select the one you want. It also has gadgets to scroll up and down, or to change the device. You can also type the filename in directly, or use the last selected one by pressing Return or clicking on OK. EXECUTING ARGED FROM THE CLI The simplest way of running the combined Editor/Assembler version of ARGASM is to type ArgEd from the CLI. This will load up with blank page, ready for you to either type or load something you were working on earlier (with the Load menu). You may alternatively specify any number of filenames which ArgEd will load into different windows ready for you to do a mammoth editing session. eg: 1> ArgEd 1> ArgEd DHO:Frog 1> ArgEd Allsyms.i frog.s types.i If you were working on something earlier and had done a snapshot, you simply type ArgEd to continue working where you left off. EXECUTING ARG FROM THE CLI To run the standalone file-based Assembler is not quite so straightforward as there are a myriad of CLI options, none of which are very memorable so take the time to study them here. The golden rule is that we have tried to make ARGASM as compatible as possible with the standard Commodore Assemblers. We have largely followed the Metacomco ASSEM standard for Command Line parameters, whilst maintaining as much compatibility as possible with Cape and Devpac. The CLI format is: 1> Arg (-Option -Option) Eg: To simply Assemble a file with no output file or frills, type: 1> Arg sourcefile.s Naturally, this won't save any object code output, produce a listing, or in any way serve useful purpose other than providing that ARGASM actually assembled your file. This is usually done to check for errors, or even just to boast to your friends how fast ARGASM is! A SUMMARY OF ARG CLI OPTIONS -a Accepts a source file (for Cape compatability only) -b Disables all object code file generation. -e Error list printout at the end of the listing. -h Specify a header file to be Included before your first file is assembled (This is the same as 'Include Filename' at the start of your source code) -i Include directory pathlist. (like the INCDIR directive) -l Specify an assembly listing filename (defaults to the console) -m Allows you to specify the size (in bytes) for the Object Code Buffer. (The default is 64000 but you can specify different amounts.) -o Specify a object code filename. (No object file will be generated if you don't ask for one!) -p Disables Printer Control characters from error reports. (in case they confuse your printer or redirected output file). -q Quiet flag, avoids printing anything (for those peaceful days) -s Symbol table printout at the end of the listing. (Output in the form of EQUs, ready for later re-assembly if required) -t display timing and assembly statistics. (Useful assembly information and timings) -u Uppercase all sumbols (same as OPT C-, makes them case insensitive) -w Turns Warning errors off (same as OPT W-) -x Makes code executable (same as OPT L-) ArgAsm supports the standard AmigaDOS output redirection so you can obtain printouts or files of your ArgAsm sessions. eg: 1> Arg frog.s -o frog.o This is the usual form an Assembly will take. It simply assembles the specified source file 'frog.s' into an object code file 'frog.o'. Note, for even lazier typists you can have an OUTPUT directive at the start of your source code to specify the default object filename and then you won't even have to have it present in the CLI options, as ArgAsm will use the first one given. Let's be more ambitious... 1> Arg >w dog.s -o dog -l list,lst -i Include: -t The above will assemble the source file 'dog.s', getting any include files from either the current directory or the 'Include' assigned directory. The object code output will be written to 'dog' and an assembly listing will be written to 'list lst'. Also, ArgAsm will display the timings and statics when it's finished. And just for history purposes, we have captured the session log into a file 'w'. OBJECT CODE BUFFER If you are assembling programs, you may see data error messages claiming that the object code buffer is full. This isn't drastic as the object buffer can be set in advance to any size you want (provided you have enough memory, of course). ArgAsm needs to store the entire object code in memory in its object code buffer. This has to be allocated in advance of the assembly because it must be contiguous. The default object buffer is 64K (65536 bytes), but as you begin to write bigger and bigger programs, you will need to readjust this value. It can be adjusted with the -m CLI option or from within ArgEd's Assembly Options page. MEMORY PROBLEMS ArgAsm is more sensative to low memory situations than other asemblers. It has been optimised to assemble source code quickly and not hang about worrying how to conserve memory. Quite different from running out of object code buffer space, you may receive an error claiming that you are FATALLY out of memory. This error is more serious, as you will have to either buy more RAM for your Amiga, or prune down your source and object code in size to fit your Amiga's RAM. This can usually be achieved by minimising the amount of object code bufferspace (with -m) and also splitting up your source files into finer chunks and utilising Include to read them in piecemeal fashion. That way, ArgAsm can allocate smaller chunks of memory and use it more effectively. ARGASM INSTRUCTION SET There isn't space to list the various 68000 instructions that ArgAsm supports. All Motorola documented 68000 instructions and addressing modes are supported, in a compatible way to Metacomco's ASSEM, and Hisoft's Devpac 2. We also support the extensions to the Motorola standard like zero offsets on (PC,Xn) and (An,Xn) addressing modes. We recommend purchasing Motorola's fine 68000 technical reference manual. [The 68000 bible, accept no substitutes] ARGED, THE EDITOR. You may have read elsewhere that ArgAsm is supplied in two forms, the first is a standalone assembler that accept source files from disk. These may have been produced with your preferred editor that you may already know and love, or possibly the source code may already exist, for instance Commodore supplied examples. The second version of ArgAsm supplied contains both a screen editor and a built-in Assembler, collectively called ArgEd. This allows you to interactively edit your source code, assemble, then edit again to fix any errors. All this is done without any unnecessary disk activity which allows greater productivity and flexibility on the part of the programmer. ArgEd is a RAM-based multi-window screen editor. 'RAM-based' means that the entire contents of the files that you edit must comfortably fit into your available RAM. In the unlikely event that you want to edit files larger than your available RAM you must either split your file into smaller chunks (quite how you do this is a difficult exercise on its own!), and edit these seperately, or alternatively you can purchase a fully fledged virtual-file editor, which is designed to perform such functions. In most cases the files you edit will be smaller than your free RAM, simply because most Amiga's have at least 1 meg of RAM, and most assembler source codes are much smaller than 1 meg. Most are around 50 to 100k, and the ideal maximum size for a source file is in fact only a few hundred kilobytes. If you are constantly running out of memory when editing files, we suggest you seriously think about purchasing more RAM. After all, RAM is cheap, useful and very cost effective! 'multi-window' means that you can have many windows open at the same time. This is an unusual feature, as most editor's aren't smart enough to do this well enough to be usable. These windows can be looking at the same file in different places, or you can open up lots of different files all in their own seperate window. Yet again, all the files that you open must be able to fit in RAM at the same time. 'screen editor' means that the editor displays an entire screenful of text in a window and allows you to move a cursor about whilst scrolling the text back and forth, left and right to allow you to edit your text anywhere in the window. This is more advanced than earlier 'line editors' where you can only edit the current line, and moving back and forth was cumbersome and rather unfriendly. In particular, ArgEd has been programmed with performance in mind, so that you can page or scroll the windows back and forth instantly without waiting for the editor to catch up or the text to be redrawn like with earlier Amiga editors. AN EXAMPLE EDIT SESSION Okay, let's just briefly go through a way to get you up and running. To run ArgEd you simply type ArgEd at the CLI prompt. Assuming you are running it for the first time (and not in the middle of something last time you used it) ArgEd will put up a blank page ready for you to type away. The cursor will be visible at the start of the page, and whatever text you type will be inserted at that point. Hit RETURN at the end of each line. If you make any mistakes you can delete the previous character with the BACKSPACE key, or you can delete the character under the cursor with the DELETE key. You move the curser about with the arrow keys. You can only move up or down if you have text there, so you cannot scroll away and lose your text. When you get near the top or bottom of the window, the text window will be scrolled to reveal another line in the direction you moved. If you wish to jump a whole page at a time, hold down the SHIFT key as you hit the arrow keys. Also, you can move to the beginning and end the line with CONTROL held down and pressing the Left and Right arrows. You can get to the Top and Bottom of your document by holding down CONTROL and pressing the Up and Down arrows. You can also get to the Top and Bottom of your document by pressing Amiga-T and Amiga-B respectively. Now go ahead and type in some example text, and play with deleting and inserting lines and generally getting comfortable with scrolling and paging windows about. Having typed in your source code you will then want to save it to disk. So press Amiga-S and a requester will pop up asking for the name you want to call it. You can either click on filename you want to overwrite, or type in a new name for it. A good convention for source code filenames is to end them with a .S, eg: MYFILE.S or SOURCE_CODE.S, this is so that you can always know it's an assembly source code file. Some people prefer .ASM instead. To load in source code text that you have previously saved, press Amiga-L to get the file requester, and then specify which filename you want. It will be loaded in the current window replacing any previous contents. If you wish to insert a file from a disk into the current contents of a window, you press Amiga-I instead. This will insert the text as if you had typed it into that spot. ARGED'S MENUBAR As with all Intuition compatible programs on the Amiga, pressing the right mouse button will invoke the menu bar at the top of the screen. This contains a menu of categories which you can move the mouse pointer over to bring down a sub-menu list over which you can move the mouse pointer. You simply release the mouse button while the pointer is on your selected menu choice for it to take effect. If you wanted a different menu you can move the mouse around while still holding down the button. If nothing takes your fancy simply release the mouse button when the pointer isn't on the menu. This has the effect of cancelling your menu request. ArgEd has the following menu categories. PROJECT, WINDOWS, SEARCH, GOTO, ARGASM, BLOCKS, SPECIAL Taking these in turn, the menu categories are listed in order together with their sub-menus. Any keyboard shortcuts are listed in brackets next to the sub-menu name. THE PROJECT MENU These functions are generally to do with the current project, for instance loading, and saving files or quitting. CLEAR (Amiga-C) will wipe out all the text in the current window ready for you to start afresh. If you hadn't previously saved the text, you will be given a last chance to back out by saying whether it is okay to continue or cancel the request to Clear. LOAD (Amiga-L) is to load a new source file from disk into the current window. Yet again, if there was unsaved text still in the window you will be asked if everything is still okay to continue. A file requester will pop up and you can select the file by clicking on it with the mouse, or typing a filename (and directory) into the string-gadgets at the bottom. The file requester is part of the 'Arp.library' package, and if for some reason this isn't on your sytem disk the nice file requester will be replaced with a simple string requester askin for the filename with no frills or gloss. SAVE (shift-Amiga-S) will save the text of the current window as the same name as was last used. If this is the first time the file has been saved, then you will be requested for a filename. SAVE AS (Amiga-S) will first request a filename, and then save the text of the current window to disk. This is usually done the first time you save a file, or if you want to save it under a new name for backup purposes etc. If you are happy with the present filename you may as well use save instead of Save as. INSERT FILE (Amiga-I) will insert a file from disk at the current cursor position as if you had typed it in directly. The inserted text will become part of the current file when you save it out. The original file on the disk that was inserted will be left untouched on the disk. QUIT (Amiga-Q) will quit from the current window, closing it up and deallocating any memory that it was using. If the file had not been recently saved you will be asked if it is okay to proceed. If this was the only ArgEd window that was open, the program will then quit and return to AmigaDOS. If more than one ArgEd window was open, Intuition (the Amiga OS) will select another window to be active. This may not be an ArgEd one, so be sure to check where the new activated window is, and if you don't agree, click on the one you want. QUIT ALL is a quick way of quiting the program, as it effectively does a quit of all ArgEd windows. This menu option doesn't have a keyboard shortcut as it's too easy to lose your files accidently. THE WINDOWS MENU OPEN NEW WINDOW (Amiga-W) will create a new blank window ready for you to type in some new source code text. The window will not be related to the last file you were editing (see the Split Vert and Split Horiz subcategories for that). The main use of this is to type or load in a new file into a window so that you can edit more than one file at the same time. Quite often you will only be editing one file, but referring to a few others, and by opening up a window for each you can scroll around looking for the information you want. Also, you can use ArgEd's powerful searching facilities to track down labels or references you are interested in. CLOSE ACTIVE WINDOW (Amiga-K) will close down the currently active window. This is the same as hitting the Close gadget with the mouse pointer in the top left corner of the window. Usually you would want to close down a window (as opposed to Quitting) if it was a split view of a file that another window was displaying. SPLIT HORIZONTALLY (Amiga-X) is used to give you another view of the same file. The current window will shrink to half it's size, beig replaced by another similar window on the right side of it. Once split, windows can scroll independantly allowing you to make changes in one window that affect another will be displayed as they occur. You can split a window quite a few times before it becomes too small to use (at which point ArgEd will keep it from getting any smaller but will still let you split into more windows). After a few splits it becomes pointless splitting any further (diminishing returns) and at some point the Amiga OS will become sluggish having to update and clip the text to all these windows. So keep to a sensible maximum number of windows onscreen at any one time (about 5 or 6). SPLIT VERTICALLY (Amiga-Y) is as above, only it splits the windows so that they are halved vertically and the two new windows are on top of each other. WINDOW FULLSIZE (Amiga-E) will expand the current window to fill the screen. This is usually done when you have a few windows on the screen and decide you want to see maximum detail in one particular window. Hitting Amiga-E is a quick way of getting a window as large as possible and has the same effect as dragging the window with the mouse to the top left of the screen, then grabbing the sizing gadget and stretching until the window is at fullsize. The opposite is Shrink Window. SHRINK WINDOW (Amiga-U) will unsize a window and make it as small as possible. Used when you want to tidy up your editing screen and keep windows from cluttering up your work. When you want to go back to the file you can click to activate it then do a Window Fullsize (Amiga-E) to bring it back to popularity again. ACTIVATE NEXT WINDOW (Amiga-D) will cycle through activating a different split window of the same file each time it is selected. It is the same as you clicking in a different window each time. THE SEARCH MENU FIND (Amiga-F) will pop up a requester asking for some text that you wish to search for. The search will start from the cursor position and will stop at the end of the file. If found, the cursor will jump to the start of the text you were searching for, if necessary repositioning the window so that the text is visible on screen. At this point, you may want to replace the text with something else (by selecting Find Next, Amiga-N). The Find requester allows you to enter the text you want to search for in a string gadget, and also to select whether you want the search to be case insensitive (ignoring the difference between capitals and lower case), and also allows you to specify a replace string to be used if necessary. Also, you can select to Search backwards for the previous occurence. FIND PREVIOUS (Amiga-P) will continue the search for your specified text string entered with Find but will go backwards through your file to find the previous occurence rather than the Next. FIND NEXT (Amiga-N) will continue the search for your specified text string and display the next occurence if one was found. It has the same function as selecting Find again with the same settings. FIND LABEL (AMIGA-M) is an unusual but powerful function to find the original label definition (be it an Equate, Subroutine or Table start) of something the cursor is on. If your cursor was on a subroutine call to a specified label, you would click on that label with the mouse (or move the cursor there) and select Find Label. ArgEd will enter the current label as a search string but will only look for it at the start of a line, which could only be a label definition. GLOBAL REPLACE (AMIGA-@) will start at the current cursor position, and will replace every occurence of the search string with the replace text string. Although it is much faster than doing it by hand, it can sometimes take time (several seconds) on a big file, so be patient. THE GOTO MENU TOP (Amiga-T) will instantly redraw the window at the very top of the file and will place the cursor at the top of the window. BOTTOM (Amiga-B) will instantly redraw the window at the very bottom of the file, and will place the cursor at the end of the window. LINE (Amiga-G) will pop-up a requester asking which line you want to go to. It will then put that line in the centre of the window, with the cursor on top of the first character of your line. This is mainly used to visit lines given to you from error reports. BLOCK (Amiga-O) will go to the start of your block definition (as defined by the block marker keys F1 and F2 respectively). THE ARGASM MENU This menu category is only for assembling the source code in the currently selected window. ASSEMBLE (Amiga-A) will pop-up a large requester full of assembly options. To avoid the Assembly Options requester, and go straight to the assembler, hold down Shift while pressing Amiga-A. ASSEMBLY OPTIONS The Assemble-Options requester will pop up with a number of gadgets for you to select what options you want when assembling your source code. An explanation of each option follows: The Object Code Type can be either Executable or Linkable. Executable code must have no XREF or XDEF references to other modules, since it will become a runnable standalone file. Linkable code can have XREF/XDEFS referencing other object code modules that will be resolved during linking. Case Dependance: refers to whether upper and lower case labels are treated as different or the same. Case Dependance will treat 'Frog' as different to 'frog'. Case Independance will uppercase all labels before processing so that upper and lower case differences are ignored and 'Frog' is the same as 'frog' or 'FROG' since they all become upper case. Debug Info: refers to whether symbols are included in the output file. You will normally want to set it to NONE for shippable code (to stop other people seeing your secrets), but for development purposes you would usually have Normal debugging info. That way, the Monitor program will be able to show your symbols as an assistance to debugging. List To: refers to where the listing file will be sent. If you select NONE, then no listing file will be created. This is the fastest way of using the assembler. If you select Screen then listing will be sent to the console "*" or selecting Printer would send the file to "PRT:". You may also send the file to named disk file for later examining or printing. Output To: allows you to specify where the object code file is sent. You would normally just leave this option set on DISK, and have an OUTPUT directive in your source file. Alternatively, leave it set to on NONE and no object code will be generated. You can fix assembly errors more quickly by repetive assembly, then editing without writing the object code to disk. Error Options: allows you to disable Warning Error messages. Most warnings can be ignored if you know what you are doing. Similarly, Optimisation warnings will usually want to be ignored. List Options: refers to your various choices of listing information. Select Macros if you want Macros to be expanded in the listing or leave it unselected if you just want to see the macrocalls. This is the same as OPT M+. Similarly with Include files, select if want to see them listed. The Narrowlist option will make an attempt at shrinking the width of the listing by leaving out columns and truncating lines. The Timings option allows you to have an extra column of the 68000 instruction cycle times, together with read/write cycles and the Flags that are affected by each instruction. This is very useful and makes interesting reading. It allows you to optimise your code by paying careful consideration to how quick each instruction is. You would normally have to have a reference book by your side looking up each instruction manually. Finally, selecting the Error option will print a list of errors at the end of assembly, normally the errors would be printed up as they occur. The Maximum Object Size: refers to the size of the internal object code buffer. This is normally set to 65536 bytes (64k) but if you are short of memory in the machine you can set it smaller (say, to 16000 bytes). If ArgAsm ever reports a fatal error because the object code overflowed the buffer then you can make the buffer bigger. It should be bigger than the maximum possible size of your object code. You can leave a fair margin, so guess on the high side. The Macro definition size: refers to the size of the macro definition buffer where your macros are stored. This contains all the text enclosed within your MACRO/ENDM definitions. If you get errors saying that the macro table is full, you know to increase this buffer. In most cases 16000 bytes is adequate, but if you are writing large macros you may want to increase it. The Header Filename: is a special Include File at the start of your source code. It has the same effect as having an Include directive on the first line of your source code. The INCDIR path list: allows you to specify a list of directories (separated by +'s) from which Include files will come. This is the same as the INCDIR directive within your source code. The Optimise: option allows you to select whether ArgAsm will attempt to optimise any instructions it thinks could be smaller or faster. It will always ensure optimisations are safe and will report how much was optimised at the end of the assembly. Future versions of ArgAsm will incorporate more powerful optimisation features. Programmers normally want to do the optimisations themselves anyway, because they can restructure their code to make it better for short branches, etc. The Statistics: option will make a report after assembly telling you useful titbits of information such as how big your object code was, how full was the macro table, how the disks and assembler performed etc. And finally, you get to hit Assemble to proceed or Cancel if you are not ready to assemble, in which case you will be dropped back into the editor. THE BLOCKS MENU To mark the start of a block at the current cursor position, select Start (or hit F1). A block is only valid when it has a Start and an End defined. This block will be shown in highlighted text. To mark the end of a block at the current cursor position, select End (or hit F2). All text between the start and end of a block will be highlighted. Once marked, blocks can be saved, deleted, copied or generally played about with. Once marked, you can save a block with Save (or hit F3). This will prompt for a filename with a file requester just like Saving a file. To Copy a block to the cursor position, select Copy (F4). This will insert the block into the text as if you typed it in again at the cursor position. The original marked block will remain untouched and will still be marked. To Paste in a block that has been previously remembered, select Paste (or hit F5). To Delete a block, select Delete (or hold Shift and press F3). This will remove the text contained within the block and will destroy any markers. To remember a block for later pasting, select Remember (or hold Shift and press F4). This copies the block into the Paste buffer but leaves it intact in the source file. To cut a block for later pasting, select Cut (or hold Shift and press F5). This first copies the block into the paste buffer and then deletes the block from your source code. THE SPECIAL MENU To take a Snapshot of what you are doing so that you can come back to it later in the same state, selectSnapshot. This saves off ArgAsm's internal information so that it remembers all the windows you had open (and their position), all the files you had loaded, and the text that was in all the requesters. A simple programmers' calculator is built-in by calling ArgAsm's expression evaluator with the Evaluate option. You can type out little sums and get the results back in hex, decimal, binary and octal. ArgEd's user configurable Preferences are altered by selecting Preferences. These can be saved out so that every time you run ArgEd it sets things up just the way you like it. PREFERENCE OPTIONS There are a number of on/off gadgets where you can select whether various features are enabled. Auto Fullsize instructs ArgEd to open up the largest possible window whenever you run it. Status Line will draw up a status line on the bottom of each window containing the line and column number that the cursor is on, and also how many bytes the file takes up. Auto Indent allows ArgEd to insert tab (or whatever indent you last used) every time you press RETURN. The Slider Bar will select whether ArgEd displays a verticle slider bar on the right hand side of each window. This bar can be dragged or clicked on with the mouse to scroll the screen around. Auto Snapshot will automatically perform a Snapshot each time you Quit ArgEd. This allows you to continue where you left off, provided that the Auto Load option has also been enabled. NOTE: scoll and paging speed will be affected by the slider bar and status line on the screen. If you want fastest possible text manipulation turn these options off, alternatively if you want to know where your cursor is (and lets face it, who doesn't) leave them on. THE ARG.INF PREFERENCES FILE ArgEd's preference settings are stored in a file called 'Arg.Inf' in the current directory. If it is not found, ArgEd will pick sensible defaults and you can then Save your preferences again. If you ever have trouble with your preferences simply delete the Arg.Inf file before running ArgEd. This can happen if you are upgrading to a new version of ArgEd and the internal variables have changed format. SOURCE CODE TEXT FORMAT ArgAsm supports the Motorola and Commodore standard line format for source code text in a source file as defined by Metacomco. This is also compatible with most other Amiga assemblers including Devpac and CAPE as well as a number of PD offerings. ASSEMBLY SOURCE CODE LINE FORMAT. Source code lines may contain any or none of the following: a label, an instruction or directive, some parameters, and a comment. Lines may also be intentionally left blank (ie: just a linefeed character), or may consist of just a comment with no instruction or parameters at all. A typical line of text in a source file looks like this: Label Instruction parameter Comment eg: frog clr.l d0 *Clears D0 reg. moveq #O,d0 So does this 1$ move.l #Zero,D0 ;And this too! .prg st d0 *This doesn't. *This line only contains a comment. ;Me too As you can see from the examples, there is a TAB character between each field. You can use any amount of White Space characters between each field, but we recommend you use a TAB because it spaces things out nicely, and a single tab is faster for ArgAsm to parse than a series of spaces. Labels should always start at the first character of the line. If you don't want a label on the line, then use a TAB to ensure that the Instruction field is not at the start of the line. You can optionally terminate a label definition with a colon (:) character for compatibility with older assemblers, but this is unnecessary. Labels usually start with an alphabetic character (eg: A-Z) in lower or uppercase. You can also start them with Underscores (_) for C compatibility, or dots (.) for textual local labels. The remainder of the label can contain any alphabetic or numeric characters eg: A-Z, 0-9. Numeric local labels can only contain the digits 0- 9 and must be followed by a Dollar $ sign. Labels are not required on source code lines unless you want them there. This might be because you will reference that line from elsewhere in the source code (eg: A subroutine call), although some directive requires a label to be present (eg: EQU). Examples of good labels are: frog, _frog, Frog2, frog:, crunchy_frog Good Local labels are: 100$, 999$, .10, .frog These are bad labels because they either don't start with an alphabetical character, or they contain illegal characters: 2frog, frog*, fr+og, spring-sunrise, its(pining The Instruction field of a line of source code contains any valid 68000 instruction, macro call or directive. eg: MOVE, CLR, or PAGE. In addition, they may contain the size parameter seperated by a full-stop from the instruction itself, eg: MOVEM.L, or BRA.S. Valid 68000 sizes are .B for Byte, .W for Word, .L for Long and .S for Short. Instructions must always follow a TAB (or any other whitespace) character, which itself would have followed a label at the start of the line if one was required. The Parameter field of a line contains any operands that may be required by the instruction or directive. This field is not always used by some implicit instructions (eg: RTS, or NOP). For instructions that require more than one operand they must all be specified close together seperated by a comma. No spaces or TABs are allowed until the end of this field, as that would signify the start of the Comment field (as per the Motorola standard). The Comment field is totally ignored by the assembler, which simply skips over it to find the start of the next line to continue assembling. You can put any comments to yourself about what your code is doing, or how it works its magic. A comment starts after the parameter part of the line, provided you put a whitespace (eg: TAB) to seperate them. You may start your comments with an asterisk (*) or semi-colon (;) but this isn't required as the Motorola standard dictates that a comment starts immediately after a blank in the parameter field. In addition, you may have a comment on a line on its own by starting the line with an * or ; instead of a label. The entire line will be treated as a comment so do not put any instructions or directives there. CASE SENSITIVITY. All instructions, directives and registers can be typed in either lower or uppercase (or if you are feeling weird, a mixture of the two!). Its really down to personal preference, but we prefer lower case, because it appears friendlier. The exception to this are Labels of any form (eg: equates, program labels, register equates and macro names). These are usually Case Sensitive, which means that 'Frog' is different from 'frog' and so too is 'FROG'. You may override this default by setting the case insensitive option (OPT C- in your source code), which will uppercase all labels for you. This has disadvantages if you wish to use a LINKER with other people's object codes, so try to keep your labels case sensitive if you can help it. ADDRESSING MODES. These are the Addressing Modes that are supported by ArgAsm. They conform to the Motorola standard and are listed overleaf as a summary for reference purposes, with a few examples. Addr Mode Explanation Dn Data Register Direct eg: d3,d0,d7 An Address Register Direct eg: a2,a6,sp (An) Address Register Indirect eg: (A4),(A1),(SP) (An)+ Addr Reg Indirect with Post Inc eg: (A3)+,(A0)+,(SP)+ -(An) Addr Reg Indirect with Pre Dec eg: -(A4),-(SP),-(A1) d(An) Addr Reg Indirect with Disp eg: 100(A3),4(SP),1000(A6) d(An,Rn.s) Addr Reg with Index eg: $100(A3,D0.W),4(A0,A1),(A3,D0) d.W Short Absolute Address eg: 4.W,1000.W,-4.W d.L Long Absolute Address eg: $DFF180,32788,$bfe001 d(PC) PC Relative with Disp eg: 1000(PC),*-2(PC),0(PC) d(PC,Rn.s) PC Relative with Index eg: 100(PC,D0.W),255(PC,A0),(PC,D0.W) #d Immediate data eg: #100,#1000,#%1010101 In the above sequence, d is a displacement or number, n is a register number (from 0 to 7), An means an address register from A0 to A7, Rn is either an Address or Data register, and s denotes the Size W or L (Word or Long), the default is Word sized for most instructions and addressing modes. Disp means Displacement, Inc and Dec mean Increment and Decrement respectively. ArgAsm will allow you to leave off the initial displacement from any Indirect addressing modes that normally require a displacement and will insert a zero in there when assembling, eg: (A1,D0) would assemble into 0(A1,D0). Similarly you can leave off the displacement from any of the PC relative addressing modes, and an asterisk (current PC) will be assumed. Eg: (PC) will become *(PC) etc. EVERYTHING YOU WANTED TO KNOW ABOUT LABELS There are three types of Label in ArgAsm, all of which can be used to mark parts of your code as subroutines or places of reference. The types are; Real Labels, eg: fred, jim and sheila. Local Labels, eg: 1$, 999$, and 10$ Textual Local Labels, eg: .fred, .jim, .sheila and also .1, .999 etc. ArgAsm will not mind if you feel the uncontrollable urge to terminate label definitions with a colon (:) character. But please try not to make a habit of it :-) It reminds us too much of those old Sixty Eight K Assemblers that have no formatting or neatness abilities. WHAT ARE LOCAL LABELS? Local Labels are used at times when you honestly cannot think of a real label name to put there. Try as hard as you might, you have exhausted all potential abbreviations for what the subroutine was supposed to do, and simply cannot find any more swearwords with numeric suffices to put as a temporary label halfway down a routine. Also, you may have run out of frog's, froggy's, fish's etc. At times like these, it is a wise idea to start using Local Labels. They may take some of the fun out of label naming, but at least they are quick to generate. For example, there is little known (or used) convention, that 999$ is usually the last label in a small subroutine that way you can branch to it easily. Of course there are those who argue that something little known and little used cannot be a convention. A Local Label is only Local when used wholly inside the bit of code seperated by next and last real (ie: non-local) label you defined. This is limited scope label and can be reused as often as you wish with the same name or number provided you are using them after a new real label. For convenience, we provide the nnn$ type of local label which is a standard in the Amiga community, but this is limited to numeric digits only. We have also implimented textual local labels that start with a dot (.) in a compatible way so that the two can be used interchangeably. eg: .1 is the same label as 1$, similarly .321 is the same as 321$. Naturally .fred has no nnn$ alternative, because of the limit of only numeric digits allowable in nnn$ local labels. SCOPE OF LABELS. Some older technology Assemblers on the Amiga have a lot of different symbol tables for each day of the week, phase of the moon or number of characters in the label. We preferred the more useful approach of having just one symbol table. It makes the code much more clearer, and faster too. But we had to insert some logic to seperate labels of a similar name that were used in different contexts. Any normal label value, whether it was defined in the programme code, or by an equate (EQU) cannot be redefined anywhere else. It is set once, and stays at that value. If you want to be able to change the label's value you can use the SET directive to initially define it, and then can successively redefine it (with SET) anywhere you want. This is useful for setting up counters or loops in conjunction with macros. You may define a Label to be equated to a Register by using the EQUR directive. This allows you to use that label as if it were a register in the rest of the code. All register equates must be defined before they are used, and once defined that label name cannot be used by a symbol value elsewhere (eg: for an EQU), so take care not to use register equates and label equates that clash. Macro label names can have the same name as a symbol label name without clashing because they are context sensitive. ie: Macro labels can only appear as instructions or directives. They are never used within expressions, or operands which is where symbol labels would be used. So take care not to be confused by this feature. BEWARE OF AUTO ALIGNMENT. The 68000 Program Counter must be a multiple of two (known as 'Even Aligned') to execute instructions. This can be assured by using the EVEN directive after every time you incorperate byte data into your code, eg: after every DC.B or DS.B statement. Failure to do so will generate an Address Error exception which will probably give a GURU or System Message on your machine, even with a 68030 processor! ArgAsm, like most modern assemblers, will auto-align the program counter to be on an EVEN boundary if you try to put an instruction or word/longword data word onto it. This feature in itself is harmless, and in fact helps sort out most problems where the programmer forgot to do a CNOP 0,2 or an EVEN after they were using an odd number of bytes of data in their code. eg: * start at location 0. dc.b 0 * the pc is now at loc 1, ie: odd frog dog nop * This nop starts at loc 2 * because it was Even Aligned. Note that the label frog will be equal to 1, since it is immediately after the odd pc left by the dc.b. However, label dog will be equal to 2, because the NOP was even-aligned from 1 to 2 and its corresponding label will be as well. But have a look at this piece of code... * start at loc 0 again cat dc.b 0 * cat=0, and leave pc at 1, ie: odd frog nop * pc is Even Aligned to 2 as usual. The problem to watch for is if you did not have two labels after dc.b, with there being only one label it will be autoaligned because of the NOP even if you were expecting it to be the value of the pc after the dc.b. eg: you would expect frog-cat (frog minus cat) to be equal to 1, but it will be 2 because the frog label was autoaligned. To solve this, either do an EVEN after any use of dc.b's that might potentially be odd, or have multiple labels after an odd byte entry, one label that represents the end of the set of bytes, and not to have any code next to it. The other label will represent the start of the following code, which will be Even-aligned. DO BE WARY OF THIS AUTO ALIGNMENT POTENTIAL FOR MISUSE, AS IT IS KNOWN TO HAVE CAUSED MANY A DEBUGGING HEADACHE IN DAYS GONE PAST. WE HAVE IMPLIMENTED WHAT WE BELIEVE IS THE CORRECT WAY OF HANDLING THIS PROBLEM, AND IT TALLIES WITH THE WAY MOST OTHER ASSEMBLERS HANDLE THE SAME SITUATION! EXPRESSIONS. ArgAsm utilises a full 32 bit integer expression evaluator of a form similar to that used in high level languages. Complex expressions are allowed containing all the usual intricicies including unlimited parenthesis levels (brackets), prioritised operators, unary operators, and of course logicalk operations. Most Expressions will take the form of: [unary minus or plus] [number] [operator] [number] etc It is important to note that expressions are either Absolute, or Relative. Absolute Expressions are those where you specified the number directly or from Equates (EQU, SET etc). Relative Expressions are those where they refer to labels that are in of the program code itself, and as such their values are not known until the program has been loaded by AmigaDOS. In general, it is safe to do any type of expression made up of Absolute values. But you must be careful when mixing Relative and Absolutes together. For instance, frog+2 is a perfectly valid reference even if frog was a bit of the program code and is thus relative. But frog*2 is not, since the address of frog is not known at Assembly time, and will only be confirmed when the program is loaded at runtime. The list of operator precedence in ascending order of priority: SYMBOL FUNCTION = Equals < Less than < * > are the same level > Greater than + Addition + & - are the same level - Subtraction * Multiplication * & / are the same level / Division & Bitwise AND ! Bitwise OR ^ Bitwise XOR << Shift left << & >> are same level >> Shift right ~ Bitwise NOT - Unary Minus + Unary Plus The Unary operators + & - are the highest priority. Expressions are always evaluated from left to right unless operator or parenthesis priorities dictate a different order. You can override the priority of operators in an expression by judicious use of the parenthesis brackets ( and ) to surround the parts of the expression you want at a higher priority. You can nest the parenthesis an almost unlimited amount deep (255 levels is pretty deep). All expressions are performed using signed 32 bit integer arithmatic. No overflow conditions are checked. Expressions must not contain any spaces or delimiters of any sort, as this would signify the end of the expression (and the start of a Comment under normal Motorola rules). USING EXTERNAL REFERENCES INSIDE EXPRESSIONS (XREF'd symbols). Due to a linker format restriction, only simple expressions are allowed when dealing with external references. You can only add or subtract numeric values to external references, any other operation would be meaningless since Amiga Linkers do not support expression evaluation at this time. Any symbols that are to be used as external references should be declared before use, by the XREF directive. Once a symbol has been referenced by any part of you sourcecode, its Type is recorded. If it wasn't XREF'd in advance of that time, then it can't be at a later date. The best place to put your XREF's is at the start of your source files. (The same goes for Macro definitions, and EQUR's etc). BASES FOR NUMBERS AND CONSTANTS ArgAsm supports a full range of base numbering systems, including the ever popular hexadecimal, and decimal, but also the less popular binary and octal bases. Also, ASCII character constants are supported. Leading zeroes are not required, and are in fact ignored (but trailing zeroes are obviously pretty important!) Decimal numbers start with a digit, eg: 123 or 95. Hexadecimal numbers start with a Dollar $ sign, eg: $100 or $fabc. Octal numbers start with an AT @ sign, eg: @777 or @012. Binary numbers start with a Percent % sign, eg: %1010101 or %1111. Also, Character constants can be used in expressions by enclosing up to 4 characters between a single or double quotes (' or "), eg: "DOS" or 'A'. These character constants are Right Justified into the constant. Ie: The last character in the string will be the lowest significant byte of the number constant. Inside a character constant you may wish to use the same quote that you were using as a delimiter. In this case, two qoutes of the same type will give you one normal quote inside your character constant. eg: "A" becomes A in hex$00000041 '@ @' becomes @ @ in hex $40204020 "DOS",1becomesDOSin hex $444f5301 'IT''S'becomesIT'S' hex $4954275C '"A"'becomes"A"in hex£00224122 Special Symbol * An asterisk * is a special symbol in an expression and is used to mean the current Program Counter value (ie: the address of where you are in memory in your program). This is usually a relative value. Do not be confused between * as the PC, and * as multiplier operator (or indeed * as a comment!). Since it is not useful to multiply the PC by any value, this confusion will not crop up much. eg: bra.s * ; Loops infinitely lea *+10(pc),a0 Blink, The Linker. Supplied on the ArgAsm distribution disk is the Blink linker written by the Software Distillery. A later version of BLINK (curiously versioned 5.04) is available from lattice as part of their C Compiler package. Blink is largely compatible with commodore's ALINK only faster. The CLI usage for Blink is; 1> BLINK prog1.o,prog2.o TO Prog Further power-user features of blink can be discovered by typing BLINK on its own. ArgAsm Directives So as to minimise any alteration to your existing source code, we have made ArgAsm very closely compatible with its contemporaries. These include Hisoft's Devpac v2, Inovatronic's CAPE v2, and Metacomco's ASSEM v10 and so (alas) our supported Directives list is rather long and contains numerous different functions of a similar nature. You have CAPE to thank for the myriad of extra non-standard directives whereas Devpac's extensions were more subtle but equally powerful. Either way, we have implemented almost all of them (for completeness. END This an optional directive that terminates the assembly of the current source file. Assembly will terminate when the end-of-file is reached so the END directive is mainly for causing premature endings in conjunction with conditionals. Note: Any ENDs in Include files will terminate THAT specific file, and return assembly to any previously active source code. INCLUDE This will read in a file from disk and insert the named source code into the assembler at the exact position of the INCLUDE in the current source as if the text was already there. The filenaame can optionally be enclosed in double or single quotes if it contains any characters likely to confuse the assembler or AmigaDOS (eg:Spaces). The filename can incorporate a full drive name, device, pathname, assigned path or any other legitimate AmigaDOS filename. eg: INCLUDE myheader.i INCLUDE "Includes:hardware/blitter.i" Includes can be definitely nested (as much as available memory allows) but we recommend you to keep the nest level as low as possible for your own sanity and debugging ease! The filname specified is loaded either from the current directory or from the directory specified by a previous INCDIR (INClude DIRectory). If the Include filename contains a drive or device name (text followed by a COLON: character) then this overrides any INCDIR directive and loads the file from the specific area of the disk! ArgAsm will always make best use of available memory, and try to load the entire INCLUDE files into memory in one go. If memory is lacking, ArgAsm will complain bitterly, and you will either have to buy more RAM, or find a way of splitting your files into smaller more manageable chunks. A future version of ArgAsm may be more able to cope with low memory assemblies, but the present version was designed for performance rather than memory efficiency. INCBIN This will read in a binary data file (such as screen data, sprites, sound samples etc.) directly into the current position in the object code and update the Program Counter accordingly. Beware of odd-length files that might cause the PC to be incorrect afterwards. ArgAsm will automatically align the PC for your safety. EVEN The 68000 series of microprocessors cannot execute instructions that are on ODD boundaries (not even the 68020 or 68030!) This directive will align the Program Counter to be EVEN (ie: a multiple of 2), and is mainly used after byte directives like DC.B that may have left the PC in a ODD state. Note: ArgAsm tries to autoalign instructions so that the PC to be EVEN all the time so this instuction is largely for compatibility with previous assemblers. See the warning about auto-alignment in the Labels section. CNOP , This will align the Program Counter in any custom manner you want. If you wanted to Word Align the PC, you would do a CNOP 0,2 and similarly to Longword align you do a CNOP 0,4. The offset allows you to index into your alignment. Thus CNOP 2,4 will place the program counter 2 bytes into the next Longword boundary. You can within reason have any offset and alignments you want, but avoid silly numbers (that are too big!) ORG
This will force the Program Counter to be on a specified absolute address and is mainly for creating Absolute Code for use on a target machine. We do not recommend using this directive on a native Amiga unless you know a lot about the memory orginisation and disable the Amiga OS (a brave move!) This is mainly used by Games Programmers. DB DW DL Cape compatible alternates of DC.B, DC.W and DC.L (see below). DC.B (expressions> DC.W (expressions> DC.L These directives are for defining constants (data areas) of the specified size into the program at the current PC address. The Expressions can be separated by commas to have as many as you can fit into one line! Expressions can be any combination of labels, numeric values, or textual strings in quotes. Be wary of any spaces in your DC expressions, as they signify COMMENTS and can lead to many a bugette! eg: dc.b If,"Hello there Frog",0 dc.w 65535 dc.l 10000,1000,100,10,1 DS.B DS.W DS.L These directives Define Space rather than constant. It will reserve space of the desired amount (filled with zeroes), and is used for preinitialising large buffer areas. eg: DS.L 10 will reserve 10 Longwords (40 bytes of zero) of space whereas DC.L 10 will put in the longword value 10 into memory! Note the difference, as it can lead to many a typo bug in those early morning hours! eg: These DS's will reserve 1000 bytes of space. ds.b 10*100 ds.l 250 ds.w 1000/2 The Expression must evaluate immediately with no forward referenced labels! Be careful with large DS's that might overflow the object code buffer! DCB , This directive allows you to define a constant block. Unlike DS, a DCB will allow you to specify the filler data as well as the amount of times it will be copied. eg: DCB.B 100,$ff will reserve a block of data 100 bytes big each containing an $ff. FAIL This directive will prematurely terminate the assembly with an error message. It is usually used in conjunction with conditional IF statements to check for errors or lack of data, or incorrect macro parameters. OUTPUT This directive specifies the filename that will be used to write out the object code when the assembly has completed. It can be set on the command Line, or inside your source file. Note: It can only be set once. OBJFILE The Cape compatible version of OUTPUT. _G2 (reserved symbols) _ArgAsm These are special reserved symbols that you can check to see which assembler you are running on. Best used in conjunction with conditional assembly. REPT This directive will repeat the block of code contained between it and the next ENDR a specified amounts of times. Best used for opening up small loops for preformance purposes. Repeated loops cannot be nested. ENDR Closes the last part of the source code to be repeated (see REPT). LIST This directive on its own will turn on the assembly listing output. You can use NOLIST to turn the listing off at any time afterwards. List will also accept ON, OFF, + and - as alternative forms of turning the assembly listings on and off. NOLIST This will turn off the assembly listing output. PLEN This will set the page length, ie: The number of lines that fit onto each page of your printout. Can be between 12 and 255, the default is 60. LLEN This will set the Line LENgth, ie: The number of characters that fit onto each line of your printout. Can be between 38 and 255, the default is 132. TTL This will set the title of your printout and will appear at the top of each page of your printout. SUBTTL <subtitle string> This will set the subtitle that appears under the title on each page of your printout. SPC <expression> This will leave a specified number of lines gap in the Assembly Printout. PAGE This will eject the current page on your printer output. <label> EQU <value> <label> = <value> Allows you to define a label to be specified value or expression. It must evaluate immediately and cannot contain a forward referenced label. <label> EQUR <register> Allows you to supply names for your favourite registers, and then use them in the rest of your source code as their newfound names. We do not recommend this feature as it tends to make code unreadable, and also slows down the Assembly. It is implemented for compatibility reasons only. <label> SET <expression> Allows you to define a label, much like EQU but has the added feature of being redefinable at any time. Has hundreds of uses, but we can think of only one right now... use it as a counter inside the Macro's or Repeat loops by saying: frog set 0 rept 100 frog set frog+1 dc.w frog endr The above will generate 100 words in memory numbered 1 to 100. <label> REG <register list> This allows you to name lists of registers for use in MOVEM instructions. Its primary use is to ensure you stack and unstack the same registers when entering and exiting your subroutines. <label> RS.B <expression> <label> RS.W <expression> <label> RS.L <expression> This Reserves Space in a Counter allowing you to define lists of offsets from the start of a data structure. It does this by incrementing a counter used only for the RS set of directives. It does not affect your code or data in any way. Best used for interfacing with other people's offsets in their data structures (eg: Commodore Include Files). RSRESET This sets the RS counter to zero, and is usually used at the start of a data structure list. RSSET <expression> This sets the RS counter to zero, and is usually used to start the RS's at a position inside the structure. _RS <reserved symbol> This contains the the current value of the RS counter. (It starts with two underscore characters). _G2 <reserved symbol> This contains the version number of GenIm2 that we were using for test, and is intended to pretend to be Devpac compatible so that sourcecode that assembles under GenIm2 will assemble under ArgAsm too. _LK <Reserved symbol> This a Devpac compatible symbol that currently gives a 3 if the code file format type is Linkable, and a 4 if it is Executeable. ARGASM OPTIONS SETTINGS. Devpac compatible options. OPT <optionlist> This allowsvarious option settings to be altered within the source file. Most of these can be defined from the CLI at the start, or will use sensible defaults. Options are usually a single letter followed by a + or - sign to signify On and Off respectively, like C+ or D- and muliple options can be done on the same line separated by commas. OPT C+,L+,W- The above line sets case Insensitivity ON, Linking object code ON, and Warnings OFF. Supported Options C - Case Sensitivity On/Off. When Case sensitivity (or Independance) is turned OFF, all labels are converted into upper case before use, which allows you to ramdomly use either upper or lower case in your code as it all gets turned into upper case anyway. If you can do without, we recommend you keep case sensitivity ON because it produces easier to read labels, especially when they consist of multiple words (eg: which is more readable, ConvertSprites or CONVERTSPRITES?) Defaults to ON. D - Debugging Information On/Off. When the Debugging flag is turned ON, the Assembler will output all symbol definitions whether they were XDEFed or not into the output file, that way they can be accessed by a monitor or linker for debugging purposes. This makes the object file significantly larger than usual. Defaults to OFF. E - Error list output. ArgAsm will buffer up to 255 error messages, and then report them at the end of Assembly if this option is enabled. L - Linker Mode On/Off. When the linker mode is turned ON, you can use the XDEF and XREF directives to access external references in other object files. The object files are written in a format suitable for an Amiga compatible linker, eg: (ALINK, BLINK etc.) When turned Off, the object files are generated as Executable, so a linker isn't necessary to convert them into runnable AmigaDOS files. This option can be chosen only at thestart of your source file, and cannot be changed afterwards. Defaults to ON. M - Macro Expansion in Listings On/Off. When Macro Expansion is turned ON, the Assembly Listing will contain every line that is inside Macro definitions. When turned OFF, you will only see the MACRO name, and not its contents. You can turn this feature on and off anywhere anytime. Defaults to OFF. O - Optimisation. This controls whether ArgAsm will attempt to optimise certain instructions with shorter faster versions. Defaults to OFF. OW - Optimisation Warnings. This allows you to inhibit ArgAsm's warnings when it optimises your code. Defaults to ON. S - Symbol Table Listing. When enabled, this will output a symbol table listing at the end of any listing output. Only the last S option found before the assembly is finished will have any effect. Defaults to OFF. W - Warnings. You can disable Warning error messages from being reported if you know what you are doing and don't want to be bothered by them. Be careful! Default to ON. CAPE COMPATIBLE OPTIONS. ADDSYM This adds symbols to the output file, and is the same as OPT D+ DEBUG This adds debugging information to the output file, and is presently the same as an OPT D+. In a future version of ArgAsm it will control the Lattice extended source level debugging information. OPTIMON This turns on Optimisations and is the same as OPT O+ NOOPTIM This turns off Optimisations and is the same as OPT O- NOOBJ This disables any object code generation for this source file and is similar to doing a -B at the CLI level. CONDITIONAL ASSEMBLY DIRECTIVES In general these operate in a similar way to the 68000-style Bcc branch condition codes and hopefully make them easy to remember for those who actually know 68000, and if you don't, now is a good time to learn. The IF directives are immediately followed (without a space) by a condition like IFEQ or IFGT. The supplied expression is evaluated and then compared with zero (0). The resulting condition dictates whether the source code is ignored or assembled until the next matching ENDC. The expression in a conditional MUST evaluate without forward referenced labels. Infinite nesting of conditionals is supported, but please watch yourself for losing track of your IFs and ENDCs. ArgAsm will keep a count of the nest level, and if a mistake should occur (an imbalanced IF and ENDC pair) a suitable error message is reported. The main use for conditional assembly is in producing code that contains extra bits for debugging, eg: printing out vital information for the programmer to see. An equated label at the start of your sourcecode could be set to 0 or 1 depending on whether you wanted the debugging code included when you assemble. Conditionals can also be used for generating portable code to run on different assemblers, or for writing code that runs on different machines. IFEQ <expression> checks to see if the expression is EQual to zero. IFNE <expression> Checks to see if the expression is Not Equal to Zero. IFGT <expression> Checks to see if the expression is Greater than Zero. IFGE <expression> Checks to see if the expression is Greater or Equal to Zero. IFLT <expression> Checks to see if the expression is Less Than Zero. IFLE <expression> Checks to see if the expression is Less than or Equal to Zero. Note: On older assemblers that lack these flexible conditions, they usually implemented IF on its own, which is equivalent to our IFNE conditions. FURTHER CONDITIONALS IFD <label> Checks to see if the specified label exists. IFC 'string1'.'string2' Checks to see if the two strings match. IFND <label> Checks to see if the label doesnt exist. IFNC 'string1'.'string2' Checks to see if the two strings don't match. The strings are often supplied in Macro arguments to check validity. ELSEIF This inverts the current conditional flag, and allow an ELSE portion of a conditional to be incorporated into the IF...ELSE...END structure. ENDC This terminates a Conditional Assembly portion. After which, Assembly resumes as normal. IFcc-ENDC pairs can be nested as deeply as your heart desires. ENDIF The Cape compatible version of ENDC. MODULE <modulename> This directive defines the name of the current object module, the default if you don't bother is rather imaginatively named "ANON_MODULE" for historical reasons. Modules are useful for deciding which parts of a library will be used by the linker. If you never use this directive in your life be assured you won't be missing anything. SECTION <Section name>,<type> Some parts of your program may be required to load into chip memory (for instance, sprite or sound data) so you often want to have different named sections of your code loading into different places. The Section directive allows you to name parts of your program. Like named sections will be coagulated together before being written to disk. Valid code-types are: CODE, DATA and BSS. In general, Code is your main section and is used by all your code (and sometimes data). The Data section is purely for data and must not have executing code in it (since it could potentially be shared by multiple programs running at the same time), and the BSS section is uninitialised storage space that your program can use for scratch space. If you want your program to be able to Resident, then you cannot have a BSS section, and must dynamically allocate all the memory you require in runtime. Also, an underscore after the code type allows you to specify Chip (useful for sprite and audio data) or Fast memory, eg: section MySprites,code_c Amiga OS note: The opposite of Chip memory is Public memory (ie: do not specify a type) NOT Fast memory! Public memory (the default type) will load into Fast memory if there is any available, failing that it will load into Chip memory. Unless you are really sure you want it, Never specify Fast memory explicitly, as you cannot guarantee people will have any! SYMBOL IMPORTS AND EXPORTS XDEF <label>,<label> etc This allows you to specify which labels are to be exported into the object code for reference by other object codes during the Linking process. All labels to be exported must be XDEF'd first! It is best to put all your XDEFs at the start of your program where they can be found and modified easily. XREF <label>,<label> etc This specifies what labels are to be imported from other object codes during linking. All XREFs must be specified before the labels are used, so yet again it is recommended to have all your XREFs at the start of your program. COPPER INSTRUCTIONS The Amiga has a co-processor chip called The Copper that can perform screen synchronised control over the Amiga custom chips. It is best used for dynamically changing colour palettes, altering resolutions and screen positions, etc. The Copper has few instructions of its own that are usually implemented on other Assemblers with macros in hardware Include files. For such a powerful chip to be so inefficiently programmed seemed strange to us, so we implimented the popular Copper macro instructiuons CWAIT, CSKIP, CMOVE, and CEND as part of ArgAsm's vocabulary of instructions, that way making them much faster to assemble and more useable than the older macro counterparts. Although they are macros, you can treat them like instructions. Note: The Copper macros are provided for the use of constructing copper list data tables only. Don't confuse these Copper instructions with 68000 instructions. They are very different such that Copper instructions cannot be executed by the 68000 chip (and vice versa). For more details of Copper instructions, their usage and abilities see the Amiga Hardware Reference Manual. CWAIT x,y This waits for a given electron gun beam position before continuing with the next copper instruction. X and Y must be between 0 and 255, and the x resolution is very chunky. CMOVE value,register offset This moves a Word value into the custom chip register. The register offsets can be found in the Amiga hardware reference manual, and are all currently found starting offset from $dff000 in memory. The register offset is a Word, and must be even. CSKIP x,y This instruction skips if the electron beam is past the specified point. See CWAIT. CEND Terminates your copperlist. MACRO HANDLING. A Macro is a collection of instructions that are given a name, and can be called up by that name at any time in your source code. Macros are there to save typing and preserve readability, but when coupled with Conditionals and Parameters they provide some great powerful programming features. Macros must be defined, usually at the start of your source file, or in a header include file. They can then be invoked anywhere in your source code by using a macroname as if it were a new instruction. Unlike a subroutine call, a macro call puts the entire contents of the macro into your source file whenever you use it. Thus macros are faster to execute since they avoid having to JSR and RTS to get to them, but of course the penalty is they take up more memory. Whenever you use a macro call, the definition is 'expanded' into your source code as if you typed it in yourself. Macro's aren't just used to save typing in blocks of instructions. They can also be used to create tables or data in any format you require. Macro calls can also be nested as deep as you want, but the macro definitions cannot be nested at all. ArgAsm supports Motorola style macros both to the Commodore Metacomco standard, but also including the Devpac extensions that allow up to 36 parameters (instead of the usual 10) <Label> MACRO This is the way you start a macro definition. All lines up to the next ENDM will be put aside into a buffer ready for you to call them anytime by using the label name in your source code. Macros must always be terminated by an ENDM. Try to keep your macros small and flexible, that way you can re-use them in future programs and save yourself reinventing your macro wheels all the time. ENDM This directive terminates the current macro definition started using the MACRO directive. There can only be one ENDM per macro definition. MEXIT This will prematurely terminate the current macro expansion. It is often used in conjunction with some conditional checks to make sure the parameters given to the macro were correct. NARG <Reserved Symbol> In addition to the above directives, there is a special reserved symbol "NARG" (in uppercase) available that you can use in your macro expressions at any time. It returns the number of parameters passed to your macro. This is commonly used to make sure your macros was passed the correct number of parameters in conjunction with some conditionals and the MEXIT directive. Outside a macro, NARG returns 0. MACRO EXPANSIONS & PARAMETERS To expand an already defined macro, you use its name, followed by up to 35 parameters seperated by commas with no spaces. eg: FRED 100,200,300 Inside the macro definition, you would refer to each parameter with a backslash (\) character and followed by the numbers 1 to 9, then A to Z to correspond to parameters 1 to 9, then 10 to 35. As the macro is expanded, any occurrences of backslash parameters are substituted with the actual text of the parameters. That way, you can have words, or instructions or numbers as your parameters. To include spaces or commas in your parameters you must enclosed the whole parameter in angle brackets eg: <THIS IS PARM 1, ok?>. There is also a special parameter \0 which refers to the Size given in the macro call. Like most Motorola instructions, it defaults to Word sized (W) if no size was specified in the macro invocation. EG: FRED.L 100,200,300 Would return \0 as an L, so your macro definitions would look something like... FRED MACRO MOVE.\0 #\1,D0 MOVE.\0 #\2,D1 MOVE.\0 #\3,D2 ENDM The above macro, when called would put a Longword of 100 into d0, 200 into d1 and 300 into d2 respectively. but: FRED 10,50,-100 ..would expand to a Word sized macro (since \0 defaults to W and no size was specified) and would load a Word of 10 into d0,,50 into d1 and -100 into d2 Other Backslash functions... \@ gives a unique _nnn text string where 'nnn' is a number incremented each time a macro is used. This allows you to have unique labels embedded within your macro since if you used normal labels then your macros would forever by trying to redefine labels that already exist. eg: FRED MACRO CMP.L #\1,D0 BGT.S FROG\@ RTS FROG\@ MOVEQ #0,D0 RTS The above macro, when called with one parameter will insert a piece of code that, when executed will check to see if the parameter supplied was larger than D0, and if so, D0 will be cleared. If the label FROG was used on its own without the \@ then you would not be able to use macro FRED more than once because FROG cannot be defined multiple times. But using the \@ gives each label a unique numeric identifier allowing it to be different on each occasion that you use the macro call. If you wish to retrieve the value of a symbol inside your macro expansion, you can use the \<symbol> to expand it into a decimal number, and \$<symbol> for hex. The symbol must be absolute and already exist to be used in this manner. To get a true backslash (/) character within a macro expansion, you must use two backslash characters next to each other, eg: \\ would return a single \. In an assembly listing, the macro name is shown whenever you invoke a macro, but the actual text of the macro expansions are not shown by default unless you use the OPT M+ directive to turn on listing of macro expansions. This is because macros are usually to save typing, space, and paper and to promote readability. Macro call parameters can be longer than one line providing each line of the macro call parameters end in a comma (,) and the next line starts with an ampersand (&) followed by a space or tab, then followed by more macro parameters. ERROR MESSAGES AND EXPLANATORY NOTES There are four kinds of error and status reports that ArgAsm supports; Warning messages, Optimisation Warnings, Error messages, and Fatal Error messages. A Warning message is simply a reminder of a minor error or mistake in your source code that ArgAsm has duly noted and ignored since it wasn't worth bothering about. Warnings are primarily there to help you avoid bad habits or sloppy programming practises, but the more advanced users will probably want to turn these Warnings off. The assembler will continue with the rest of your source code quite happily after a Warning message. An Optimisation message is a reminder that ArgAsm has optimised an instruction, so that you can make that optimisation permanent in your source code at a later date. There is nothing harmful about ArgAsm optimising your code, as it has a set of rules that it carefully applies. The code will be functionally the same, right down to flag settings and which registers are affected. The Assembler will continue assembling the rest of your source code, as with Warning messages. An Error Message will notify you of any mistakes or problems in your source code that need your attention. The assembler will continue assembling your source code just in case there are more errors to find, but your object code will be invalid and it is not worth trying to execute it unless you are sure that the errors do not affect the specific bit of code you will be testing. A Fatal Error Message is an error so bad that it is pointless trying to continue assembling the rest of the file. These sort of errors must be fixed immediately if you want to get anything assembled. These errors are usually due to outside circumstances, like being unable to find a specified include file on the disk, or not being able to write out an object file. The Assembler aborts after a Fatal Error, and does not assemble any more source code until the problem is fixed. In general, ArgAsm will continue assembling your files, counting and remembering the errors and warnings for later examination. You have the option to display errors as they are found, or display up to 250 of them at the end of the Assembly. In general, ArgAsm will try and work out where the error was in the line of source code, and show the text and highlight the mistake as best it can. If the error was in a Forward Reference, then ArgAsm will not display the text of the line with the error, and will only display the error message and line number where the problem occured. One of the features of ArgAsm are the positive error messages. They don't just tell you whats wrong, they try and tell you why its wrong. Error messages are there to enable you to quickly find your problem and easily. Being vague is pointless, so ArgAsm tries to be as helpful as possible during its error reporting. In particular, it will try and give useful information as to why an error occured so as to help you fix it more easily. eg: When confronted with a BRA.S (short branch) to an address that was too far away, Other assemblers might report "Data too large" where ArgAsm would be more helpful and say "Byte Displacement out of range by 2 bytes" which would give you more of an idea how to fix it. Another example would be if you had used an IF but forgot the corresponding ENDC from your source code. ArgAsm would say "Conditionals aren't balanced, There is 1 more IF than ENDC!". If you ever see any Internal Errors (they say "Internal:" at the start of them) then please report them to us. These should never occur in normal usage and indicate a problem that needs our attention. If you see any 'Fatally out of memory errors' this means ArgAsm has run out of memory whilst deep within its expression evaluation routines. If this happens often, we suggest you buy more RAM for your Amiga, but in the short term try splitting up your source file into smaller chunks. Also, try pruning down the object code buffer with the -m cli option. If the memory is seriously low, ArgAsm may not have enough memory to exit safely again. At times like this, it may even crash. The bottom line is; make sure ArgAsm has all the memory it needs for the source code, object code, symbols, and macro definitions. Here is the ArgAsm Error list, in numeric ascending order by Error Number. Most error messages are self axplanatory, though some may have extra comments below them. LIST OF ARGASM ERROR MESSAGES. 1. Label defined twice You may have two labels with the same name. This usually occurs with Case Insensitivity. 2. Too many brackets ArgAsm supports up to 255 parenthesis levels. 3. Missing ( 4. Bad size,.B,.W, or .L expected 5. Dn,Dn or -(An), -(An) expected Some instructions like ABCD do not allow the normal collection of addressing modes. 6. Bad address register 7. Bad data register 8. Data register expected 9. Parameter error 10. Bad register 11. Fatally out of memory (Internal ...) The memory in your Amiga was exhausted before the assembly was finished, try saving memory by having smaller ramdisk, assembling smaller source files that use Include more effectively, also try pruning down the maximum object code buffer size with the -m cli option. 12. Not enough memory by n bytes This refers to the object Code buffer being full. Try a bigger buffer with the -m cli option. See error 58. 13. Reserved 14. Bad register 15. Illegal parameters, try (An)+,(An)+ 16. Operation too large, byte expected 17. Operation too large, word expected 18. Data Alterable (ea) expected 19. Data Addressing (ea) expected 20. Memory Alterable (ea) expected 21. Alterable (ea) expected 22. Control (ea) expected 23. Unrecognised addressing mode 24. Byte displacement: Out of range by n bytes 25. Word displacement: Out of range by n bytes 26. Label not defined If you reference a label that wasn't defined later on. 27. Operand too large, Nybble expected 28. Operand too large 29. No label for equate This usually occurs as a side effect of trying to do an EQU after a Label Defined Twice. 30. Address register expected 31. Unrecognised Instruction No Instruction, Directive or Macro definition exists of this name. 32. Data register expected 33. Missing quote 34. Panic! Premature end byte reached This should not occur! Report it to us, with an example if possible. 35. Macro storage space full 36. Macro definition requires name All Macro definitions must have a Label. 37. Nested macro definition You may not nest macro definitions. 38. Macro definition not terminated No ENDM was found, to terminate the Macro definition. 39. Only allowable in Macro definition 40. Unrecognised Instruction 41. Incorrect delimiting in parameter list 42. Undefined symbol 43. Too many parameters (max 35) (warning) 44. Immediate value expected 45. Value between 1 and 8 46. bad size, .W or .L expected 47. Register expected 48. Bad size, word expected 49. Bad size, byte expected 50. Garbage following instruction 51. Bad size, .S, .B, or .W expected 52. Short branch converted to NOP (warning) 53. Bad size, long expected 54. XREF'd symbol used in expression 55. Linkable code option not set 56. Can't export symbols 57. Referenced symbols cannot be XREF'd 58. Object Code Buffer full! Use the Assembly Option in ArgEd or the -m cli option to increase the Maximum object code buffer size. 59. Bad option An OPT directive was used with illegal parameters. 60. Option must be set at start Some options must be set before any code is generated, eg: OPT L+ (Linking or Executable mode) 61. Divide by zero You cannot have a division by zero inside an expression. 62. XREF'd symbol not allowed 63. ORG must evaluate No forward reference or xrefs are allowed for an ORG address. 64. Page length must be between 12 and 255! 65. Strange expression 66. Bad line length 67. Too many lines 68. Untitled? 69. Not implemented yet (alas) 70. Repeat up to 65535 times 71. ENDR found with no corresponding REPT 72. Expected CNOP Offset,Alignment 73. Not a valid effective address 74. Not a valid register list 75. Expected format: 'String1','String2' 76. No forward references allowed 77. Unexpected ENDC 78. INCBIN filename expected 79. INCBIN file read error 80. INCLUDE filename expected 81. INCDIR filename expected 82. OUTPUT filename expected 83. Object filename already specified 84. File not found 85. Could not Examine file 86. File Load error 87. File Save error 88. Name expected 89. Hunk type expected 90. List filename expected 91. List file already specified 92. Linker format restriction 93. Assembly interrupted by user You pressed Control-C! 94. Assembly failed A FAIL directive was issued in the assembly. 95. Bad size, long expected (warning) 96. Operand too large, byte expected (warning) 97. Not allowed in BSS section No code can be generated, only storage space (DS and DC directives) 98. Bad Copper instruction 99. Forward reference Short Branch converted to NOP. End.