MAC80 User's guide Bruce Tanner Cerritos College 11110 Alondra Blvd. Norwalk, CA 90650 Cerritos@USC-ECL.ARPA CHAPTER 1 INTRODUCTION MAC80 is an 8085/Z80 cross assembler for the DECsystem-10, which also runs on the DECSYSTEM-20 under the compatability package. This document describes the use of the assembler and the syntax of the source file to be used by the assembler. Some attempt has been made to make MAC80 compatible with Macro-80 from Microsoft and MAC/RMAC from Digital Research; the differences between MAC80 and these other assemblers are described in appendix A. 1.1 MAC80 SOURCE MAC80 is made from three files, 1. M80UNV.MAC - The universal file containing symbol definitions 2. MAC80.MAC - The command scanner 3. MAC80A.MAC - The parser/code generator some of the macros require MACTEN.UNV which in turn requires JOBDAT.UNV. 1.2 OUTPUT MAC80 can generate an object file, a list file and a symbol file. 1. The object (.HEX) file is a Mostek (Intel) hex format file. 2. The list (.LST) file shows the code generated by the source lines. A cross-reference listing may optionally be included. 3. The symbol (.SYM) file contains a list of the symbols defined in the source file for use with SID/ZSID. MAC80 generates absolute location code the same as ASM and MAC. Macro-80 programs that use ASEG will generate compatible code. MAC80 also generates relocatable format .HEX files in the Mostek hex format only; not INTRODUCTION Page 1-2 the Microsoft format. See appendix B for a description of this format. CHAPTER 2 RUNNING MAC80 After invoking MAC80 (.R MAC80 or @MAC80), it will display an asterisk prompt. The command line for MAC80 consists of four fields, labeled: Object,List=Source/Switch 2.1 SOURCE The source field has the format Device:Filename.Ext[Proj,Prog]. The Device and Filename are limited to 6 characters, the Ext to 3 characters, SFDs are not supported. If the device is omitted, DSK: is used, if the extension is omitted, .M80 is used, if the PPN is omitted, your current path is used. 2.2 OBJECT The Object field has the format Device:Filename.Ext (6:6.3). If the device is omitted DSK: is used, if the filename is omitted the source filename is used, if the extension is omitted .HEX is used. 2.3 LIST The List field has the format Device:Filename.Ext (6:6.3). If the Device is omitted DSK: is used, if the filename is omitted the source filename is used, if the extension is omitted .LST is used. 2.4 SWITCH The switch field(s) may be placed anywhere in the command line. There are two switches: RUNNING MAC80 Page 2-2 1. /C - Add a cross-reference listing to the List file. 2. /S - Generate a Symbol file with the Source filename and a .SYM ext. /C will create a List file if none was requested. 2.5 COMMAND LINE SYNTAX To assemble the source with an object file of the same name, you only need to enter the source file name: *Source or *=Source To assemble the source with an object file of the same name and a list file of the same name, you may enter: *,=Source 2.6 CCL MODE MAC80 can be invoked with the COMPILE command if the line X MAC80,M80,MAC80,,HEX,,= is placed in the language definition macro in COMPIL.MAC. Tops-20 users will need to modify the EXEC. CHAPTER 3 SOURCE FILE SYNTAX 3.1 SOURCE LINES Each line of the source consists of the following fields: Label: Operator Arg,Arg...Arg ;Comment each of the fields is optional. If the operator is an EQU or MACRO, the label must not have a colon. Some examples: FALSE EQU 0 START: LXI SP,STACK ;SET UP THE STACK DB 1,2,3,4 NOP ;NOOP Labels must be followed by a colon. For compatibility with Macro-80, two colons may be used, but the label is not treated any differently. 3.2 COMMENTS Comments begin with a semicolon and end with a carriage return. Long comments can be contained in the .COMMENT pseudo-op. 3.3 SYMBOLS 1. Symbols may be any length, but only the first twelve characters are significant. 2. The legal symbol characters are A-Z a-z 0-9 $ . ? @ _ 3. A symbol must not start with a digit. SOURCE FILE SYNTAX Page 3-2 4. Lower case characters are automatically converted to upper case. 3.4 OPCODES MAC80 supports two instruction sets: 8085 and Z80. By default, MAC80 starts in 8085 mode; the .Z80 pseudo-op must be used before any Z80 opcodes will be understood. Opcodes may also be macro names. See chapter 5 for information about macros. 3.5 EXPRESSIONS MAC80 opcodes and pseudo-ops will accept arbitrary expressions as their arguments. Expressions are one or more operands (symbols, numbers, character constants or 8085 opcodes) seperated by operators (arithmetic or logical). 3.5.1 Operands Operands may be numbers, strings, character constants, symbols, 8085 opcodes or expressions. Operands (except strings) generate 16 bits of data. 3.5.2 Numbers A number is always evaluated as decimal unless one of the following notations are used: nnnnB Binary nnnnO Octal nnnnQ Octal nnnnH Hexadecimal Hexadecimal numbers must start with a digit. A dollar sign may be imbedded in a number for legibility. For example: 1100$1010B generates 0CA hex. SOURCE FILE SYNTAX Page 3-3 3.5.3 Strings The DB or DEFB pseudo-ops will accept zero or more characters delimited by quotation marks. Either single (') or double (") quotes may be used, but they are not interchangeable. For example: DB "'Howdy', he said" generates the string 'Howdy', he said To be compatible with Macro-80, two quotes in a row will generate a single occurrence of that quote. For example: DB """Howdy"", he said" generates the string "Howdy", he said 3.5.4 Character Constants Character constants are zero, one or two characters between quote marks. They generate a 16 bit value and may be used in expressions. For example: LXI B,'AB'+1 generates 01 43 41 However, only single character constants are allowed in the DB (DEFB) pseudo-op (where two character constants aren't necessary). Quoted character strings are character constants only if the expression has more than one operand. (E.g. 'A'+1 has a character constant, generating 16 bits of data. 'A' is a string, generating 8 bits of data.) 3.5.5 Symbols A symbol may be used as an operand in an expression. The value of the symbol is used when the expression is evaluated. There is one special symbol that may not be defined by the source program. The dollar sign ($) is the current program counter symbol. When used in an expression, the current PC symbol is evaluated to be the address of the next instruction or data byte to be assembled. SOURCE FILE SYNTAX Page 3-4 3.5.6 8085 Opcodes An 8085 opcode may be used as as operand. Only opcodes that generate one byte may be used. If the opcode uses more than one symbol, the opcode must be enclosed in parentheses. 8085 opcodes are not legal in Z80 mode. 3.5.7 Expressions Parenthesized expressions may be used as operands in expressions. Expression evaluation will always be performed on parenthesized sub-expressions before an operator is used. Because the Z80 instruction mnemonics use parentheses to distinguish between addresses and immediate values, parentheses may not be used at the start of expressions in Z80 mode. Instead, angle brackets <> may be used to form sub-expressions. 3.5.8 Operators The following operators are allowed in expressions. Unary operators use the next operand as their argument. HIGH, LOW, NOT, NUL and unary minus are unary operators. HIGH Returns the high byte of the next operand. It is equivalent to ( AND 0FF00H) SHR 8. LOW Returns the low byte of the next operand. It is equivalent to AND 0FFH. NOT Complements the value of the next operand. NUL Returns true (0FFFFH) if the next operand was not specified when the macro was invoked, otherwise it returns false (0). This operator is only applicable in macro definitions. - Unary minus. Returns the negative value of the next operand. The rest of the operators are binary; that is, they are placed between two operands. + Returns the sum of the two operands. - Returns the difference of the two operands. * Returns the product of the two operands. / Returns the integer part of the quotient of the two operands. SOURCE FILE SYNTAX Page 3-5 MOD Returns the remainder (modulo) part of the quotient. AND Returns a bitwise logical AND of the two operands. OR Returns a bitwise logical OR of the two operands. XOR Returns a bitwise logical Exclusive OR of the two operands. SHR Shift right the value of the previous operand by the integer value specified by the next operand. SHL Shift left the value of the previous operand by the integer value specified by the next operand. The rest of the operators return true (0FFFFH) or false (0). EQ Returns true if the two operands are equal. NE Returns true if the two operands are not equal. LT Returns true if the previous operand is less than the next operand. LE Returns true if the previous operand is less than or equal to the next operand. GT Returns true if the previous operand is greater than the next operand. GE Returns true if the previous operand is greater than or equal to the next operand. The order of precedence for the operators is: 1. NUL 2. NOT, Unary minus 3. *, /, MOD, SHR, SHL 4. +, - 5. EQ, NE, LT, LE, GT, GE 6. AND 7. OR, XOR 8. HIGH, LOW CHAPTER 4 PSEUDO-OPS Pseudo-ops direct the assembler to perform some function. Below are the MAC80 pseudo-ops: ASEG This pseudo-op does nothing. It is for compatibility with Macro-80 programs. SET ASET is set to the value of . SET may not be used in Z80 mode because SET is a Z80 instruction; use ASET instead. EQU is set to the value of . If already has a value other than , an error will be generated. DB [,...] DEFB [,...] DB stores the least eight bits value(s) of the expression(s) in memory at the current PC location. may also be a string. DW [,...] DEFW [,...] DW stores the value(s) of the expressions(s) in memory at the current PC location. Each is evaluated as a 16 bit value, and is stored with the low byte first, then the high byte. DS DEFS DS reserves bytes in memory. The contents of this space are undefined. END [] PSEUDO-OPS Page 4-2 The END pseudo-op specifies that the end of the program has been reached. If is present, its value is placed in the last record (01 type) in the object file. If END is found in a MACLIB or INCLUDEd file, it is ignored. EXT [,...] EXTRN [,...] EXTERN [,...] The EXTERN pseudo-op declares that the name(s) in the list are external to the current module. Only the first 6 characters of an external name are passed to the linker. OCT HEX OCT causes the listing to be printed with octal numbers to be printed in the address and code fields. HEX switches it back to hexadecimal. HEX is the default. INT [,...] INTERN [,...] PUBLIC [,...] The PUBLIC pseudo-ops declares the name(s) in the list as internal to the current module and therefore available of use by other programs using the EXTERN pseudo-op. Only the first 6 characters of the internal symbol name are passed to the linker. INCLUDE MACLIB INCLUDE inserts the source from an alternate file into the source file. MACLIB is the same as Include except that neither the inserted text nor its generated code is listed. The file is assumed to be on DSK: in your default path. If the extension is omitted, .LIB is assumed. ORG ORG changes the value of the location counter to be . ORG starts the generation of non-relocatable code. CP/M programs should start with an ORG 100H. .PHASE .PHASE tells the assembler to assemble the code as if it were at , but to leave the code at the current location counter. PAGE [] PAGE will cause a form feed to be placed in the list file. If is included, the current page size is changed to be . The default page size is 60. PSEUDO-OPS Page 4-3 TITLE TITLE specifies a title to be used in each page heading of the list file. SUBTTL SUBTTL specifies the subtitle to be used after the title in each page heading of the list file. .Z80 .8080 .Z80 specifies that the assembler be placed in Z80 mode. .8080 is used to place the assembler back in 8085 mode. 8085 mode is the default. .COMMENT .COMMENT is used to make long comments. Anything between the delimiters is ignored. .LALL .SALL .XALL .XLIST .XMAC These pseudo-ops are for listing control: .LALL list everything. .XALL don't list code generated after the first line (6 bytes) of a DB or DW. This is the default. .XMAC XALL plus don't list the text expansion of macros. .SALL XMAC plus don't list code generated by macros. .XLIST shut off listing. .PRINTX .PRINTX will list the text on the terminal during the second pass. IF IFN If is non-zero, the statements within the conditional block are assembled. IFE PSEUDO-OPS Page 4-4 If is zero, the statements within the conditional block are assembled. ELSE ELSE will toggle the assembly state of the current conditional block. If it is off, ELSE will start assembly. If it is on, ELSE will turn off assembly. ENDIF ENDIF terminates the conditional block started by IF, IFN or IFE. CHAPTER 5 MACROS Macro definition allows you to invoke a block of text with parameter substitution. The macro text is started with either the macro definition pseudo-op or the repeat pseudo-op and ends with the ENDM pseudo-op. Macros may be nested. 5.1 MACRO DEFINITION Macros are defined with the MACRO pseudo-op. MACRO [[,...]] . . . ENDM is the name of the macro and is used to invoke the macro after it has been defined. has the same limitations as any other symbol. is a place holder that is replaced by an actual parameter when the macro is invoked. Dummy parameters must be seperated by commas. 5.2 MACRO INVOCATION To use a macro, use the macro name as if it were a pseudo-op: [[,...]] Each is substituted for the corresponding in the macro definition. If a parameter is enclosed by angle brackets (<>), everything within the angle brackets will be passed as one parameter. MACROS Page 5-2 5.3 REPEAT The repeat pseudo-op specifies a block of text that is to be repeated for the number of times specified. Repeated blocks don't have names and don't do parameter substitution. Repeated blocks are defined with the REPT pseudo-op. REPT . . . ENDM The text between the REPT and the ENDM is repeated times. 5.4 MACRO TERMINATION 5.4.1 ENDM ENDM tells the assembler to end the definition of a macro or a repeat. 5.4.2 EXITM The EXITM pseudo-op is used inside a macro or repeat block to terminate the expansion of the macro or repeat before the end of the macro or repeat block has been reached. EXITM is usually used in conjunction with a conditional pseudo-op. If an EXITM is encountered inside a nested macro, the outer macro continues to be expanded. 5.5 LOCAL SYMBOLS The LOCAL pseudo-op is used inside a macro or repeat block to declare certain symbols to be local to each expansion of the macro. Each time the local symbol is defined in an expansion, it is given a unique symbol starting with ..0000. A LOCAL statement must precede the use of the local symbol. EXAMPLE: FOO MACRO X,Y LOCAL SKIP JMP SKIP X: DB Y SKIP: ENDM MACROS Page 5-3 FOO DATA,<10,20,30> will generate: JMP ..0000 DATA: DB 10,20,30 ..0000: 5.6 SPECIAL SYMBOLS ;; Comments preceded by two semicolons is not saved as part of the macro expansion. A comment preceded by one semicolon will be included as part of the macro expansion. & Ampersand concatenates text or symbols (including dummy parameters) inside macro expansions. % If a percent sign precedes a parameter of a macro invocation, the expression is evaluated and the numeric string of its value is passed to the macro expansion. EXAMPLE: FOO MACRO X DB X ENDM SYM EQU 100Q FOO SYM will generate DB SYM FOO %SYM will generate DB 64 APPENDIX A DIFFERENCES BETWEEN MAC80 AND MACRO-80 This is just a quick list of some of the more obvious differences between MAC80 and Microsoft's Macro-80. MAC80 cannot generate Macro-80 .REL files. There are no ENTRY, COMMON, DSEG or CSEG pseudo-ops. MAC80 checks for opcodes and pseudo-ops before macros. Macro-80 checks for macros before opcodes/pseudo-ops. Macro-80 allows X'nnnn' as a hexadecimal number. MAC80 only allows nnnnH. MAC80 doesn't have the TYPE operator and the operator precedence is slightly different. MAC80 does not have the DC, .RADIX, .REQUEST, .SFCOND, .LFCOND, .TFCOND, .CREF, .XCREF pseudo-ops. MAC80 does not have the IRP and IRPC repeat pseudo-ops. MAC80 does not have the IFT, COND, IFF, IF1, IF2, IFDEF, IFNDEF, IFB, IFNB, IFIDN, IFDIF or ENDC conditional pseudo-ops. APPENDIX B MOSTEK HEX FILE FORMAT Each record of an object module begins with a delimiter (colon or dollar sign) and ends with a carriage return and line feed. A colon (:) is used for data records and end-of-file indicator for Intel compatibility. A dollar sign ($) is used for records containing relocation information and linking information. An Intel loader will ignore such information and allow loading of non-relocatable, non-linkable programs. All information is ASCII. Each record is defined by a "type". The type appears in the 8th and 9th bytes of the record and can take the following values: 00 - data record 01 - end-of-file 02 - internal symbol 03 - external symbol 04 - relocation information Data record (type 00) Byte 1 Colon (:) delimiter. 2-3 Number of (binary) bytes of data in this record. The maximum is 32 binary bytes (64 ASCII bytes). [This is not a LINK80 restriction.] 4-5 Most significant byte of start address of data. 6-7 Least significant byte of start address of data. 8-9 ASCII zeros. This is the "record type" for data. last 2 Checksum of all bytes except the delimiter, carriage return and line feed. The checksum is the negative of the binary sum of all bytes in the record. CRLF End-of-file record (type 01) Byte 1 Colon (:) delimiter. 2-3 ASCII zeros. 4-5 Most significant byte of the transfer address of the program. This transfer address appears as the argument of the "END" statement of a program. 6-7 Least significant byte of the transfer address of the program. 8-9 Record type 01. CRLF Internal symbol (type 02) Byte 1 Dollar sign ($) delimiter 2-7 Up to 6 ASCII characters of the internal symbol name. The name is MOSTEK HEX FILE FORMAT Page B-2 left justified blank filled. 8-9 Record type 02. 10-13 Address of the internal symbol, most significant byte first. 14-15 Binary checksum CRLF External symbol (type 03) Byte 1 Dollar sign ($) delimiter 2-7 Up to 6 ASCII characters of the external symbol name. The name is left justified blank filled. 8-9 Record type 03. 10-13 Last address which uses the external symbol. This is the start of a linked list (terminated by FFFF) of all locations using the external symbol. The most significant byte is first. 14-15 Binary checksum CRLF Relocating record (type 04) The addresses in the program which must be relocated are explicitly defined in these records. Up to 16 addresses (64 ASCII characters) may be defined in each record. [This is not a LINK80 restriction.] Byte 1 Dollar sign ($) delimiter 2-3 Number of (binary) bytes of addresses. The maximum is 32 binary bytes (64 ASCII characters or 16 addresses). [This is not a LINK80 restriction.] 4-7 ASCII zeros. 8-9 Record type 04. 10- Address which must be relocated. Last 2 Binary checksum. CRLF