NAME zmac - relocating Z-80 assembler SYNOPSIS zmac relfile,listfile=asmfile DESCRIPTION ZMAC is a Zilog mnemonic assembler with command and language syntax similar to DEC assemblers. "relfile" is the object file name, with the default extension ".OBJ" (for the format, see OBJ.DOC). "listfile" is the listing file, with the default extension ".PRN". In addition to standard disk files, you can specify "LST:" for the list device or "CON:" for the console. "asmfile" is the input assembly language file, with the default extension ".ASM". The output files are both optional, so that zmac frodo=frodo reads FRODO.ASM and creates FRODO.OBJ, while zmac ,frodo=frodo creates only FRODO.PRN, and zmac frodo,frodo=frodo creates both. Listing files are rarely needed except for final documentation, since lines with syntax errors are automatically listed to the console. If ZMAC is called with no arguments, it will obey multiple commands of the above format, prompting for each with "ZMAC>". Operating this way saves time, since the assembler gets read in only once. An empty command line terminates the input. INPUT LANGUAGE The language accepted by ZMAC is like that for the Zilog assembler, with a few exceptions... ZMAC does not require the "-$" after relative jump arguments. The standard and ZMAC syntaxes are as follows: standard: JR SOMEWHERE-$ ZMAC: JR SOMEWHERE . For equates, the syntaxes are: standard: BELL EQU 7H ZMAC: BELL = 7H . A colon is forbidden after an equated symbol, but both a colon and whitespace (space, tab, or carriage return) are required after a label. Symbols defined in the current module which are to be referenced in other modules (exported symbols), or those referenced in the current module but defined elsewhere (imported symbols) must be declared GLOBAL: GLOBAL WARFARE The ORG directive is illegal. There is instead the AORG ("absolute ORG") to set the program counter to a given absolute address. The bad news is that ZLINK has a bug in its handling of AORG. If one module has an AORG, then the NEXT module can't correctly import symbols. The good news is that an AORG is hardly ever necessary. ZLINK starts the code at 100H by default. There is also an RORG ("relative ORG") directive, which sets the program counter to a particular value with respect to the module beginning. Symbols and opcodes can be in either upper or lower case (no case distinction). A symbol may have at least 100 characters, and the first 16 characters are significant. In addition to the standard alphabetic and numeric characters, the four characters "_$.%" are also permitted in symbols. A "$" by itself stands for the value of the program counter (the location of the first byte in the CURRENT machine instruction). For example, an infinite loop can be coded as "JP $". Numbers should start with a numeral, which can be zero. By default, the number is interpreted in decimal. The base of the number can be set by a letter at the end of the number: D for decimal, H for hex, O for octal, or B for binary. The assembler can evaluate quite complex expressions. Multiplication and division have higher precedence than addition or subtraction (as usual for most software, but untrue for the Zilog assembler). Parentheses are permitted to enforce a certain evaluation order, but parentheses around an entire expression denote indexing. The unary operations are: + (no operation) - negate (2's complement) # 1's complement The binary operations are: + - * / as usual \ inclusive or & and EXAMPLE Consider the following assembly: C>zmac demo,demo=demo SSD RELOCATING (AND EVENTUALLY MACRO) Z80 ASSEMBLER VER 1.07 0 ERRORS ...or the equivalent assembly using interactive input: C>zmac SSD RELOCATING (AND EVENTUALLY MACRO) Z80 ASSEMBLER VER 1.07 ZMAC>demo,demo=demo 0 ERRORS ZMAC> 0 ERRORS TOTAL C> The resulting listing file DEMO.PRN is as follows: PAGE NO. 1 1 ;Demonstration of ZMAC assembly language 2 ;syntax and resulting object code 3 ; 4 ;declare imported symbol before use 5 GLOBAL OMICRON 6 ;declare exported symbol before definition 7 GLOBAL ALPHA 8 ; 9 ;Equal sign rather than "EQU", 10 ;and colon is illegal 0001= 11 ONE = 1 12 ;using local symbol '0000 0700' 13 DW SIGMA 14 ;lower case is synonymous '0002 0700' 15 dw sigma '0004 0C00' 16 DW MU 17 ;both colon and whitespace (blank, tab, 18 ;or CRLF) are required after label '0006: 00 19 ALPHA: DB 0 '0007: 20 SIGMA: 21 ;using "extended alphabet" 22 ;in symbol names '0007: 01 23 _BETA: DB 1 '0008: 0F 24 BE_TA: DB 15 '0009: 02 25 .GAMMA: DB 2 '000A: 03 26 $DELTA: DB 3 '000B: 04 27 %EPSILON: DB 4 28 ; "EF" is optional '000C: 05 29 MU: DEFB 5 '000D: 0600 30 NU: DEFW 6 31 ; '000F: 32 RHO: DS 16 33 ;precedence used in 34 ;evaluating expressions '001F 07 35 DB 1+2*3 '0020? 0000 36 DW OMICRON '0022 88 37 DB 88H 38 ;single or double quotes around string 39 ;(double either to insert into string) '0023 4A6F6527 40 DB 'Joe''s mom' '002C 20226861 41 db " ""hates"" chocolate" '003E? 00 42 DB OMEGA '003F 88 43 DB 88H 44 ;declare exported symbol after definition 45 GLOBAL RHO 46 ;declare imported symbol after use 47 GLOBAL OMEGA 0 ERRORS PAGE NO. 1 Addresses and data values subject to relocation are marked with single quotes. Imported values are marked with question marks. FORMAT OF .OBJ FILE The following information was gleaned from inspection of the source code of the assembler and linker, and output generated by the assembler. It didn't come from Bruce Mallett, so any errors aren't his fault. - Jim Van Zandt The relocatable file created by ZMAC consists of a module record, a series of data records, symbol records, and set address records, and is terminated by an end of module record. An end of module record has the format: DB 2,0 A module start record has the format: LGH1: DB NEXT1-LGH1 ;# bytes in record DB 1 ;signals MODULE record DB YY ;descriptor bits (see below) DB 'FREEMONT' ;optional module name NEXT1: A set address record is generated for each DEFS or DS opcode. It has the effect of resetting the linker's program counter. It has the format: LGH2: DB NEXT2-LGH2 ;# bytes in record DB 2 ;signals SET ADDRESS record DB YY ;descriptor bits DW XXXX ;new value for program ; counter NEXT2: A data record has the following format: LGH3: DB NEXT3-LGH3 ;# bytes in record DB 3 ;signals DATA record DS 28 ;one bit is set for each word ;of data requiring relocation. DB 23,34,17,...,1BH ;1 to 224 bytes of data. NEXT3: A symbol record is used to import or export a global symbol. It has the format: LGH4: DB NEXT4-LGH4 ;# bytes in record DB 4 ;signals SYMBOL record DB YY ;descriptor bits DW XXXX ;if defined here, XXXX is the value of ; the symbol. If not defined here, XXXX ; is the address requiring the symbol. ; The value of the symbol will be added ; to the word at XXXX. In either case, ; if "relocatable", then XXXX is with ; respect to the beginning of the module. DB 'GANDOLF' ;the symbol NEXT4: In the above records, the "descriptor bits" are defined as follows: bit 0 if word rather than byte bit 1 if defined here bit 2 if global rather than local bit 3 if relocatable rather than absolute bit 4 if value of symbol is to be shifted left by 3 bits. The "shift left 3 bits" note is used when the bit number in a SET, BIT, or RES instruction is an imported symbol. In those instructions, the bit number field is in bits 3 through 5 of a byte. Note that it is always characteristic of a use, never a definition, of a symbol. The object code corresponding to the above assembly listing is: C>dump demo.obj DUMP version 00.05 RECORD: 0 0000 0301 002D 03A8 0000-0000 0000 0000 0000 ...-.(.......... 0010 0000 0000 0000 0000-0000 0000 0000 0000 ................ 0020 0007 0007 000C 0000-010F 0203 0405 0600 ................ 0030 0502 0A1F 000C 0405-2000 4F4D 4943 524F ........ .OMICRO 0040 4E0A 0404 3E00 4F4D-4547 413F 0300 0000 N...>.OMEGA?.... 0050 0000 0000 0000 0000-0000 0000 0000 0000 ................ 0060 0000 0000 0000 0000-0007 0000 884A 6F65 .............Joe 0070 2773 206D 6F6D 2022-6861 7465 7322 2063 's mom "hates" c RECORD: 1 0080 686F 636F 6C61 7465-0088 0B04 0B0A 0024 hocolate.......$ 0090 4445 4C54 4108 0402-0100 4F4E 4508 040F DELTA.....ONE... 00A0 0F00 5248 4F0B 040B-0900 2E47 414D 4D41 ..RHO......GAMMA 00B0 0D04 0B0B 0025 4550-5349 4C4F 4E0A 040B .....%EPSILON... 00C0 0700 5349 474D 410A-040F 0600 414C 5048 ..SIGMA.....ALPH 00D0 410A 040B 0800 4245-5F54 4107 040B 0C00 A.....BE_TA..... 00E0 4D55 0704 0B0D 004E-550A 040B 0700 5F42 MU.....NU....._B 00F0 4554 4102 0000 0000-0000 0000 0000 0000 ETA............. The first byte of relocation bits in the first data record (relative address 0005 in the file) is A8 hex, or 10101000 binary, signifying that words beginning at bytes 0, 2, and 4 among the following data bytes must be relocated. The last nine bytes displayed are extraneous, since the end of module record is at 00F3 and 00F4. For more information, see the source files. POTENTIAL IMPROVEMENTS Handle multiple program counters, such as one each for "code", "initialized data", and "uninitialized data". Permit "EQU" as well as "=". Make colons optional after either equated symbols or labels. Make "ORG" a synonym for "AORG". BUGS A file name can't include a '-'. AUTHOR Bruce Mallett