›1m snma.hyper›0m ›1mSamu Nuojua's Macro Assembler, SNMA v1.90›0m ****************************************************** * * * S N M A V1.90 * * ~~~~~~~~~~~~~~~~~~~~~~ * ****************************************************** SNMA is 680x0 conditional macro assembler. Main contents: 1. ›3m Introduction ›0m Blabla bla blaa 2. ›3m Usage›0m How to use (start). 3. ›3m Features›0m Expressions, directives... 4. ›3m ARexx›0m ARexx interface 5. ›3m Author›0m Me. ›1m1. Introduction›0m Introduction to Samu Nuojua's Macro Assembler, SNMA SNMA is 680x0/6888x macro assembler. SNMA requires OS 2.0+. If you have used some other assembler, snma should not throw big suprises to your face (I hope). (Look at ›3m things to note ›0m) ›1m1.1 Copyright ©›0m SNMA stands for Samu Nuojua's Macro Assembler. SNMA is © copyright 1993-1994 by Samu Nuojua. All SNMA documents are © copyright 1993-1994 by Samu Nuojua. SNMA is FREEWARE. I reserve all rights to SNMA. You can copy it as long you don't ask payment (small fee is allowed to cover the expenses of the possible disk/postage fee). Permission is granted to upload SNMA to the bulletin boards and FTP sites. Also, you must provide all the files supplied when you are copying SNMA to somewhere/somebody (including all the documents). SNMA software and documents are provided 'as is'. No guarantee of any kind is given what SNMA does or that information in files is correct in any way. You are using this software at your own risk. Author of SNMA is in NO WAY responsible for any losses or damage caused by SNMA. ›1m1.2 What you need›0m What you need to use SNMA to produce stand alone programs. - AmigaOS 2.04 or higher (V37) - Linker (to produce executables) - Text editor (to write/edit programs) - The following libaries: V. Where note ~~ ~~~~~ ~~~~ - dos.library 37 in rom - intuition.library 36 in rom - utility.library 36 in rom - icon.library any * in rom WB support - mathieeedoubbas.library any * libs: fp support - mathieeedoubtrans.library any * libs: fp support - rexxsyslib.library 36 * libs: Arexx support Libraries marked with * are not neccessarily required. Math libraries are needed for the single and double floating point conversions. 6888x or 680x0 with FPU is needed for the extended floating point conversions. Rexxsyslib is needed for the Arexx support and icon.library for the WB support (if snma is started from the icon). You need linker to produce executables. There are several choices, snma should work with the ones which can deal with standard hunks. I have used DLink (from the freely distributable DICE, not the registered or commercial one, I don't know do they differ any way) and that works just fine and is free. Recommended: - Hard Disk - Manuals, manuals... - Debugger - Time (8') - Development tools (Includes and so on) ********************************************************************* * Remember, this isn't pascal, this is REAL programming. * * - 68000 Assembly language, techniques for building programs * ********************************************************************* (Good book (a bit old, however) by D.Krantz and J.Stanley). ›1m1.3 Installing SNMA ›0m There are couple of files to be copied. Installer ? Well, as soon as I have some time to spare. SNMA main file, copy somewhere under the search path if using snma in shell mode. In arexx mode snma needs to be started only once so its not so neccasary to be under the search path. SNMA has now icon so it can be started directly from the WB. SNMA.guide Documents in AmigaGuide format. Copy anywhere you like. examples/ Very simple example files. arexx/ Arexx macros. Copy to the rexx: directory the ones you are going to use. See also examples/alias.txt file. (User friendlies at the best 8'| ) ›1m1.4 Good & Bad›0m My personal view from this assembler. Things are not in any particular order. Good: - It's free. - Most common ›3m directives ›0m are supported. - Macros are supported. - All 680x0, 6888x, 68851 and 68030 PMMU instructions are supported - Does normal optimizations, including forward branches. - It's not terribly slow. - It's coded with assembler. (See below, Bad things). - Enforcer was in duty all the time I coded, checked, debugged... - Supports all data types of 680x0 6888x family (I think). (FFP conversions not supported). - ›3m ARexx ›0m interface. - Global symbol table Bad: - 68040/68060 instructions (those couple of) are not yet supported. - All source files must fit to memory at the same time. - Is coded with assembler. Messy code sometimes, my fault, my problem. (Moral: Assembly is two edged sword). - Doesn't support any small data model. - Some kind of beginners help would be good (sources...). - Only outputted format is Amiga object code. - No LINE DEBUG HUNK (or whatever it is) nor any new hunks. - This document is a translators nightmare!!!! From the one (TK) who tried to fix english... (Authors note: Oh, life is so hard. 8^) - No GUI, but I'm not sure would it even be useful. ›1m1.5 History of SNMA›0m Changes, fixes and additions I have made to SNMA ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ V1.90 o moveq didn't allow xref'd data. o mc68xxx directives o Command line additions ([-option]) o Object code naming now also checks ".s" and ".a" suffix. o OBJ filename in template was ignored (oh my). o tst with pc-relative was allowed on 68000 mode. o ext_ref symbols with same name were written many times, causing larger object file size (not actual code size). o xdef symbols were written to the all sections. o divu.l wasn't allowed. o Equates with relative components are handled better now. o Minimal WorkBench support o \*VALOF() + other macro 'insert functions'. o abslong to pc-relative optimizing. o DC generated too much data if the 2nd operand of the previous instruction was one which took some space. o REPT/ENDR directives o Global symbol table. o In cases where reloc was needed didn't create it, when symbol referred to equate which type was relative. o Equates with relative components are no longer written to the symbol list. o CHDIR (AREXX) command called FreeVec with wrong argument, causing memory loss (no crash, at least in my system). V1.70 o BTST/BCHG/BSET/BCLR Dn, set always as d0. (uups) o MOVEP didn't allow zero displacement. o ENDC switched assembly on sometimes when it shouldn't. V1.68 o Some minor bug fixes and changes (okay, I forgot them). V1.65 o Address components which started with 'Z' or 'z' were parsed to the totally wrong thing. (Bad one). o IFGT did unsigned test, instead of signed. o Didn't notice all cases when macro was already defined. o Include didn't work. o Expression handler didn't catch all undefined symbols. o AREXX, SET command. o 'TST An' in 020+ mode wasn't allowed. o Destination address mode optimizing in move instruction generated spurious opcodes in some cases. o Movem->move optimizing. V1.60 o AREXX PORT finally added o Several bugs fixed o LONGBRA flag to the template o ZAn no longer required if An omitted in addressing mode. Probaply I don't remember all the changes and fixed bugs, but I hope all the major ones are here. First released version of SNMA is 1.39. ›1m1.6 Bug reports›0m Bug reports are WELCOME. Please, state following facts: 1) Your system configuration (Model, CPU, MEM, OS, ...) and the version of SNMA. 2) What you did. Source code which caused bug. If I can't make the bug appear, it is awful task to find out what went wrong. If possible try to isolate the bug, only tiny piece of code is usually required to show it. Or if the bug is not directly related to the source code, describe it well enough (in any case). If you find out something is implemented badly, something would need a little polishing or something is missing, and things like that, suggestions are welcome. Where to report, see ›3m author ›0m. ---------------------------- --* fixed bug better bug *-- ---------------------------- ›1m1.7 Misc., general things›0m Some words from the inner working of SNMA ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ SNMA is not traditional two pass assembler altough its operations can be divided down to two stages. Source files are read and parsed only once. SNMA creates its own internal structures in this first pass. In the second pass, snma solves all undefined symbols, optimizes code, recalculates the changed values (like pc-relative stuff) and writes object code (and other requested files). Listing file creation is sloooow. (I suspect the buffered IO, but can't make sure because I don't have 3.1 where SetVBuf() actually does something). Memory usage of snma isn't the most economical, since all source files must fit in the memory and the way I implemented all the other stuff. Strip comments from the include files you use, because that reduces memory usage. As a memory usage example: One source code module: size 25625 bytes, 1061 lines with includes 7423 lines SNMA uses 99403 bytes to store source files, 225356 bytes to the all other stuff, total 324759 bytes. The way I have implemented macros costs memory because snma needs the produced macro lines to be in the memory in second pass where expressions with relative and undefined symbols are re-calculated and possible errors told. (SNMA won't read the source twice). I know, the actual snma file is quite large also. Well, can't help a lot anymore, without complete re-desing and re-write which is not in my top ten list of how to spend the next years of my life. (Actually I have managed to drop the size little). The development of SNMA ~~~~~~~~~~~~~~~~~~~~~~~ I started the development of snma somewhere on the first half of year 1993. I have coded SNMA entirely with the assembler, most of it with a68k and minor parts with snma itself. It works pretty stable in my system (A2000, GVP A3001 28Mhz 68030/882, 4M fast 1Mchip, OS2.04). I'm developing it in my free time and have spend long nights staring at my old 1081 and wondering what the **** is wrong with everything. Thanks ~~~~~~ I really must thank all you who have made so much wonderful 'Freely Distributable' software to Amiga. Special thanks to the following people for the software I mainly use while developing SNMA. - Charlie Gibbs, A68k - Matt Dillon, DME and DLink - Aaron Digulla, XDME - Steffan Becker, ToolManager - Jorrit Tyberghein, PowerVisor. ›1m2. How to use ›0m SNMA can be started from the Shell or from the WorkBench. ›1m2.1 Startup from shell›0m SNMA can be started from the shell like 'traditional' assembler. It parses it arguments using AmigaDOS 2.0 templates. Some of the options can be specified also in the ›3m 'old way' ›0m, i.e. with '-'. These 'old way' arguments override the template arguments. Command Line template: SNMA SOURCEFILE/A O=OBJ/K O=OBJ/K I=INCLUDE/K H=HEADER/K E=EQUATE/K L=LISTING/K Q=QUICKOPT P=PCOPT A=ADDRESSOPT B=BASEFORCE S=SYMBOL L=LONGBRA AREXX/S PORTNAME/K QUIET/S PAGELEN/K/N Where: SOURCEFILE is the name of the source file. It is a first argument and must be there always. OBJ defines the name of the object file. alias: -o INCLUDE defines list of directories where ›3m INCLUDE ›0m directive searches include files alias: -i HEADER defines file to be included before any lines from source file are assembled. Only one is allowed. alias: -h[] EQUATE defines equate file name to be created. Empty string is allowed, SNMA produces name from the source file name. Currently equate file is generated at the end of assembly. Symbols are taken from the hash table, so they are in mixed order. You can use AmigaDOS SORT command if you like some sort of order. alias: -e[] LISTING Listing file to be created. Minimal formatting can be done by using PAGELEN option. alias: -l[] QUICKOPT Quick optimizing flag, default: on PCOPT pc-relative optimizing, default: off ADDRESSOPT effective address optimizing default: on BASEFORCE Auto-force (Bd,An)->(disp16,An) default: on SYMBOL Write symbol data hunk default: off LONGBRA Long branches (wo/size field) default: off AREXX flag to start ›3m AREXX ›0m command host SNMA. Overrides others. QUIET Disables output PAGELEN Defines pagelen used in listing file. If null, snma does not create pages (useful if you want to do your own formatting). Default: NULL. See ›3m Options ›0m. SNMA does not check the stack anyway. I haven't had any problems with stack size of 4000 bytes. You can overflow stack with very deep expressions or very nested includes. One level on both cases takes about 100 bytes, so very means here something like 40 levels. Actually little less. If you worry about that, use bigger stack. See ›3m Examples ›0m (2.1.2). ›1m2.1.1 template: old flags›0m Many applications use the '-' as a option start character. (like: a68k file.asm -l -iinclude:). If you want just to flag that you want some file to be generated and want snma to create the file name from the source name, you had to pass empty string (like LISTING ""). I have to admit that this isn't very elegant method and when trying to pass commands to arexx macros I had several problems with the quotes. So, to allow easier use, couple of '-' flags are also allowed in commandline. In template they show as OLDFLAGS/M template. In the template explanation they are referred as 'alias:'. ›1m2.1.2 Command Line Examples›0m prompt> SNMA mycode.asm obj mycode.o include myinc: Mycode.asm is a source file, mycode.o is a object file and include files are searched from the current directory and then from myinc: directory. prompt> SNMA mycode.asm Q on A off B off S on I work:,work2:inc mycode.asm is a source file. Flags are set on and off. Include files are searched from the current directory, work: and work2:inc. prompt> SNMA mycode.asm EQUATE myequ produces myequ.equ named equate file and mycode.o object code. prompt> SNMA mycode.asm E "" produces mycode.equ named equate file and mycode.o object code. prompt> SNMA arexx Starts SNMA ›3m Arexx ›0m command host. prompt> SNMA mycode.s -e -l -iinclude: mycode.s is source code, -e and -l flags snma to produce equate and listing file, and -iinclude: tells snma to search include files from the include: directory. ›1m2.2 Workbench support›0m SNMA can be started from the Workbench, too. Its behaviour is controlled with ToolTypes. SNMA can assemble file(s) or start Arexx SNMA. You can disable ToolType removing it or setting it to parenthesis "()". Tooltypes: ~~~~~~~~~ AREXX flag to start snma in arexx mode. PORTNAME= AREXX port name. If omitted, uses default (SNMA) name. WINDOW= Specify output file. If omitted, snma will use its default output (CON:...). If AREXX flag is set too, no default output is created, if omitted. See ›3m Arexx/SET ›0m. The default tooltypes are so that AREXX snma will be started. You can have many SNMAs running at the same time (altough it is not very useful). If you click several times snma icon several SNMAs are started, each with dirreferent portname. See ›3m Arexx ›0m. To stop SNMA you have to send QUIT command to it. Here's how you do it from the shell: ->rx "address SNMA QUIT" where "SNMA" is the name of the arexx port. How to stop from the WB ? For example, use tool like ToolManager, and create the "SNMA OFF" command which is just like the above shell command. If you want to assemble files playing with icons, I suggest you to use for example ToolManager which makes your life a lot easier. I added the WB support mainly because it may be helpful to start SNMA in arexx mode from the icon. If you start SNMA from the WB and pass it arguments (you have selected other icons as well), SNMA will try to open WINDOW=, if omitted it will open its default output window. Then the passed file(s) is(are) assembled just like in shell mode. SNMA won't check any of the tooltypes of arguments and it does not check if there is already snma arexx host where the assembly could be directed. (I strongly doubt anyone will even use this method, but it was rather easy to implent so there it is). ›1m2.3 Starting the arexx SNMA host›0m SNMA can be started as arexx host and I suggest to use snma that way. Startup from: - Shell use AREXX template - WB use AREXX tooltype See ›3m Arexx ›0m section (4.). ›1m3. Features of SNMA›0m This section covers all the features of SNMA, relating to the actual assembly process. ›1m3.1 Source code format›0m The format of the source code is 'standard'. One line can be 256 bytes long (after macro expansion, too). One source code line may have following components: